diff --git a/handbook/handbook.sgml b/handbook/handbook.sgml index 92e952404c..8fcb8ddf0d 100644 --- a/handbook/handbook.sgml +++ b/handbook/handbook.sgml @@ -1,168 +1,167 @@ - + %authors; ]> FreeBSD Handbook <author> <name>The FreeBSD Documentation Project</name> </author> - <date>June 30, 1995</date> + <date>July 7, 1995</date> <abstract>Welcome to FreeBSD! This handbook covers the installation and day to day use of <bf>FreeBSD Release 2.0.5</bf>. This manual is a <bf>work in progress</bf> and is the work of many individials. Many sections do not yet exist and some of those that do exist need to be updated. If you are interested in helping with this project, send email to &a.jfieber; or to the FreeBSD Documentation Project mailing list <tt><doc@freebsd.org></tt>. </abstract> <toc> <!-- ************************************************************ --> <part><heading>Basics</heading> <chapt><heading>Introduction</heading> &nutshell; &history; &relnotes; - <sect><heading>* FreeBSD now and in the future</heading> &install; &basics; <chapt><heading>Installing applications</heading> <sect><heading>* Installing packages</heading> &ports; &porting; <!-- ************************************************************ --> <part><heading>System Administration</heading> <chapt><heading>* Reconfiguring the Kernel<label id="kernelconfig"></heading> <!-- &kernelconfig; --> <chapt><heading>Users, groups and security</heading> <sect><heading>* DES, MD5 and Crypt</heading> <sect><heading>* S/Key</heading> &kerberos; <sect><heading>* Firewalls</heading> <chapt><heading>* Printing</heading> <chapt><heading>* The X-Window System</heading> <chapt><heading>Managing hardware</heading> &scsi; <sect><heading>* Adding and reconfiguring disks</heading> <sect><heading>* Tapes and backups</heading> <sect><heading>* Serial ports</heading> <sect><heading>* Sound cards</heading> <!-- ************************************************************ --> <part><heading>Network Communications</heading> <chapt><heading>Basic Networking</heading> <sect><heading>* Ethernet basics</heading> <sect><heading>* Serial basics</heading> <sect><heading>* Hardwired Terminals</heading> &dialup; <chapt><heading>PPP and SLIP</heading> &ppp; &slipc; &slips; <chapt><heading>Advanced networking</heading> <sect><heading>* Gateways and routing</heading> &nfs; <sect><heading>* Yellow Pages/NIS</heading> &diskless; <sect><heading>* ISDN</heading> <chapt><heading>* Mail</heading> <!-- ************************************************************ --> <part><heading>Advanced topics</heading> ¤t; &ctm; ⊃ &kerneldebug; &submitters; &booting; &memoryuse; &troubleshooting; <!-- ************************************************************ --> <part><heading>Appendices</heading> &bibliography; &eresources; &hw; &glossary; </book> </linuxdoc> diff --git a/handbook/history.sgml b/handbook/history.sgml index dbaec6629d..8b747ea407 100644 --- a/handbook/history.sgml +++ b/handbook/history.sgml @@ -1,44 +1,95 @@ -<!-- $Id: history.sgml,v 1.2 1995-06-30 17:37:38 jfieber Exp $ --> +<!-- $Id: history.sgml,v 1.3 1995-07-07 22:25:51 jfieber Exp $ --> <!-- The FreeBSD Documentation Project --> -<sect><heading>A brief history of FreeBSD<label id="history"></heading> +<sect><heading>A brief history of FreeBSD, according to Jordan Hubbard<label id="history"></heading> <p><em>Contributed by &a.jkh;</em>. -The FreeBSD project was started somewhere in the early part of 1992 as -an outgrowth of the "Unofficial 386BSD Patchkit" by the patchkit's -last 3 coordinators: Nate Williams, Jordan Hubbard and Rod Grimes. +The FreeBSD project had its genesis in the early part of 1992, +partially as an outgrowth of the "Unofficial 386BSD Patchkit" by the +patchkit's last 3 coordinators: Nate Williams, Rod Grimes and myself. David Greenman and Julian Elischer were also lurking in the background around this time, though they didn't come fully into the project until -a month or two after it was more or less officially launched. The -original working title of the project was also "386BSD 0.5" or "386BSD -Interim", a reference to the fact that the original goal was to -produce an intermediate snapshot of 386BSD. - -386BSD was Bill Jolitz's operating system, which had been up to -that point suffering rather severely from neglect, a consequence -of which was to cause the patchkit to swell ever more -uncomfortably with each passing day. The 3 ex-patchkit -coordinators were all in agreement that the patchkit had to die. -It was rapidly outliving its usefulness, and it would be a far -easier thing to simply do another 386BSD release with all patches -applied and a number of its aging utilities updated. - -These plans came to a rude halt when Bill Jolitz suddenly decided -to withdraw his sanction from the project. It didn't take the -team members long to decide that the goal remained worthwhile -even without Bill's support, and so they adopted the name -"FreeBSD", which was coined by David Greenman. - -Once it also became clear that the project was on the road to -perhaps even becoming a reality, Jordan Hubbard contacted Walnut -Creek CDROM with an eye towards improving FreeBSD's distribution -channels to those many unfortunates without easy access to the -Internet. Walnut Creek CDROM not only supported the idea of -distributing FreeBSD on CD, but went so far as to provide the -project with a machine to work on and a fast Internet connection. -Without Walnut Creek CDROM's almost unprecidented degree of faith -in what was, at the time, a completely unknown project, it is -very unlikely that FreeBSD would have gotten as far, as fast, as -it has today. +a month or two after it was more or less officially launched. Our +original goal was to produce an intermediate snapshot of 386BSD in +order to fix a number of problems with it that the patchkit mechanism +just wasn't capable of solving. Some of you may remember the early +working title for the project being "386BSD 0.5" or "386BSD Interim" +in reference to that fact. + +386BSD was Bill Jolitz's operating system, which had been up to that +point suffering rather severely from almost a year's worth of neglect. +As the patchkit swelled ever more uncomfortably with each passing day, +we were in unanimous agreement that something had to be done and +decided to try and assist Bill by providing this interim "cleanup" +snapshot. Those plans came to a rude halt when Bill Jolitz suddenly +decided to withdraw his sanction from the project and without any +clear indication of what would be done instead (and it was, in fact, +to be another full year before he was even heard from in public +again!). + +It didn't take us long to decide that the goal remained worthwhile +even without Bill's support, and so we adopted the name "FreeBSD", +which was coined by David Greenman. Our initial objectives were set +after consulting with the system's current users and once it became +clear that the project was on the road to perhaps even becoming a +reality, I contacted Walnut Creek CDROM with an eye towards improving +FreeBSD's distribution channels to those many unfortunates without +easy access to the Internet. Walnut Creek CDROM not only supported +the idea of distributing FreeBSD on CD but went so far as to provide +the project with a machine to work on and a fast Internet connection. +Without Walnut Creek CDROM's almost unprecidented degree of faith in +what was, at the time, a completely unknown project, it is in fact +very unlikely that FreeBSD would have gotten as far, as fast, as it +has today. + +The first CDROM (and general net-wide) distribution was FreeBSD 1.0, +released in December of '93. This was based on the 4.3 BSD Lite +("Net/2") tape from U.C. Berkeley with many components provided by +386BSD and the Free Software Foundation. It was a fairly reasonable +success for a first offering, and we followed this release with the +highly successful FreeBSD 1.1 version in May of 1994. + +Around this time, some rather unexpected storm clouds formed on our +horizon as Novell and U.C. Berkeley settled their long-running lawsuit +over the legal status of the Berkeley Net/2 tape. A condition of that +settlement was U.C. Berkeley's concession that large parts of Net/2 +was "encumbered" code and property of Novell, who had in turn aquired +it from AT&T some time previously. What Berkeley got in return was +Novell's "blessing" that the 4.4 Lite release, when it was finally +released, would be declared unencumbered and all existing Net/2 users +would be strongly encouraged to switch. This included us, and we were +given until the end of July 1994 to stop shipping our own Net/2 based +product. Under the terms of that agreement, were were allowed one +last release before the deadline and that became FreeBSD 1.1.5.1, the +culmination of our year's work with Net/2 and generally considered by +many to be a significant project milestone for stability and general +performance.. + +We then set about the arduous task of literally re-inventing ourselves +with a completely new and rather incomplete set of 4.4 Lite bits. The +"Lite" releases were light in part because Berkeley's CSRG removed +large chunks of code required for actually making a bootable running +system out of it due to various legal requirements and the fact that +the Intel port of 4.4 was highly incomplete. It took us until +December of 1994 to make this transition, and in January of 1995 we +released FreeBSD 2.0 to the net and on CDROM. Despite being still +more than a little rough around the edges, the release was a +significant success and has since been followed by the more robust and +easier to install FreeBSD 2.0.5 release in June of 1995. + +Where to from here? Well, we intend to release FreeBSD 2.1 sometime +in September of 1995 and have reasonable expectations that it will +meet or exceed all of the standards for quality we set with FreeBSD +1.1.5.1 back in July of 1994. From there, we'll probably go to a +two-track scheme with a "stable" branch of FreeBSD and an +"experimental" branch, where development can continue at its usually +rapid pace without penalizing those who just want a stable, working +system without too much excitement. We also intend to focus on any +remaining areas of weakness, like documentation or missing drivers, +and steadily increase the overall quality and feature set of the +system well into 1996 and beyond. + + Jordan + diff --git a/handbook/nutshell.sgml b/handbook/nutshell.sgml index 3c7fc43cf3..a7ef47ac3c 100644 --- a/handbook/nutshell.sgml +++ b/handbook/nutshell.sgml @@ -1,148 +1,147 @@ -<!-- $Id: nutshell.sgml,v 1.3 1995-06-30 17:37:44 jfieber Exp $ --> +<!-- $Id: nutshell.sgml,v 1.4 1995-07-07 22:25:52 jfieber Exp $ --> <!-- The FreeBSD Documentation Project --> <sect><heading>FreeBSD in a nutshell<label id="nutshell"></heading> <p>FreeBSD is a state of the art operating system for personal computers based on the Intel CPU architecture, which includes the 386, 486 and Pentium processors (both SX and DX versions). Intel compatible CPUs from AMD and Cyrix are supported as well. FreeBSD provides you with many advanced features previously available only on much more expensive computers. These features include: <itemize> <item><bf>Preemptive multitasking</bf> with dynamic priority adjustment to ensure smooth and fair sharing of the computer between applications and users.</item> <item><bf>Multiuser</bf> access means that many people can use a FreeBSD system simultaneously for a variety of things. System peripherals such as printers and tape drives are also properly shared between all users on the system.</item> <item>Complete <bf>TCP/IP networking</bf> including SLIP, PPP, NFS and NIS support. This means that your FreeBSD machine can interoperate easily with other systems as well act as an enterprise server, providing vital functions such as NFS (remote file access) and e-mail services or putting your organization on the Internet with WWW, ftp, routing and firewall (security) services.</item> <item><bf>Memory protection</bf> ensures that applications (or users) cannot interfere with each other. One application crashing will not affect others in any way.</item> <item>FreeBSD is a <bf>32-bit</bf> operating system and was designed as such from the ground up.</item> <item>The industry standard <bf>X Window System</bf> (X11R6) provides a graphical user interface (GUI) for the cost of a - common VGA card and monitor.</item> + common VGA card and monitor and comes with full sources.</item> <item><bf>Binary compatibility</bf> with many programs built for SCO, BSDI, NetBSD, and 386BSD.</item> <item>Hundreds of <bf>ready-to-run</bf> applications are available from the FreeBSD <bf>ports</bf> and <bf>packages</bf> collection. Why search the net when you can find it all right here?</item> <item>Thousands of additional and <bf>easy-to-port</bf> applications available on the Internet. FreeBSD is source code compatible with most popular commercial Unix systems and thus most applications require few, if any, changes to compile.</item> <item>Demand paged <bf>virtual memory</bf> and `merged VM/buffer cache' design efficiently satisfies applications with large appetites for memory while still maintaining interactive response to other users.</item> <item><bf>Shared libraries</bf> (the Unix equivalent of MS-Windows DLLs) provide for efficient use of disk space and memory.</item> <item>A full compliment of <bf>C</bf>, <bf>C++</bf> and <bf>Fortran</bf> development tools. Many additional - languages for research and advanced development are - available as well in the ports and packages - collection.</item> + languages for advanced research and development are + also available in the ports and packages collection.</item> <item><bf>Source code</bf> for the entire system means you have the greatest degree of control over your environment. Why be locked into a proprietary solution and at the mercy of your vendor when you can have a truly Open System?</item> <item>Extensive <bf>on-line documentation</bf>.</item> <item><bf>And many more!</bf></item> </itemize> FreeBSD is based on the BSD 4.4-lite release from Computer Systems Research Group (CSRG) at the University of California at Berkeley, and carries on the distinguished tradition of BSD systems development. In addition to the fine work provided by CSRG, the FreeBSD Project has put in many thousands of hours in fine tuning the system for maximum performance and reliability in real-life load situations. As many of the commercial giants struggle to - field PC operating systems with such features, performance, + field PC operating systems with such features, performance and reliability, FreeBSD can offer them <bf>now</bf>! The applications to which FreeBSD can be put are truly limited only by your own imagination. From software - development to factory automation. Inventory control to - azimuth correction of remote satellite antennae, if it can - be done with a commercial UNIX product, then it's more than + development to factory automation, inventory control to + azimuth correction of remote satellite antennae; if it can + be done with a commercial UNIX product then it's more than likely that you can do it with FreeBSD, too! FreeBSD also benefits significantly from the literally thousands of high quality applications developed by research centers and - universities around the world, and often available at low - (to no) cost. Commercial applications are also available + universities around the world, often available at little + to no cost. Commercial applications are also available and appearing in greater numbers every day. Because the source code for FreeBSD itself is generally available, the system can also be customized to an almost unheard of degree for special applications or projects, and in ways not generally possible with operating systems from most major commercial vendors. Here is just a sampling of some of the applications in which people are currently using FreeBSD: <itemize> <item><bf>Internet Services:</bf> The robust TCP/IP networking built into FreeBSD makes it an ideal platform for a variety of Internet services such as: <itemize> <item>FTP servers</item> <item>World Wide Web servers</item> <item>Gopher servers</item> <item>Electronic Mail servers</item> <item>USENET News</item> <item>Bulletin Board Systems</item> <item>And more...</item> </itemize> You can easily start out small with an inexpensive 386 class PC and upgrade as your enterprise grows.</item> <item><bf>Education:</bf> Are you a student of computer science or a related engineering field? There is no better way of learning about operating systems, computer - architecture and networks than the hands on, under the + architecture and networking than the hands on, under the hood experience that FreeBSD can provide. A number of freely available CAD, mathematical and graphic design packages also make it highly useful to those who's primary interest in a computer is to get <em>other</em> work done!</item> <item><bf>Research:</bf> With source code for the entire system available, FreeBSD is an excellent platform for research in operating systems as well as other branches of computer science. FreeBSD's freely available nature also makes it possible for remote groups to collaborate on ideas or shared development without having to worry about - special licensing agreements, or with limitations on what - may be discussed in certain forums.</item> + special licensing agreements or limitations on what + may be discussed in open forums.</item> <item><bf>Networking:</bf> Need a new router? A name server (DNS)? A firewall to keep people out of your internal network? FreeBSD can easily turn that unused 386 or 486 PC sitting in the corner into an advanced router with sophisticated packet filtering capabilities. </item> - <item><bf>X Window workstation:</bf> FreeBSD is an excellent + <item><bf>X Window workstation:</bf> FreeBSD is a fine choice for an inexpensive X terminal solution, either using the freely available XFree86 server or one of the excellent commercial servers provided by X Inside. Unlike an X terminal, FreeBSD allows many applications to be run locally, if desired, thus relieving the burden on a - central server. Additionally, FreeBSD can boot - "diskless" making individual workstations even cheaper + central server. FreeBSD can even boot + "diskless", making individual workstations even cheaper and easier to administer.</item> <item><bf>Software Development:</bf> The basic FreeBSD system comes with a full compliment of development tools included the renowned GNU C/C++ compiler and debugger. </item> </itemize> diff --git a/handbook/ports.sgml b/handbook/ports.sgml index 5e955ae41c..32b40bc288 100644 --- a/handbook/ports.sgml +++ b/handbook/ports.sgml @@ -1,240 +1,231 @@ -<!-- $Id: ports.sgml,v 1.4 1995-06-30 17:37:45 jfieber Exp $ --> +<!-- $Id: ports.sgml,v 1.5 1995-07-07 22:25:52 jfieber Exp $ --> <!-- The FreeBSD Documentation Project --> <sect><heading>The Ports collection<label id="ports"></heading> <p><em>Contributed by &a.gpalmer; and &a.jkh;.</em> Unfortunately, there are more variations of UN*X than most people know of, and hence not all software for UN*X available on the Internet will work on all versions of UN*X (in fact, I can guarantee it!). Hence, some software needs modifications to work under some UN*Xs. The process of making those modifications is known as ``porting'' and the result known as a ``port'' (not to be confused with the sockets on the back of your computer!). <sect1><heading>What is the FreeBSD Ports Collection?</heading> -<p> People who (allegedly) know what they are doing have automated the -process of ``porting'' software to FreeBSD, and the result is the -Ports Collection. The general idea is that a combination of various -programming tools available in the base FreeBSD installation will -allow you to fetch the port from a FreeBSD mirror site, type ``make'' -and get the fully working program. +<p> When 2.0 was released, the FreeBSD Project decided to attempt to +automate the process of ``porting'' such software to FreeBSD, and the +result is the Ports Collection. The general idea was that a +combination of various programming tools already available in the base +FreeBSD installation would allow you to simply type `make' for a given +port and have the underlying ports mechanism automatically fetch the +port from a FreeBSD mirror site, apply any special configuration +knowledge to it and then build it to result in a fully working version +of the program. The ports collection itself normally doesn't have any of the original source code necessary for the compilation in the tree, just those shell scripts, Makefiles and source code ``diffs'' that are -necessary to compile the program under FreeBSD. This is meant to keep -the entire system down to a manageable size, and the current system -has over 100 ports in the master source tree, and yet a compressed tar -file of that tree is about 2 megabytes (all the source code needed is -over 100Mb's!). +necessary to configure and compile the program under FreeBSD. This +keeps the entire system down to a manageable size, with the current +system having over 300 ports in the master source tree and yet taking +up no more than a few tens of megabytes. <sect1><heading>How does the system compile with no source code?</heading> -<p> A ports' Makefile automatically looks in a central location on -your system (usually /usr/ports/distfiles, though this value can be +<p> The Makefile for a port automatically looks in a central location +on your system (usually /usr/ports/distfiles, though this value can be customized) for the associated set of original distribution files that -have been ``ported''. These are generally provided at various places -on the Internet, though if you have a CDROM distribution of FreeBSD -then you've already got them available on your CD for ease of use. -See section 3.1 if you have such a CD distribution, otherwise skip to -section 3.2. - -<!-- -3.1 Compiling ports from CD - - Type something profound here. ---> - -<sect2><heading>Compiling ports using an Internet connection</heading> +have been ``ported''. Those not found locally are searched for +wherever they're generally provided on the Internet. If you have a +CDROM distribution of FreeBSD then you've already got them available +on your CD for ease of use. See <ref id="ports:cd" +name="Compiling ports from CD"> if you have such a CDROM +distribution, otherwise skip to <ref id="ports:inet" +name="Compiling ports using an Internet connection">. + +<sect1><heading>Compiling ports from CDROM<label id="ports:cd"></heading> + +<p>The ports collection is easy to use from CDROM, and all you need do +is create a "link tree" to it using the ``lndir'' command that comes +with the <em>XFree86</em> distribution. Find a location with some +free space and create a directory there, then invoking the lndir +command with the full pathname of the ``ports'' directory on the CDROM +as an argument (this might be, for example, something like: ``lndir +/cdrom/ports''). Then you can build ports directly off the CDROM by +building them in the link tree you've created. + +<sect1><heading>Compiling ports using an Internet connection<label id="ports:inet"></heading> <p> The ports collection can also use an auto-fetch system to keep your ports collection source tree up to date, updating the central ``distfiles'' version for you the next time you compile the port. - Of course, this always assumes you have a permanent network link, -or don't mind heavy usage of your telephone. If you don't want heavy -network usage when you compile your ports tree, you can pre-fetch the + Of course, this assumes you have a permanent network link or don't +mind heavy usage of your telephone. If you don't want heavy network +usage when you compile your ports tree, you can pre-fetch the necessary tarballs beforehand and put them into /usr/ports/distfiles (or wherever DISTDIR points) by hand. A good way to see what files a port is going to need is to cd to that port's directory and do a ``make -n fetch'' to see what it does. You can also chose to get the source files either from the master FTP site as defined in the relevant Makefile (in the MASTER_SITES line), or some FreeBSD mirror site also carrying a set of distfiles, as does the master FTP site on ftp.FreeBSD.org (aka ftp.cdrom.com) in the directory /pub/FreeBSD/ports/distfiles. Note that the files in that directory are not guarenteed to be kept up to date - this is a volunteer project! We can't make any guarantees about the mirror sites either - they are obviously under independant control and don't even have to mirror the distfiles directory. If you have a non-permanant link, you can fetch all the distfiles by going to the top of the tree and typing ``make fetch''. <sect1><heading>It doesn't work?!</heading> <p>Oh. You can do one of four (4) things : <enum> <item> Fix it yourself. Technical details can be found in the GUIDELINES file, available from URL ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/GUIDELINES <item> Gripe. This is done by e-mail *ONLY*! The people at Walnut Creek are in no way responsible for the functionality (or lack thereof) of the FreeBSD system as a whole, and especially the ports system, which is mainly contributed by 3rd parties. (If you don't believe me, check the catalogue, especially the line saying "We cannot offer tech-support on this product") The e-mail address is Ports@FreeBSD.org. Please include details of the port, where you got both the port source & distfile(s) from, and what the error was. Note: At time of writing, lang/Sather doesn't seem to work on Pentium machines due to the Intel Curse (aka the Floating Point Division Bug). Please don't tell us about this - gripe to Intel instead - it's their bug! <item> Forget it. This is the easiest for most - very few of the programs in ports can be classed as `essential'! <item> Grab the pre-compiled package from a ftp server. The ``master'' package collection is in: ftp://ftp.FreeBSD.org/pub/FreeBSD/packages/ though check your local mirror first, please! These are more likely to work (on the whole) than trying to compile from source, and a lot faster! </enum> <sect1><heading>I've ported a program and I want to make a port out of it. What now?</heading> <p> See the file GUIDELINES, in: ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/GUIDELINES This contains details of the procedure and structure involved. <sect1><heading>I've got a good port, what now?</heading> <p> Upload the fixed version to freefall.cdrom.com /pub/incoming or ftp.FreeBSD.org /pub/FreeBSD/incoming and send e-mail to ports@FreeBSD.org with the filename and details. Someone on the all-volunteer `ports committee' will (hopefully) look it over and commit it to the ports collection if they like the looks of it. -<sect1><heading>Things go funny during the fetch stage of compilation!</heading> - -<p> We know. Please don't blame us. There is a program called `ncftp' -which is used instead of the normal ftp as it can do so-called -``background'' or ``batch'' transfers, ideal for this situation. -Unfortunately it can do strange things, and has crashed at least one -machine (during circumstances stranger than most, I'll admit, but it -was still responsible). Hopefully a future release of ncftp will fix -these problems (it is not maintained by the main FreeBSD team, but a -third party, who is I believe aware of its shortcomings) - - <sect1><heading>I want to leave the compile going overnight, but some ports don't like this.</heading> <p> There is a way around this. Before starting the compilation, type: <verb> setenv BATCH yes # (if you use csh/tcsh) or BATCH=yes; export BATCH # (for sh/bash) </verb> - This should miss out ports which need user interaction. Unfortunately, -ncftp doesn't know about this trick, and can often screw up and ask -stupid questions in unattended batch mode. See (7). + This should skip ports which need user interaction to build. To compile those ports left out by doing the above, using a different login shell (or unsetting the above BATCH variable), set the INTERACTIVE variable instead (you can use the same statements as above except replace ``BATCH'' with ``INTERACTIVE'') and re-run make. This should now compile only those ports which will definitely ask for user interaction. <sect1><heading>The ports collection is weak. What can I do to help?</heading> <p> First read the bsd.port.mk file (which may be found in /usr/share/mk/) and the associated bsd.port.subdir.mk file. A lot of the weirdness can be explained properly in there (most of the current weirdness is due to the lack of assumptions about anything, which is necessary due to the generic nature of these files). Also check that you have an up-to-date copy, as the file can change from minute to minute. A reasonably up-to-date copy can be found in: <url url="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/mk"> If you find that you still need to go in there and alter things, by all means do so, and then send the diffs to ports@FreeBSD.org if you'd like them to be a part of the default distribution. Please also remember that any changes must respect backwards-compatability with any and all older Makefiles, unless you want a real nightmare of /usr/ports munging ahead of you! Large scale changes will generally not be warmly welcomed unless all the existing makefiles work without alteration. Sorry! <sect1><heading>This FAQ is weak. What can I do?</heading> <p> Send changes to ports@FreeBSD.org. Changes are most welcome! This FAQ is also very green and should be considered no more than a `good start' for now. Authors? You can come out of hiding any time now! :-) <sect1><heading>How do I get more information on all the ports?</heading> <p> One good method is to cd to the top of the ports tree (say /usr/ports) -and type something like: +and type: <verb> - make describe | sed -e '/===/D' -e 's;/usr/ports/;;' | expand -40 + make print-index </verb> -The ``make describe'' will try to extract the one-line description from -each port, and the ``sed'' will delete the extraneous output. ``expand'' -just makes it a little more readable (sort of - you may want to season -the output of this more to taste). - +This will print a summary of all ports in the tree. <sect1><heading>I've heard of a new checksum system. What is this for?</heading> <p> For various reasons, when using FTP over the Internet to obtain the source code, you may not always end up with the same copy of the code that the origional porter worked from, and this can lead to problems. So a simple checksumming system has been employed to try and highlight problems in this area. To check the entire system, go to the top of the ports tree (defaults to /usr/ports) and type <verb> make checksum </verb> This will give a report on the validity of the files you have FTP'd. If some are missing, the system will attempt to retrieve them before running the checksum routine. The same technique can be applied to a single port. The system will complain if there is no pre-computed checksum available for that port. Not all ports currently have checksums, but this should be cured soon. Some older versions of the system don't recognise the ``checksum'' target. In that case, try the command <verb> make check-md5 </verb> (``check-md5'' was the pre-cursor to the ``checksum'' target). If neither work, get the latest copies of bsd.port.mk and bsd.port.subdir.mk from <url url="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/mk"> and install them in /usr/share/mk. This will get you the latest version of the ports system. diff --git a/handbook/submitters.sgml b/handbook/submitters.sgml index 8828474021..709f9fd0b4 100644 --- a/handbook/submitters.sgml +++ b/handbook/submitters.sgml @@ -1,236 +1,236 @@ -<!-- $Id: submitters.sgml,v 1.4 1995-06-30 17:37:51 jfieber Exp $ --> +<!-- $Id: submitters.sgml,v 1.5 1995-07-07 22:25:54 jfieber Exp $ --> <!-- The FreeBSD Documentation Project --> <chapt><heading>Contributing to FreeBSD<label id="submitters"></heading> <p><em>Contributed by &a.jkh;.</em> This guide is intended for those who are moderately familar with FreeBSD and are now to the point where they have some locally developed customizations or fixes to the system which they'd like to incorporate back into the mainstream sources, thus saving the work of having to re-integrate the changes for each subsequent FreeBSD release. Submitting something to the FreeBSD project is also an excellent way of getting your -code seriously <em>tested</em>! Many people have developed an original concept -far beyond what they might have envisioned at the start just due to the +code seriously <em>tested</em>! Many people have seen an original concept +develop far beyond what they might have envisioned at the start just due to the flood of feedback and ideas generated by the many thousands of users of FreeBSD. Contributions are also what FreeBSD lives and grows from, and so your contributions are very important to the continued survival of this communal effort of ours---we're very glad to see you reading this -documentation! +document! Submissions to FreeBSD can generally be classified into four catagories: <enum> <item>Ideas, general suggestions, bug reports. <item>Addition, deletion, renaming or patching of existing sources. <item>Significant contribution of a large body of independant work. <item>Porting of freely available software. </enum> A submission in <em>any</em> of these catagories is highly welcomed as they are each, in their own way, quite significant to the project. <sect><heading>Ideas and suggestions</heading> <p>An idea, suggestion or fix can be communicated in one of the following ways: <itemize> <item>An idea or suggestion of general technical interest should be mailed to <tt><hackers@freebsd.org></tt>. Likewise, people with an interest in such things (and a tolerance for a <em>high</em> volume of mail!) may subscribe to the hackers mailing list by sendimg mail to <tt><majordomo@freebsd.org></tt>. See <ref id="eresources:mail" name="mailing lists"> for more information about this and other mailing lists. <item>An actual bug report should be filed by using the <tt>send-pr(1)</tt> program. This will prompt you for various fields to fill in. Simply go to the fields surrounded by <tt><></tt>'s and fill in your own information in place of what's suggested there. You should receive confirmation of your bug report and a tracking number. Keep this tracking number and use it in any subsequent correspondence. If you do not receive confirmation in a timely fashion (3 days to a week, depending on your email connection) or are, for some reason, unable to use the <tt>send-pr(1)</tt> command, then you may also file a bug report by sending mail to <tt><bugs@freebsd.org></tt>. </itemize> <sect><heading>Changes to the existing code</heading> <p>An addition or change to the existing source code is a somewhat trickier affair and depends a lot on how far out of date you are with the current state of the core FreeBSD development. There is a special on-going release of FreeBSD known as ``FreeBSD-current'' and made available in a variety of ways for the convenience of developers who wish to actively work on the system. See <ref id="current" name="Staying current with FreeBSD"> for more information about getting and using FreeBSD-current. Working from older sources unfortunately means that your changes may sometimes be too obsolete to use, or too divergent to allow for easy re-integration. This can be minimized somewhat by subscribing to the <tt><announce@freebsd.org></tt> mailing list, among others, where periodic announcements concerning the current state of the system are made. If you see a change being proposed for which you have a better solution, by all means come forward with your contribution and we will do our very best to evaluate it fairly and perhaps integrate it if it is indeed a better solution. Assuming that you can manage to secure fairly up-to-date sources to base your changes on, the next step is to produce a set of diffs to send to the FreeBSD maintainers for evaluation and possible adoption. This is done with the <tt>diff(1)</tt> command, with the FreeBSD maintainers preferring to receive diffs in `context diff' form. For example: <tscreen><verb> diff -c <oldfile> <newfile> </verb></tscreen> or <tscreen><verb> diff -c -r <olddir> <newdir> </verb></tscreen> See the man page for <tt>diff(1)</tt> for more details on producing both context and recursive context diffs. Once you have a set of diffs that are capable of taking a copy of the original code and bringing it to a state identical to the ``new'' sources (you may test this with the <tt>patch(1)</tt> command), you should bundle them up in an email message and send it, along with a brief description of what the diffs are for, to <tt><hackers@freebsd.org></tt>. Someone will very likely get back in touch with you in 24 hours or less, assuming of course that your diffs are interesting! If your changes don't express themselves well as diffs alone (e.g. you've perhaps added, deleted or renamed files as well) then you may be better off bundling any new files, diffs and instructions for deleting/renaming any others into a <tt>tar</tt> file and running the <tt>uuencode(1)</tt> program on it before sending the output of that to <tt><hackers@freebsd.org></tt>. See the man pages on <tt>tar(1)</tt> and <tt>uuencode(1)</tt> for more info on bundling files through the mail this way. If your change is of a potentially sensitive nature, for example you're unsure of copyright issues governing its further distribution, or you're simply not ready to release it without a tighter review first, then you should send it to <tt><core@freebsd.org></tt> rather than <tt><hackers@freebsd.org></tt>. The core mailing list reaches a much smaller group of people who do much of the day-to-day work on FreeBSD. Note that this group is also <em>very busy</em> and so you should only mail to them in cases where mailing to hackers truly is impractical. <sect><heading>Contributions of new code</heading> <p>In the case of a significant contribution of a large body work, or the addition of an important new feature to FreeBSD, it becomes almost always necessary to either send changes as uuencoded tar files or upload them to our ftp site <url url="ftp://freefall.cdrom.com/pub/FreeBSD/incoming"> where users may log in anonymously and upload their work or download the work-in-progress files left by others. When working with large amounts of code, the touchy subject of copyrights also invariably comes up. Acceptable copyrights for code included in FreeBSD are: <enum> <item>Contributions under the BSD copyright are greatly preferred due to its ``no strings attached'' nature and general attractiveness to commercial enterprises who might then be inclined to invest something of their own into FreeBSD. <item>Contributions under the GNU Public License, or ``GPL''. This is not quite as popular a solution for us, due to the amount of extra effort demanded of anyone using the code for commercial purposes. However, given the sheer quantity of GPL'd code we currently require (compiler, assembler, text formatter, etc), it would be silly to pretend that we couldn't deal with the GPL at all and so we have become more willing to accept code with either the BSD or the GPL copyright. Code under the GPL also goes into a different part of the tree, that being <tt>/sys/gnu</tt> or <tt>/usr/src/gnu</tt>. <item>Contributions coming under any other type of copyright must be carefully reviewed before their inclusion into FreeBSD will even be considered. Contributions for which particularly restrictive commercial copyrights apply are generally rejected, though the authors are always free to make the changes available through their own channels. </enum> To place such a copyright on your work, place the following text at the very beginning of every source code file you wish to protect, replacing the text between the `<tt>%%</tt>' with the appropriate information. <tscreen><verb> Copyright (c) %%proper_years_here%% %%your_name_here%%, %%your_state%% %%your_zip%%. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer as the first lines of this file unmodified. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. All advertising materials mentioning features or use of this software must display the following acknowledgment: This product includes software developed by %%your_name_here%%. 4. The name of the author may not be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY %%your_name_here%% ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL %%your_name_here%% BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - $Id: submitters.sgml,v 1.4 1995-06-30 17:37:51 jfieber Exp $ + $Id: submitters.sgml,v 1.5 1995-07-07 22:25:54 jfieber Exp $ </verb></tscreen> For your convenience, a copy of this text can be found in <tt>/usr/share/examples/etc/bsd-style-copyright</tt>. <sect><heading>Porting of software</heading> <p>The porting of freely available software, while perhaps not as gratifying as developing your own package from scratch, is still a vital part of FreeBSD's growth and of great usefulness to those who wouldn't otherwise know where to turn for it. All ported software is organized into a hierarchy know as ``the ports collection''. This collection enables a new user to get a complete overview of what's available in a short time, and with a logical framework. The ports collection also saves considerable space by not actually containing the the majority of the sources being ported. See <ref id="ports" name="The ports collection"> for more information on using the ports collection and <ref id="porting" name="Porting applications"> for guidelines on creating new ports. You may also send mail to <tt><ports@freebsd.org></tt>. Whichever way you decide to contribute, we hope you'll find it an enjoyable process and also realize how valuable your contributions are to the project! FreeBSD is one of those great projects where the more we all put in, the more we all get back out of it again, and with enough steady contributions it begins to aquire a momentum of its own. It is through such momentum that mountains are moved! diff --git a/handbook/sup.sgml b/handbook/sup.sgml index 0025a73961..a2c02f4d80 100644 --- a/handbook/sup.sgml +++ b/handbook/sup.sgml @@ -1,91 +1,91 @@ -<!-- $Id: sup.sgml,v 1.4 1995-07-06 14:25:01 jfieber Exp $ --> +<!-- $Id: sup.sgml,v 1.5 1995-07-07 22:25:54 jfieber Exp $ --> <!-- The FreeBSD Documentation Project --> <sect><heading>SUP<label id="sup"></heading> <p><em>Contributed by &a.jkh; and &a.gclarkii;.</em> SUP is a network based software update tool developed at CMU. The purpose of this document is get the beginner up and running with sup. <sect1><heading>Getting setup</heading> <p>First off you will need to pick up the sup binaries. The easiest way of doing this is to grab the sup.tgz package from: <verb> ftp://ftp.FreeBSD.ORG:/pub/FreeBSD/packages/sup.tgz </verb> Install the sup package using pkg_add and add the following line to your /etc/services file: <verb> sup 871/tcp #sup </verb> SUP gets the information it needs to run from a configuration file called a supfile. This file tells sup what collections it will be updating and/or installing and where they go. The supfile in this directory will sup both the source and ports collection - look for the blank line seperating the two collections; if you don't want ports, you can simply delete all the ports entries. If you're inside the United States, you may also uncomment the `secure' collection line to grab the DES code. If you're outside the U.S., you should NOT sup this code from FreeBSD.ORG as this will violate U.S. export restrictions. Simply sup everything *but* the secure collection and then go look on "braae.ru.ac.za", where it's available for anonymous ftp for those outside the U.S. Any other distributions you do not wish to receive can be commented out with a # at the begining of the distribution line. Once this is setup, you're ready to go. To start sup type: <verb> sup supfile </verb> If you wish to see what sup is doing "verbosely", give it the -v option, like so: <verb> sup -v supfile </verb> Thats all there is to it! Remember that if you're running current, which is what you will have if you sup, please join the freebsd-current mailing list. You should also be sure to read <ref id="current" name="Staying current with FreeBSD"> for important information on just what we can and cannot do for you as a -current user. <sect1><heading>Description of FreeBSD SUP distributions</heading> <p>For the main FreeBSD distribution: <verb> base: /usr/src/... misc files at the top of /usr/src bin: /usr/src/bin system binaries secure: /usr/src/secure DES Sources. U.S./Canada only! etc: /usr/src/etc system files games: /usr/src/games games gnu: /usr/src/gnu sources under the GNU Public License include: /usr/src/include include files sys: /usr/src/sys kernel sources lib: /usr/src/lib libraries libexec: /usr/src/libexec more system binaries share: /usr/src/share various shared resources sbin: /usr/src/sbin even more system binaries usrbin: /usr/src/usr.bin user binaries usrsbin: /usr/src/usr.sbin that's it for the system binaries </verb> And for the ports collection: <verb> ports-base: /usr/ports/... misc files at the top of /usr/ports ports-editors: /usr/ports/editors text editors ports-game: /usr/ports/games games ports-lang: /usr/ports/lang programming languages ports-mail: /usr/ports/mail mail software ports-math: /usr/ports/math math software ports-net: /usr/ports/net networking software ports-news: /usr/ports/news USENET news software ports-print: /usr/ports/print printing software ports-russian: /usr/ports/russian russian software ports-shells: /usr/ports/shells various UN*X shells ports-utils: /usr/ports/utils miscellaneous utilities ports-x11: /usr/ports/x11 X11 software -</verb> \ No newline at end of file +</verb> diff --git a/handbook/troubleshooting.sgml b/handbook/troubleshooting.sgml index 73bbc36257..128d7cfed3 100644 --- a/handbook/troubleshooting.sgml +++ b/handbook/troubleshooting.sgml @@ -1,185 +1,69 @@ -<!-- $Id: troubleshooting.sgml,v 1.2 1995-06-30 17:37:53 jfieber Exp $ --> +<!-- $Id: troubleshooting.sgml,v 1.3 1995-07-07 22:25:55 jfieber Exp $ --> <!-- The FreeBSD Documentation Project --> <chapt><heading>Troubleshooting<label id="troubleshooting"></heading> <p>The following tips and tricks may help you turn a failing (or failed) installation attempt into a success. Please read them carefully. <sect> <heading>Hardware conflict or misconfiguration</heading> <p><descrip> <tag>Problem:</tag> A device is conflicting with another or doesn't match the kernel's compiled-in IRQ or address. <tag>Cause:</tag> While most device drivers in FreeBSD are now smart enough to match themselves to your hardware settings dynamically, there are a few that still require fairly rigid configuration parameters to be compiled in (and matched by the hardware) before they'll work. We're working hard to eliminate as many of these last hold-outs as we can, but it's not always as easy as it looks. <tag>Solution:</tag> There are several possible solutions. The first, and easiest, is to boot the kernel with the <tt>-c</tt> flag. When you see the initial boot prompt (from floppy or hard disk), type: <tscreen><verb> /kernel -c </verb></tscreen> This will boot just past the memory sizing code and then drop into a dynamic kernel configuration utility. Type `<tt>?</tt>' at the prompt to see a list of commands. You can use this utility to reset the IRQ, memory address, IO address or a number of other device configuration parameters. You can also disable a device entirely if it's causing problems for other devices you'd - much rather have work. Note that this only affects the - kernel being booted temporarily, it does not write out - the information to the kernel so that these settings are - permanantly altered (this would be actually rather hard). - If you reboot, you'll have to make the same changes - again. The goal of the <tt>-c</tt> utility is to get you - up far enough to be able to download the appropriate - sources and configure and rebuild a kernel more specific - to your needs. + much rather have work. Another solution is, obviously, to remove the offending hardware or simply strip the system down to the bare essentials until the problem (hopefully) goes away. Once you're up, you can do the same thing mentioned above---compile a kernel more suited to your hardware, or incrementally try to figure out what it was about your original hardware configuration that didn't work. </descrip> -<sect> - <heading>My floppy-tape drive isn't probed</heading> - - <p>Cause: Last-minute problems with this driver caused it - to be disabled by default. - - Solution: Boot with -c (described above) and set the - flags value of fdc0 to 1. This will re-enable the floppy - tape driver. Sorry, but it was causing problems for - other people! - <sect> <heading>When I boot for the first time, it still looks for /386bsd!</heading> <p>Cause: You still have the old FreeBSD 1.x boot blocks on your boot partition. Solution: You should re-enter the installation process, invoke the (F)disk editor and chose the (W)rite option. This won't hurt an existing installation and will make sure that the new boot blocks get written to the drive. If you're installing for the first time, don't forget to (W)rite out your new boot blocks! :-) -<sect> - <heading>I want to boot FreeBSD off the second drive. It - doesn't!</heading> - - <p>Cause: FreeBSD will actually install just fine on a - drive other than 0 (the first drive), and the boot - manager will even allow you to select it, but the boot - blocks rather pathologically assume 0. This should be - fixed in 2.1. - - Solution: Easy - follow these steps: - - 1. Select the first (0) drive from the (F)disk editor - and write out the boot manager with the (B) option. - This will enable the boot manager that allows you to - actually boot off the other drive. - - 2. Exit the fdisk editor for the first drive and and - re-enter it again for the drive you wish to install - on. Set up a partition on this drive, or select - (A)ll for the entire drive. - - 3. Enter the disklabel editor and allocate space on - your second drive as normal. Proceed with the - installation. - - 4. Once you've installed on the disk and are going to - reboot from the hard disk, enter the following at - the boot prompt: - - hd(1,a)/kernel - - This will ensure that you really boot from the second - drive. If you've actually installed on a drive other - than 1 (the 3rd or 4th drive?), substitute that number - in for the above. You will need to enter this EVERY - time you reboot from the hard disk. If you're feeling - brave and have a srcdist + the requisite experience, - you can hack the boot blocks in: - - /usr/src/sys/i386/boot/biosboot - - So that this drive you're booting from is hard-coded. - Recompile the boot blocks and reinstall them on your - drive with `disklabel -B ...' You can then have the - default Do The Right Thing. - -<sect> - <heading>Newfs crashes, requesting that blocksize be 32K</heading> - - <p>Cause: You have your SCSI controller configured to - translate geometries for disks >1GB in size. - - Solution: Turn such translation OFF in your controller's - BIOS setup! FreeBSD has no problems with disks >1GB just - so long as the root partition starts and ends BELOW - cylinder 1024. This is a PC hardware limitation. - -<sect> - <heading>FreeBSD won't boot off the hard disk</heading> - - <p>Cause: Root partition does not start and end below - cylinder 1024. - - Solution: See solution for newfs crashes, or move your - root partition. This limitation holds true for ANY - operating system you wish to boot from your hard drive. - - -<sect> - <heading>FreeBSD still won't boot off the hard disk</heading> - - <p>Cause: No boot code is installed in sector 1. - - Solution: Chose the Write MBR (B)oot code in the FDISK - editor. - -<sect> - <heading>Nope, FreeBSD's still not booting from the hard - disk</heading> - - <p>Cause: BIOS disk geometry different from that used when - installing FreeBSD. - - Solution: With IDE drives, pay careful attention to the - geometry information that FreeBSD prints out when it's - first booting off the floppy. Use this geometry in your - BIOS setup or use the BIOS geometry when you install - FreeBSD. Either way, they have to match. - - With SCSI drives, the values they report is most often - bogus and cannot be used. In this situation, the SCSI - controller is performing geometry translation and it's - probably wise to assume a default of 64 heads, 32 sectors - and 1MB/cylinder. Use these values when you install - FreeBSD. See above comments concerning newfs failures - for more info.