diff --git a/handbook/Makefile b/handbook/Makefile index 801dc6a427..8e6cca402d 100644 --- a/handbook/Makefile +++ b/handbook/Makefile @@ -1,15 +1,15 @@ -# $Id: Makefile,v 1.7 1995-12-07 13:22:12 jkh Exp $ +# $Id: Makefile,v 1.8 1996-02-11 00:16:06 jkh Exp $ SRCS= authors.sgml basics.sgml bibliography.sgml boothelp.sgml SRCS+= booting.sgml contrib.sgml crypt.sgml ctm.sgml current.sgml dialup.sgml SRCS+= diskless.sgml dma.sgml eresources.sgml esdi.sgml SRCS+= firewalls.sgml glossary.sgml goals.sgml SRCS+= handbook.sgml history.sgml hw.sgml install.sgml kerberos.sgml SRCS+= kernelconfig.sgml kerneldebug.sgml memoryuse.sgml SRCS+= mirrors.sgml nfs.sgml nutshell.sgml SRCS+= porting.sgml ports.sgml ppp.sgml printing.sgml relnotes.sgml SRCS+= routing.sgml scsi.sgml sections.sgml -SRCS+= skey.sgml slipc.sgml slips.sgml submitters.sgml sup.sgml -SRCS+= troubleshooting.sgml userppp.sgml +SRCS+= skey.sgml slipc.sgml slips.sgml stable.sgml submitters.sgml sup.sgml +SRCS+= synching.sgml troubleshooting.sgml userppp.sgml .include diff --git a/handbook/current.sgml b/handbook/current.sgml index 02ee6a3190..79054dab54 100644 --- a/handbook/current.sgml +++ b/handbook/current.sgml @@ -1,166 +1,166 @@ - + Staying current with FreeBSD

Contributed by &a.jkh;. What is FreeBSD-current?

FreeBSD-current is, quite literally, nothing more than a daily snapshot of the working sources for FreeBSD. These include work in progress, experimental changes and transitional mechanisms that may or may not be present in the next official release of the software. While many of us compile almost daily from FreeBSD-current sources, there are periods of time when the sources are literally un-compilable. These problems are generally resolved as expeditiously as possible, but whether or not FreeBSD-current sources bring disaster or greatly desired functionality can literally be a matter of which part of any given 24 hour period you grabbed them in! Under certain circumstances we will sometimes make binaries for parts of FreeBSD-current available, but only because we're interested in getting something tested, not because we're in the business of providing binary releases of current. If we don't offer, please don't ask! It takes far too much time to do this as a general task. Who needs FreeBSD-current?

FreeBSD-current is made generally available for 3 primary interest groups: Members of the FreeBSD group who are actively working on some part of the source tree and for whom keeping `current' is an absolute requirement. Members of the FreeBSD group who are active testers, willing to spend time working through problems in order to ensure that FreeBSD-current remains as sane as possible. These are also people who wish to make topical suggestions on changes and the general direction of FreeBSD. Peripheral members of the FreeBSD (or some other) group who merely wish to keep an eye on things and use the current sources for reference purposes (e.g. for reading, not running). These people also make the occasional comment or contribute code. What is FreeBSD-current NOT?

A fast-track to getting pre-release bits because you heard there's some cool new feature in there and you want to be the first on your block to have it. A quick way of getting bug fixes. In any way ``officially supported'' by us. We do our best to help people genuinely in one of the 3 ``legitimate'' FreeBSD-current categories, but we simply do not have the time to help every person who jumps into FreeBSD-current with more enthusiasm than knowledge of how to deal with experimental system software. This is not because we're mean and nasty people who don't like helping people out (we wouldn't even be doing FreeBSD if we were), it's literally because we can't answer 400 messages a day and actually work on FreeBSD! I'm sure that, if given the choice between having us answer lots of questions or continuing to improve FreeBSD, most of you would vote for us improving it. Using FreeBSD-current

Join the freebsd-current and cvs-all mailing lists. This is not just a good idea, it's essential. If you aren't on freebsd-current, you won't see the comments that people are making about the current state of the system and thus will probably end up stumbling over a lot of problems that others have already found and solved. Even more importantly, you will miss out on potentially critical information (e.g. ``Yo, Everybody! Before you rebuild /usr/src, you must rebuild the kernel or your system will crash horribly!"). The cvs-all mailing list will allow you to see the commit log entry for each change as it's made along with any pertinent information on possible side-effects. - To join these lists, send mail to `majordomo@FreeBSD.ORG' - and say: + To join these lists, send mail to + and say: subscribe current subscribe cvs-all In the body of your message. Optionally, you can also say `help' and Majordomo will send you full help on how to subscribe and unsubscribe to the various other mailing lists we support. Grab the sources from ftp.FreeBSD.ORG. You can do this in three ways: Using the CTM facility described below. Unless you have a good TCP/IP connection at a flat rate, this is the way to do it. Use the CMU `sup' program (Software Update Protocol), also described below. This is the second most recommended method, since it allows you to grab the entire collection once and then only what's changed from then on. Many people run sup from cron and keep their sources up-to-date automatically. Use ftp. The source tree for FreeBSD-current is always "exported" on: - - ftp.FreeBSD.ORG:~ftp/pub/FreeBSD/FreeBSD-current - - We use `wu-ftpd' which allows compressed/tar'd grabbing + + We also use `wu-ftpd' which allows compressed/tar'd grabbing of whole trees. e.g. you see: usr.bin/lex You can do: ftp> cd usr.bin ftp> get lex.tar.Z And it will get the whole directory for you as a compressed tar file. Essentially, if you need rapid on-demand access to the source and communications bandwidth is not a consideration, use sup or ftp. Otherwise, use CTM. If you're grabbing the sources to run, and not just look at, then grab all of current, not just selected portions. The reason for this is that various parts of the source depend on updates elsewhere, and trying to compile just a subset is almost guaranteed to get you into trouble. Before compiling current, read the Makefile in /usr/src carefully. You should at least run a `make world' the first time through as part of the upgrading process. Reading freebsd-hackers will keep you up-to-date on other bootstrapping procedures that sometimes become necessary as we move towards the next release. Be active! If you're running FreeBSD-current, we want to know what you have to say about it, especially if you have suggestions for enhancements or bug fixes. Suggestions with accompanying code are received most enthusiastically! diff --git a/handbook/handbook.sgml b/handbook/handbook.sgml index f9893c731b..e272d71130 100644 --- a/handbook/handbook.sgml +++ b/handbook/handbook.sgml @@ -1,157 +1,157 @@ - + %authors; %sections; ]> FreeBSD Handbook <author> <name>The FreeBSD Documentation Project</name> </author> <date>December 21, 1995</date> <abstract>Welcome to FreeBSD! This handbook covers the installation and day to day use of <bf>FreeBSD Release 2.1.0</bf>. This manual is a <bf>work in progress</bf> and is the work of many individuals. 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 the FreeBSD Documentation Project mailing list <tt><htmlurl url="mailto:doc@freebsd.org" name="<doc@freebsd.org>"></tt>. The latest version of this document is always available from the <url url="http://www.freebsd.org/" name="FreeBSD World Wide Web server">. </abstract> <toc> <!-- ************************************************************ --> <part><heading>Basics</heading> <chapt><heading>Introduction</heading> <p>FreeBSD is a 4.4 BSD Lite based operating system for Intel architecture (x86) based PCs. For an overview of FreeBSD, see <ref id="nutshell" name="FreeBSD in a nutshell">. For a history of the project, read <ref id="history" name="a brief history of FreeBSD">. To see a description of the latest release, read <ref id="relnotes" name="about the current release">. If you're interested in contributing something to the FreeBSD project (code, equipment, sacks of unmarked bills), please see about <ref id="submitters" name="contributing to FreeBSD">. &nutshell; &history; &goals; &relnotes; &install; &basics; <chapt><heading>Installing applications</heading> <sect><heading>* Installing packages</heading> &ports; <!-- ************************************************************ --> <part><heading>System Administration</heading> &kernelconfig; <chapt><heading>Users, groups and security</heading> &crypt; &skey; &kerberos; &firewalls; &printing; <chapt><heading>The X-Window System</heading> <p>Pending the completion of this section, please refer to documentation supplied by the <url url="http://www.xfree86.org/" name="The XFree86 Project, Inc">. &hw; <!-- ************************************************************ --> <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> <p>If your connection to the Internet is through a modem, or you wish to provide other people with dialup connections to the Internet using FreeBSD, you have the option of using PPP or SLIP. Furthermore, two varieties of PPP are provided: <em>user</em> (sometimes referred to as iijppp) and <em>kernel</em>. The procedures for configuring both types of PPP, and for setting up SLIP are described in this chapter. &userppp; &ppp; &slipc; &slips; <chapt><heading>Advanced networking</heading> &routing; &nfs; &diskless; <sect><heading>* Yellow Pages/NIS</heading> <sect><heading>* ISDN</heading> <chapt><heading>* Mail</heading> <!-- ************************************************************ --> <part><heading>Advanced topics</heading> ¤t; - &ctm; - ⊃ + &stable; + &synching; &submitters; &troubleshooting; &kerneldebug; <chapt><heading>FreeBSD internals</heading> &booting; &memoryuse; &dma; <!-- ************************************************************ --> <part><heading>Appendices</heading> &mirrors; &bibliography; &eresources; &contrib; <!-- &glossary; --> </book> </linuxdoc> diff --git a/handbook/sections.sgml b/handbook/sections.sgml index 34b19db2db..fd859d2523 100644 --- a/handbook/sections.sgml +++ b/handbook/sections.sgml @@ -1,46 +1,48 @@ -<!-- $Id: sections.sgml,v 1.7 1995-12-07 13:22:17 jkh Exp $ --> +<!-- $Id: sections.sgml,v 1.8 1996-02-11 00:16:15 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> <!-- Entities containing all the pieces of the handbook are --> <!-- defined here --> <!ENTITY bibliography SYSTEM "bibliography.sgml"> <!ENTITY basics SYSTEM "basics.sgml"> <!ENTITY booting SYSTEM "booting.sgml"> <!ENTITY contrib SYSTEM "contrib.sgml"> <!ENTITY ctm SYSTEM "ctm.sgml"> <!ENTITY current SYSTEM "current.sgml"> +<!ENTITY stable SYSTEM "stable.sgml"> <!ENTITY crypt SYSTEM "crypt.sgml"> <!ENTITY dialup SYSTEM "dialup.sgml"> <!ENTITY diskless SYSTEM "diskless.sgml"> <!ENTITY dma SYSTEM "dma.sgml"> <!ENTITY eresources SYSTEM "eresources.sgml"> <!ENTITY esdi SYSTEM "esdi.sgml"> <!ENTITY firewalls SYSTEM "firewalls.sgml"> <!ENTITY goals SYSTEM "goals.sgml"> <!ENTITY glossary SYSTEM "glossary.sgml"> <!ENTITY history SYSTEM "history.sgml"> <!ENTITY hw SYSTEM "hw.sgml"> <!ENTITY install SYSTEM "install.sgml"> <!ENTITY kerberos SYSTEM "kerberos.sgml"> <!ENTITY kernelconfig SYSTEM "kernelconfig.sgml"> <!ENTITY kerneldebug SYSTEM "kerneldebug.sgml"> <!ENTITY memoryuse SYSTEM "memoryuse.sgml"> <!ENTITY mirrors SYSTEM "mirrors.sgml"> <!ENTITY nfs SYSTEM "nfs.sgml"> <!ENTITY nutshell SYSTEM "nutshell.sgml"> <!ENTITY porting SYSTEM "porting.sgml"> <!ENTITY ports SYSTEM "ports.sgml"> <!ENTITY ppp SYSTEM "ppp.sgml"> <!ENTITY printing SYSTEM "printing.sgml"> <!ENTITY relnotes SYSTEM "relnotes.sgml"> <!ENTITY routing SYSTEM "routing.sgml"> <!ENTITY scsi SYSTEM "scsi.sgml"> <!ENTITY skey SYSTEM "skey.sgml"> <!ENTITY slipc SYSTEM "slipc.sgml"> <!ENTITY slips SYSTEM "slips.sgml"> <!ENTITY submitters SYSTEM "submitters.sgml"> <!ENTITY sup SYSTEM "sup.sgml"> +<!ENTITY synching SYSTEM "synching.sgml"> <!ENTITY troubleshooting SYSTEM "troubleshooting.sgml"> <!ENTITY userppp SYSTEM "userppp.sgml"> diff --git a/handbook/stable.sgml b/handbook/stable.sgml new file mode 100644 index 0000000000..f9b3c8f3be --- /dev/null +++ b/handbook/stable.sgml @@ -0,0 +1,109 @@ +<!-- $Id: stable.sgml,v 1.1 1996-02-11 00:16:17 jkh Exp $ --> +<!-- The FreeBSD Documentation Project --> + + +<chapt><heading>Staying stable with FreeBSD<label id="stable"></heading> + +<p><em>Contributed by &a.jkh;.</em> + +<!-- + + THE FREEBSD STABLE POLICY + +Last updated: $Date: 1996-02-11 00:16:17 $ + +This document attempts to explain the rationale behind +FreeBSD-stable, what you should expect should you decide to run it, +and states some prerequisites for making sure the process goes as +smoothly as possible. +--> + +<sect><heading>What is FreeBSD-stable?</heading> + +<p>FreeBSD-stable is our development branch for a more low-key and +conservative set of changes intended for our next mainstream release. +Changes of an experimental or untested nature do not go into this +branch (see <ref id="current" name="FreeBSD-current">). + +<sect><heading>Who needs FreeBSD-stable?</heading> + +<p>If you're a commercial user or someone who puts maximum stability of +their FreeBSD system before all other concerns, you should consider tracking +<em>stable</em>. This is especially true if you've installed the most +recent release (<htmlurl url="ftp://ftp.freebsd.org/pub/FreeBSD/2.1.0-RELEASE" +name="2.1.0-RELEASE"> at the time of this writing) since the <em>stable</em> +branch is effectively a bug-fix stream relative to the previous release. + +<p>Please note that the <em>stable</em> tree endevors, above all, to +be fully compilable and stable at all times, but we do occasionally +make mistakes (these are still active sources with quickly-transmitted +updates, after all). We also do our best to thoroughly test fixes in +<em>current</em> before bringing them into <em>stable</em>, but sometimes +our tests fail to catch every case. If something breaks for you in +<em>stable</em>, please let us know <em>immediately!</em> (see +next section). + +<sect><heading>Using FreeBSD-stable</heading> + + <p><enum><item> Join the freebsd-stable mailing list. This will + keep you informed of build-dependencies that may appear in + <em>stable</em> or any other issues requring special attention. + Developers will also make announcements in this mailing list when + they are contemplating some contraversal fix or update, giving + the users a chance to respond if they have any issues to raise concerning + the proposed change. + + To join this list, send mail to <htmlurl url="mailto:majordomo@FreeBSD.ORG" + name="majordomo@FreeBSD.ORG"> and say: +<verb> + subscribe freebsd-stable +</verb> + In the body of your message. Optionally, you can also say `help' + and Majordomo will send you full help on how to subscribe and + unsubscribe to the various other mailing lists we support. + + <item> Grab the sources from ftp.FreeBSD.ORG. You can do this in + three ways: + + <enum> + <item> Using the CTM facility described below. Unless you + have a good TCP/IP connection at a flat rate, this is + the way to do it. + + <item> Use the CMU `sup' program (Software Update + Protocol), also described below. + This is the second most recommended method, since it allows + you to grab the entire collection once and then only what's + changed from then on. Many people run sup from cron + and keep their sources up-to-date automatically. + + <item> Use ftp. The source tree for FreeBSD-stable is always + "exported" on: + <htmlurl url="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/FreeBSD-stable" + name="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/FreeBSD-stable"> + + <p>We also use `wu-ftpd' which allows compressed/tar'd grabbing + of whole trees. e.g. you see: +<verb> + usr.bin/lex +</verb> + You can do: +<verb> + ftp> cd usr.bin + ftp> get lex.tar.Z +</verb> + And it will get the whole directory for you as a compressed + tar file. + </enum> + + <item> Essentially, if you need rapid on-demand access to the source and + communications bandwidth is not a consideration, use sup or ftp. + Otherwise, use CTM. + + <item> Before compiling stable, read the Makefile in /usr/src + carefully. You should at least run a `make world' the first time + through as part of the upgrading process. + Reading freebsd-stable will keep you up-to-date on other bootstrapping + procedures that sometimes become necessary as we move towards the next + release. +</enum> diff --git a/handbook/sup.sgml b/handbook/sup.sgml index 4836e3622e..8fbff545bf 100644 --- a/handbook/sup.sgml +++ b/handbook/sup.sgml @@ -1,131 +1,132 @@ -<!-- $Id: sup.sgml,v 1.12 1996-02-06 23:41:01 asami Exp $ --> +<!-- $Id: sup.sgml,v 1.13 1996-02-11 00:16:18 jkh 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>Starting with FreeBSD 2.1, sup is supplied as part of the base system and no separate installation is required. SUP gets the information it needs to run from a configuration file called a supfile. This file should be found in <tt>/usr/share/examples/sup/standard-supfile</tt> for the standard distributions. This file tells sup what collections it will be updating and/or installing and where they go. This supfile will sup the current source collection. For ports please have a look at <tt>/usr/share/examples/sup/ports-supfile</tt>. If you are interested in obtaining the cvs files that make up the source tree, refer to <tt>/usr/share/examples/sup/cvs-supfile</tt>. If you would rather track changes to the -stable release, refer to <tt>/usr/share/examples/sup/stable-supfile</tt> instead. If you're inside the United States, you may also uncomment the `secure' and `eBones' collection lines to grab the DES code. If you're outside the U.S., you should NOT sup this code from sup.FreeBSD.ORG as this will violate U.S. export restrictions. Instead you should use the <tt>secure-supfile</tt> found within the above directory. This will connect you to the international sup site that contains a secure distribution. Any distributions you do not wish to receive can be commented out with a # at the beginning of the distribution line. Please consult the file <tt>/usr/share/examples/sup/README</tt> for a list of alternate sup servers. The default sup server (sup.FreeBSD.ORG) listed in the above example files is currently overloaded and any traffic that can be transfered to a different host will help relieve some of the strain. 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 with the standard-supfile, please join the freebsd-current mailing list. You should also be sure to read -<ref id="current" -name="Staying current with FreeBSD"> +<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. If you are using the stable-supfile, please -join the freebsd-stable mailing list. +join the freebsd-stable mailing list and read +<ref id="stable" name="Staying stable with FreeBSD"> +. <sect1><heading>Description of FreeBSD SUP distributions</heading> <p>For the main FreeBSD distribution using the standard-supfile: <verb> src-base: /usr/src/... misc files at the top of /usr/src src-bin: /usr/src/bin user and system binaries src-secure: /usr/src/secure DES Sources (US/Canada ONLY) src-eBones: /usr/src/eBones Kerberos and DES (US/Canada ONLY) src-etc: /usr/src/etc system files src-games: /usr/src/games games src-gnu: /usr/src/gnu sources under the GNU Public License src-include: /usr/src/include include files src-sys: /usr/src/sys kernel sources src-lib: /usr/src/lib libraries src-libexec: /usr/src/libexec system binaries src-share: /usr/src/share various shared resources src-sbin: /usr/src/sbin single user system binaries src-usrbin: /usr/src/usr.bin user binaries src-usrsbin: /usr/src/usr.sbin system binaries </verb> <p>For the international FreeBSD distribution using the secure-supfile: <verb> src-secure: /usr/src/secure DES Sources src-eBones: /usr/src/eBones Kerberos and DES </verb> <p>And for the ports collection: <verb> ports-base: /usr/ports/... misc files at the top of /usr/ports ports-archivers: /usr/ports/archivers archiving tools ports-audio: /usr/ports/audio sound support ports-benchmarks: /usr/ports/benchmarks benchmarks ports-cad: /usr/ports/cad CAD tools ports-comms: /usr/ports/comms communication software ports-databases: /usr/ports/databases databases ports-devel: /usr/ports/devel development utilities ports-editors: /usr/ports/editors editors ports-emulators: /usr/ports/emulators emulators for other OSes ports-games: /usr/ports/games games ports-graphics: /usr/ports/graphics various graphics utilities ports-japanese: /usr/ports/japanese Japanese software. ports-lang: /usr/ports/lang programming languages ports-mail: /usr/ports/mail mail software ports-math: /usr/ports/math numerical computation software ports-misc: /usr/ports/misc miscellaneous utilities ports-net: /usr/ports/net networking software ports-news: /usr/ports/news USENET news software ports-plan9: /usr/ports/plan9 various programs from Plan9 ports-print: /usr/ports/print printing software ports-russian: /usr/ports/russian Russian software ports-security: /usr/ports/security ``security'' utilities, for better or for worse ports-shells: /usr/ports/shells various UN*X shells ports-sysutils: /usr/ports/sysutils system utilities ports-www: /usr/ports/www software related to the world wide web ports-x11: /usr/ports/x11 X11 software </verb> <p>If you want to keep updated on the original source of the ports, you can also add this to your supfile. But note that this collection is <em>enormous</em>, and unless you are an ftp site mirroring the entire FreeBSD tree (but can't use ``mirror'' for some reason), you (and us) are much better off not using sup to collect these: <verb> ports-distfiles: /usr/ports/distfiles original tarballs </verb> diff --git a/handbook/synching.sgml b/handbook/synching.sgml new file mode 100644 index 0000000000..ea5cd85a84 --- /dev/null +++ b/handbook/synching.sgml @@ -0,0 +1,21 @@ +<!-- $Id: synching.sgml,v 1.1 1996-02-11 00:16:20 jkh Exp $ --> +<!-- The FreeBSD Documentation Project --> + +<chapt><heading>Synchronizing source trees over the Internet<label id="synching"></heading> + +<p><em>Contributed by &a.jkh;.</em> + +<!-- + +Last updated: $Date: 1996-02-11 00:16:20 $ + +This document tries to describe the various ways in which a user may +use the internet to keep development sources in synch. +--> + + <p>There are various ways of using an Internet (or email) connection + to stay up-to-date with whatever collection of FreeBSD project sources + it is that interests you. The primary services we offer are: + + ⊃ + &ctm;