From acd6ba06465e00f8a77b3633e38fc58a7d7d1d63 Mon Sep 17 00:00:00 2001 From: jfieber Date: Fri, 28 Apr 1995 16:19:59 +0000 Subject: The FreeBSD handbook finds a new home. --- share/doc/handbook/authors.sgml | 20 + share/doc/handbook/basics.sgml | 73 +++ share/doc/handbook/bibliography.sgml | 110 +++++ share/doc/handbook/ctm.sgml | 199 ++++++++ share/doc/handbook/current.sgml | 179 +++++++ share/doc/handbook/dialup.sgml | 809 ++++++++++++++++++++++++++++++++ share/doc/handbook/diskless.sgml | 153 ++++++ share/doc/handbook/eresources.sgml | 118 +++++ share/doc/handbook/glossary.sgml | 5 + share/doc/handbook/handbook.sgml | 237 ++++++++++ share/doc/handbook/kerberos.sgml | 329 +++++++++++++ share/doc/handbook/nfs.sgml | 79 ++++ share/doc/handbook/porting.sgml | 414 ++++++++++++++++ share/doc/handbook/ports.sgml | 240 ++++++++++ share/doc/handbook/ppp.sgml | 372 +++++++++++++++ share/doc/handbook/scsi.sgml | 688 +++++++++++++++++++++++++++ share/doc/handbook/slipc.sgml | 196 ++++++++ share/doc/handbook/slips.sgml | 488 +++++++++++++++++++ share/doc/handbook/submitters.sgml | 181 +++++++ share/doc/handbook/sup.sgml | 92 ++++ share/doc/handbook/troubleshooting.sgml | 185 ++++++++ 21 files changed, 5167 insertions(+) create mode 100644 share/doc/handbook/authors.sgml create mode 100644 share/doc/handbook/basics.sgml create mode 100644 share/doc/handbook/bibliography.sgml create mode 100644 share/doc/handbook/ctm.sgml create mode 100644 share/doc/handbook/current.sgml create mode 100644 share/doc/handbook/dialup.sgml create mode 100644 share/doc/handbook/diskless.sgml create mode 100644 share/doc/handbook/eresources.sgml create mode 100644 share/doc/handbook/glossary.sgml create mode 100644 share/doc/handbook/handbook.sgml create mode 100644 share/doc/handbook/kerberos.sgml create mode 100644 share/doc/handbook/nfs.sgml create mode 100644 share/doc/handbook/porting.sgml create mode 100644 share/doc/handbook/ports.sgml create mode 100644 share/doc/handbook/ppp.sgml create mode 100644 share/doc/handbook/scsi.sgml create mode 100644 share/doc/handbook/slipc.sgml create mode 100644 share/doc/handbook/slips.sgml create mode 100644 share/doc/handbook/submitters.sgml create mode 100644 share/doc/handbook/sup.sgml create mode 100644 share/doc/handbook/troubleshooting.sgml diff --git a/share/doc/handbook/authors.sgml b/share/doc/handbook/authors.sgml new file mode 100644 index 0000000..b102495 --- /dev/null +++ b/share/doc/handbook/authors.sgml @@ -0,0 +1,20 @@ + + + + + +<jkh@FreeBSD.org>"> +<jfieber@FreeBSD.org>"> +<phk@FreeBSD.org>"> +<gclarkii@FreeBSD.org>"> +<gena@NetVision.net.il>"> +<ghelmer@alpha.dsu.edu>"> +<md@bsc.no>"> +<martin@innovus.com>"> +<gpalmer@FreeBSD.org>"> +<john@starfire.MN.ORG>"> +<asami@FreeBSD.org>"> +<wilko@yedi.iaf.nl>"> diff --git a/share/doc/handbook/basics.sgml b/share/doc/handbook/basics.sgml new file mode 100644 index 0000000..86dbab7 --- /dev/null +++ b/share/doc/handbook/basics.sgml @@ -0,0 +1,73 @@ + + + +Unix Basics + + + The online manual + +

The most comprehensive documentation on FreeBSD is in + the form of man pages. Nearly every program + on the system comes with a short reference manual + explaining the basic operation and various argument. + These manuals can be view with the + man command. Use of the + man command is simple: + + man command + + where command is the name of the command + you wish to find. For example, to learn more about + ls command type: + + man ls + + +

The online manual is divided up into numbered + sections: + + User commands + System calls and error numbers + Functions in the C libraries + Device drivers + File formats + Games and other diversions + Miscellaneous information + System maintenance and operation commands + + in some cases, the same topic may appear in more than + one section of the on-line manual. For example, there + is a chmod user command and a + chmod() system call. In this case, + you can tell the man command which + you want by specifying the section: + + man 1 chmod + + which will display the manual page for the user command + chmod. + +

This is fine if you know the name of the command and + forgot how to use it, but what if you cannot recall the + command name? You can use man to + search through the command descriptions by + using the -k switch: + + man -k mail + + With this command you will be presented with a list of + commands that have the keyword `mail' in their + descriptions. + + + GNU Info files + +

FreeBSD includes many applications and utilities + produced by the Free Software Foundation (FSF). In + addition to man pages, these programs come with more + extensive info files which can be viewed with + the info command or, if you installed + emacs, the info mode of emacs. + + + diff --git a/share/doc/handbook/bibliography.sgml b/share/doc/handbook/bibliography.sgml new file mode 100644 index 0000000..eb69637 --- /dev/null +++ b/share/doc/handbook/bibliography.sgml @@ -0,0 +1,110 @@ + + + + + Bibliography + +

While the manual pages provide the definative reference + for individual pieces of the FreeBSD operating system, + they are notorious for not illustrating how to put the + pieces together to make the whole operating system run + smoothly. For this, there is no substitute for a good + book on Unix system administration, and a good users' + manual. + + + Users' guides + +

+ Gilley, Daniel. Unix in a Nutshell. + O'Reilly & Associates, Inc. 1990 + + + + Administrators' guides + +

+ + Albitz, Paul; Liu, Cricket. DNS and + BIND. O'Reilley & Associates. 1993. ISBN + 1-56592-010-4 + + Costales, Brian; Allman, Eric; Rickert, + Neil. sendmail O'Reilley & + Associates. 1993. ISBN 1-56592-056-2 + + Frisch, Æleen. Essential System + Administration. O'Reilley & + Associates. 1993. ISBN 0-937175-80-3 + + Hunt, Craig. TCP/IP Network Administration + O'Reilley & Associates. 1992. ISBN 0-937175-82-X + + Nemeth, Evi. Unix System Administration + Handbook. Prentice Hall. 1989. ISBN + 0-13-933441-6 + + + + + + + Programmers' guides + +

+ + Asente, Paul. X Window System + Toolkit. Digital Press. ISBN + 1-55558-051-3 + + Ellis, Margaret A. and Stroustrup, + Bjarne. The Annotated C++ Reference + Manual. Addison-Wesley. 1990. ISBN + 0-201-51459-1 + + Harbison, Samuel P. and Steele, Guy + L. Jr. C: A Reference Manual. Prentice + Hall. 3rd Edition, 1991. ISBN + 0-13-110933-2 + + Jolitz, William. "Porting UNIX to the + 386". Dr. Dobb's Journal. January + 1991-July 1992. + + Leffler, Samuel J. The Design and + implementation of the 4.3BSD UNIX operating + system. Addison-Wesley. 1989. + + Plauger, P. J. The Standard C + Library. Prentice Hall. 1992. ISBN + 0-13-131509-9 + + Wells, Bill. "Writing Serial Drivers for UNIX". + Dr. Dobb's Journal. 19(15), December + 1994. pp68-71, 97-99. + + + + + Hardware reference + +

+ + Stanley, Tom; Anderson, Don. PCI System + Architechure. Mindshare, Inc. ISBN + 1-881609-08-1 + + + + + Magazines and journals + +

+ + The C/C++ Users Journal. R&D Publications + Inc. ISSN 1075-2838 + + + + + diff --git a/share/doc/handbook/ctm.sgml b/share/doc/handbook/ctm.sgml new file mode 100644 index 0000000..341c918 --- /dev/null +++ b/share/doc/handbook/ctm.sgml @@ -0,0 +1,199 @@ + + +CTM + +

Contributed by &a.phk;. Updated 16-Mar-1995. + + Why should I use + /usr/share/FAQ/Text/current-policy.FAQ + + + + What do I need to use You will need two things: The ``/usr/src/usr.sbin/). + If you are running an older version of FreeBSD, you can fetch the + current + + The ``deltas'' you feed + + Ftp the the relevant directory and fetch the /etc/aliases if you want. Check the Starting off with Before you can start using Using To apply the deltas, simply say + + cd /where/ever/you/want/the/stuff + ctm -v -v /where/you/store/your/deltas/src-cur.* + + Future plans for + Tons of them: + + + Make local modifications to the tree possible. One way to do + it could be this:

When foo/bar.c'', it would first check for the existence + of foo/bar.c#CTM If this file exists, the delta is + applied to it instead. This way the foo/bar.c file + can be edited to suit local needs. + + Make a ``restore file(s)'' option to + ctm -r src/sys/i386/wd.c /here/are/my/deltas/src-cur.* + + would restore + Clean up the options to + + The bad news is that I am very busy, so any help in doing this will + be most welcome. And don't forget to tell me what you want also... + + Miscellaneous stuff +

+ All the ``DES infected'' (e.g. export controlled) source is not + included. You will get the ``international'' version only. If + sufficient interest appears, we will set up a ``Thanks! +

+ + + diff --git a/share/doc/handbook/current.sgml b/share/doc/handbook/current.sgml new file mode 100644 index 0000000..1e3af09 --- /dev/null +++ b/share/doc/handbook/current.sgml @@ -0,0 +1,179 @@ + + + + +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 uncompilable. 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 one + part or another of the source tree and for whom keeping `current' + is an absolute requirement. + + Members of the FreeBSD group who are active ALPHA or BETA testers + and 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 there's something + you heard was pretty cool 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 catagories, 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 if + given the choice between having us answer lots of questions or + continue to improve FreeBSD, most of you would vote for us + improving it. + + +Using FreeBSD-current + +

Join the freebsd-hackers and freebsd-commit + mailing lists. This is not just a good idea, it's + essential. If you aren't on freebsd-hackers, you + won't read the comments that people are making about the + current state of the system and thus will 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 freebsd-commit list will allow you to see the commit log + entry for each change as its made. This can also contain + important information, and will let you know what parts of + the system are being actively changed. + + To join these lists, send mail to `majordomo@FreeBSD.ORG' + and say: + + subscribe freebsd-hackers + subscribe freebsd-commit + + 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 desribed 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. + + The problem is that sup does not use the bandwidth efficient, + unless the round-trip is very fast. If the cost of connection + or the duration of the session is a concern, use CTM. + + 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 + 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. + + + 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'll see one-time targets like `bootstrapld' + which must be run 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/share/doc/handbook/dialup.sgml b/share/doc/handbook/dialup.sgml new file mode 100644 index 0000000..5401473 --- /dev/null +++ b/share/doc/handbook/dialup.sgml @@ -0,0 +1,809 @@ + + +Dialup access + +

Contributed by &a.ghelmer;. + +This document provides suggestions for configuring a FreeBSD system to +handle dialup modems. This document is written based on the author's +experience with FreeBSD versions 1.0, 1.1, and 1.1.5.1 (and experience +with dialup modems on other UNIX-like operating systems); however, +this document may not answer all of your questions or provide examples +specific enough to your environment. The author cannot be responsible +if you damage your system or lose data due to attempting to follow the +suggestions here. + +Prerequisites

+ +To begin with, the author assumes you have some basic knowledge of +FreeBSD. You need to have FreeBSD installed, know how to edit files +in a UNIX-like environment, and how to look up manual pages on the +system. As discussed below, you'll need certain versions of FreeBSD, +and knowledge of some terminology & modem and cabling. + +FreeBSD Version +

+ +First, it is assumed that you are using FreeBSD version 1.1 or higher +(including versions 2.x). FreeBSD version 1.0 included two different +serial drivers, which complicates the situation. Also, the serial +device driver (Terminology +

+ +A quick rundown of terminology: + + + + + +If you need more information about these terms and data communications +in general, the author remembers reading that External vs. Internal Modems +

+ +External modems seem to be more convenient for dialup, because +external modems often can be semi-permanently configured via +parameters stored in non-volatile RAM and they usually provide lighted +indicators that display the state of important RS-232 signals. +Blinking lights impress visitors, but lights are also very useful to +see whether a modem is operating properly. + +Internal modems usually lack non-volatile RAM, so their configuration +may be limited only to setting DIP switches. If your internal modem +has any signal indicator lights, it is probably difficult to view the +lights when the system's cover is in place. + +Modems and Cables +

+ +A background knowledge of these items is assumed + + + + You know how to connect your modem to your computer so that the +two can communicate (unless you have an internal modem, which doesn't +need such a cable) + + You are familiar with your modem's command set, or know where +to look up needed commands + + You know how to configure your modem (probably via a terminal +communications program) so you can set the non-volatile RAM +parameters + + + +The first, connecting your modem, is usually simple - most +straight-through serial cables work without any problems. You need to +have a cable with appropriate connectors (DB-25 or DB-9, male or +female) on each end, and the cable must be a DCE-to-DTE cable with +these signals wired: + + + Transmitted Data ( Received Data ( Request to Send ( Clear to Send ( Data Set Ready ( Data Terminal Ready ( Carrier Detect ( Signal Ground ( + +FreeBSD needs the Serial Interface Considerations +

+ +FreeBSD supports NS8250-, NS16450-, NS16550-, and NS16550A-based EIA +RS-232C (CCITT V.24) communications interfaces. The 8250 and 16450 +devices have single-character buffers. The 16550 device provides a +16-character buffer, which allows for better system performance. +(Bugs in plain 16550's prevent the use of the 16-character buffer, so +use 16550A's if possible). Because single-character-buffer devices +require more work by the operating system than the 16-character-buffer +devices, 16550A-based serial interface cards are much prefered. If +the system has many active serial ports or will have a heavy load, +16550A-based cards are better for low-error-rate communications. + +Quick Overview +

+ +Here is the process that FreeBSD follows to accept dialup logins. A +/dev/ttyd0, for our example). The +command + 4850 ?? I 0:00.09 /usr/libexec/getty V19200 ttyd0 + + +When a user dials the modem's line and the modems connect, the /usr/bin/login, which completes the login +by asking for the user's password and then starting the user's shell. + +Let's dive into the configuration... + +Kernel Configuration +

+ +FreeBSD kernels typically come prepared to search for four serial +ports, known in the PC-DOS world as /sbin/dmesg command to replay the kernel's boot messages. In +particular, look for messages that start with the characters +/usr/sbin/dmesg | grep 'sio' + + +For example, on a system with four serial ports, these are the +serial-port specific kernel boot messages: + + +sio0 at 0x3f8-0x3ff irq 4 on isa +sio0: type 16550A +sio1 at 0x2f8-0x2ff irq 3 on isa +sio1: type 16550A +sio2 at 0x3e8-0x3ef irq 5 on isa +sio2: type 16550A +sio3 at 0x2e8-0x2ef irq 9 on isa +sio3: type 16550A + + +If your kernel doesn't recognize all of your serial ports, you'll +probably need to configure a custom FreeBSD kernel for your system. + +Please see the BSD System Manager's Manual chapter on ``Building +Berkeley Kernels with Config'' [the source for which is in +/usr/src/share/doc/smm] and ``FreeBSD Configuration +Options'' [in /sys/doc/options.doc] for more +information on configuring and building kernels. You may have to +unpack the kernel source distribution if haven't installed the system +sources already (srcdist/srcsys.?? in FreeBSD 1.1, +srcdist/sys.?? in FreeBSD 1.1.5.1, or the entire source +distribution in FreeBSD 2.0) to be able to configure and build +kernels. + +Create a kernel configuration file for your system (if you haven't +already) by /sys/i386/conf. Then, if you are +creating a new custom configuration file, copy the file GENERICAH (or +GENERICBT, if you have a BusTek SCSI controller on FreeBSD 1.x) to + +device sio0 at isa? port "IO_COM1" tty irq 4 vector siointr +device sio1 at isa? port "IO_COM2" tty irq 3 vector siointr +device sio2 at isa? port "IO_COM3" tty irq 5 vector siointr +device sio3 at isa? port "IO_COM4" tty irq 9 vector siointr + + +You can comment-out or completely remove lines for devices you don't +have. If you have a multiport serial board, such as the Boca Board +BB2016, please see the can't share interrupts on ISA-bus PCs (multiport boards have +on-board electronics that allow all the 16550A's on the board to share +one or two interrupt request lines). + +When you are finished adjusting the kernel configuration file, use the +program Device Special Files +

+ +Most devices in the kernel are accessed through ``device special +files'', which are located in the /dev directory. The +/dev/ttyd? +(dial-in) and /dev/cua0? (call-out) devices. On FreeBSD +version 1.1.5 and higher, there are also initialization devices +(/dev/ttyid? and /dev/cuai0?) and locking devices +(/dev/ttyld? and /dev/cual0?). The initialization +devices are used to initialize communications port parameters each +time a port is opened, such as crtscts for modems which use +CTS/RTS signalling for flow control. The locking devices are +used to lock flags on ports to prevent users or programs changing +certain parameters; see the manual pages Making Device Special Files +

+ +A shell script called /dev directory +manages the device special files. (The manual page for +/dev +and issue the command /dev/ttyd? device special +files, but also creates the /dev/cua0? (and all of the +initializing and locking special files under FreeBSD 1.1.5 and up) and +removes the hardwired terminal special file /dev/tty0?, if it +exists. + +After making new device special files, be sure to check the +permissions on the files (especially the /dev/cua* files) to +make sure that only users who should have access to those device +special files can read & write on them - you probably don't want +to allow your average user to use your modems to dialout. The default +permissions on the /dev/cua* files should be sufficient: + + +crw-rw---- 1 uucp dialer 28, 129 Feb 15 14:38 /dev/cua01 +crw-rw---- 1 uucp dialer 28, 161 Feb 15 14:38 /dev/cuai01 +crw-rw---- 1 uucp dialer 28, 193 Feb 15 14:38 /dev/cual01 + + +These permissions allow the user Configuration Files +

+ +There are three system configuration files in the /etc +directory that you'll probably need to edit to allow dialup access to +your FreeBSD system. The first, /etc/gettytab, contains +configuration information for the /usr/libexec/getty daemon. +Second, /etc/ttys holds information that tells +/sbin/init what /etc/rc.serial script if you have FreeBSD +1.1.5.1 or higher; otherwise, you can initialize ports in the +/etc/rc.local script. + +There are two schools of thought regarding dialup modems on UNIX. One +group likes to configure their modems and system so that no matter at +what speed a remote user dials in, the local computer-to-modem RS-232 +interface runs at a locked speed. The benefit of this configuration +is that the remote user always sees a system login prompt immediately. +The downside is that the system doesn't know what a user's true data +rate is, so full-screen programs like Emacs won't adjust their +screen-painting methods to make their response better for slower +connections. + +The other school configures their modems' RS-232 interface to vary its +speed based on the remote user's connection speed. For example, +V.32bis (14.4 Kbps) connections to the modem might make the modem run +its RS-232 interface at 19.2 Kbps, while 2400 bps connections make the +modem's RS-232 interface run at 2400 bps. Because <Enter> key until they see a recognizable prompt. If +the data rates don't match, /etc/gettytab +

+ +/etc/gettytab is a Locked-Speed Config +

+ +If you are locking your modem's data communications rate at a +particular speed, you probably won't need to make any changes to +/etc/gettytab. + +Matching-Speed Config +

+ +You'll need to setup an entry in /etc/gettytab to give + +# +# Fast dialup terminals, 2400/1200/300 rotary (can start either way) +# +D2400|d2400|Fast-Dial-2400:\ + :nx=D1200:tc=2400-baud: +3|D1200|Fast-Dial-1200:\ + :nx=D300:tc=1200-baud: +5|D300|Fast-Dial-300:\ + :nx=D2400:tc=300-baud: + + +If you have a higher speed modem, you'll probably need to add an entry +in /etc/gettytab; here's an entry you could use for a 14.4 +Kbps modem with a top interface speed of 19.2 Kpbs: + + +# +# Additions for a V.32bis Modem +# +um|V300|High Speed Modem at 300,8-bit:\ + :nx=V19200:tc=std.300: +un|V1200|High Speed Modem at 1200,8-bit:\ + :nx=V300:tc=std.1200: +uo|V2400|High Speed Modem at 2400,8-bit:\ + :nx=V1200:tc=std.2400: +up|V9600|High Speed Modem at 9600,8-bit:\ + :nx=V2400:tc=std.9600: +uq|V19200|High Speed Modem at 19200,8-bit:\ + :nx=V9600:tc=std.19200: + + +On FreeBSD 1.1.5 and later, this will result in 8-bit, no parity +connections. Under FreeBSD 1.1, add std. entries at the top of the file for 8 bits, no +parity; otherwise, the default is 7 bits, even parity. + +The example above starts the communications rate at 19.2 Kbps (for a +V.32bis connection), then cycles through 9600 bps (for V.32), 2400 +bps, 1200 bps, 300 bps, and back to 19.2 Kbps. Communcations rate +cycling is implemented with the +# +# Additions for a V.32bis or V.34 Modem +# Starting at 57.6 Kpbs +# +vm|VH300|Very High Speed Modem at 300,8-bit:\ + :nx=VH57600:tc=std.300: +vn|VH1200|Very High Speed Modem at 1200,8-bit:\ + :nx=VH300:tc=std.1200: +vo|VH2400|Very High Speed Modem at 2400,8-bit:\ + :nx=VH1200:tc=std.2400: +vp|VH9600|Very High Speed Modem at 9600,8-bit:\ + :nx=VH2400:tc=std.9600: +vq|VH57600|Very High Speed Modem at 57600,8-bit:\ + :nx=VH9600:tc=std.57600: + + +If you have a slow CPU or a heavily loaded system and you don't have +16550A-based serial ports, you may receive sio ``silo'' errors at 57.6 +Kbps. + +/etc/ttys +

+ +/etc/ttys is the list of /etc/ttys also provides security information to /etc/ttys or +add new lines to make +ttyd0 "/usr/libexec/getty xxx" dialup on + + +The first item in the above line is the device special file for this +entry - /dev/ttyd0 is the file that this +"/usr/libexec/getty + (secure, but it +should only be used for terminals which are physically secure (such as +the system console). + +The default terminal type (/etc/ttys, you may send the + +kill -1 1 + + +to send the signal. If this is your first time setting up the system, +though, you may want to wait until your modem(s) are properly +configured and connected before signalling Locked-Speed Config +

+ +For a locked-speed configuration, your +ttyd0 "/usr/libexec/getty std.19200" dialup on + + +If your modem is locked at a different data rate, substitute the +appropriate name for the std. entry for +/etc/gettytab for your modem's data rate. + +Matching-Speed Config +

+ +In a matching-speed configuration, your /etc/gettytab. For example, if you added the above suggested +entry for a matching-speed modem that starts at 19.2 Kbps (the + +ttyd0 "/usr/libexec/getty V19200" dialup on + + +/etc/rc.serial or /etc/rc.local +

+ +High-speed modems, like V.32, V.32bis, and V.34 modems, need to use +hardware (RTS/CTS) flow control. You can add /etc/rc.serial on FreeBSD 1.1.5.1 and up, or +/etc/rc.local on FreeBSD 1.1, to set the hardware flow +control flag in the FreeBSD kernel for the modem ports. + +For example, on a sample FreeBSD 1.1.5.1 system, +/etc/rc.serial reads: + + +#!/bin/sh +# +# Serial port initial configuration + +stty -f /dev/ttyid1 crtscts +stty -f /dev/cuai01 crtscts + + +which sets the +# Set serial ports to use RTS/CTS flow control +stty -f /dev/ttyd0 crtscts +stty -f /dev/ttyd1 crtscts +stty -f /dev/ttyd2 crtscts +stty -f /dev/ttyd3 crtscts + + +Since there isn't an initialization device special file on FreeBSD +1.1, one has to just set the flags on the sole device special file and +hope the flags aren't cleared by a miscreant. + +Modem Settings +

+ +If you have a modem whose parameters may be permanently set in +non-volatile RAM, you'll need to use a terminal program (such as Telix +under PC-DOS or + + Disable XON/XOFF flow control + + Quiet mode (no result codes) + + No command echo + + + +Please read the documentation for your modem to find out what commands +and/or DIP switch settings you need to give it. + +For example, to set the above parameters on a USRobotics Sportster +14,400 external modem, one could give these commands to the modem: + + +ATZ +AT&C1&D2&H1&I0&R2&W + + +You might also want to take this opportunity to adjust other settings +in the modem, such as whether it will use V.42bis and/or MNP5 +compression. + +The USR Sportster 14,400 external modem also has some DIP switches +that need to be set; for other modems, perhaps you can use these +settings as an example: + + + + Switch 1: UP - DTR Normal + + Switch 2: Don't care (Verbal Result Codes/Numeric Result Codes) + + Switch 3: UP - Suppress Result Codes + + Switch 4: DOWN - No echo, offline commands + + Switch 5: UP - Auto Answer + + Switch 6: UP - Carrier Detect Normal + + Switch 7: UP - Load NVRAM Defaults + + Switch 8: Don't care (Smart Mode/Dumb Mode) + + + +Result codes should be disabled/suppressed for dialup modems to avoid +problems that can occur if Locked-speed Config +

+ +For a locked-speed configuration, you'll need to configure the modem +to maintain a constant modem-to-computer data rate independent of the +communications rate. On a USR Sportster 14,400 external modem, these +commands will lock the modem-to-computer data rate at the speed used +to issue the commands: + + +ATZ +AT&B1&W + + +Matching-speed Config +

+ +For a variable-speed configuration, you'll need to configure your +modem to adjust its serial port data rate to match the incoming call +rate. On a USR Sportster 14,400 external modem, these commands will +lock the modem's error-corrected data rate to the speed used to issue +the commands, but allow the serial port rate to vary for +non-error-corrected connections: + + +ATZ +AT&B2&W + + +Checking the Modem's Configuration +

+ +Most high-speed modems provide commands to view the modem's current +operating parameters in a somewhat human-readable fashion. On the USR +Sportster 14,400 external modems, the command Troubleshooting +

+ +Here are a few steps you can follow to check out the dialup modem on +your system. + +Checking out the FreeBSD system +

+ +Hook up your modem to your FreeBSD system, boot the system, and, if +your modem has status indication lights, watch to see whether the +modem's + 114 ?? I 0:00.10 /usr/libexec/getty V19200 ttyd0 + 115 ?? I 0:00.10 /usr/libexec/getty V19200 ttyd1 + + +If you see something different, like this: + + + 114 d0 I 0:00.10 /usr/libexec/getty V19200 ttyd0 + ^^ + + +and the modem hasn't accepted a call yet, this means that /etc/ttys to +see if there are any mistakes there. Also, check the log file +/var/log/messages to see if there are any log messages from +/etc/ttys and +/etc/gettytab, as well as the appropriate device special +files /dev/ttyd?, for any mistakes, missing entries, or +missing device special files. + +Try Dialing In +

+ +Try dialing into the system; be sure to use 8 bits, no parity, 1 stop +bit on the remote system. If you don't get a prompt right away, or +get garbage, try pressing <Enter> about once per +second. If you still don't see a BREAK. If you are using a high-speed modem to +do the dialing, try dialing again after locking the dialing modem's +interface speed (via AT&B1 on a USR Sportster, for +example). + +If you still can't get a /etc/gettytab again and double-check that + + + The initial capability name specified in /etc/ttys for +the line matches a name of a capability in /etc/gettytab + + Each Each + +If you dial but the modem on the FreeBSD system won't answer, make +sure that the modem is configured to answer the phone when FreeBSD-Questions@freebsd.org describing your modem and your +problem, and the good folks on the list will try to help. + +Acknowledgements +

+ +Thanks to these people for comments and advice: + + + + + + diff --git a/share/doc/handbook/diskless.sgml b/share/doc/handbook/diskless.sgml new file mode 100644 index 0000000..283e216 --- /dev/null +++ b/share/doc/handbook/diskless.sgml @@ -0,0 +1,153 @@ + + + +Diskless operation + +

Contributed by &a.martin;. + + netboot.com/netboot.rom allow you to boot your + FreeBSD machine over the network and run FreeBSD without + having a disk on your client. Under 2.0 it is now + possible to have local swap. Swapping over NFS is also + still supported. + + Supported Ethernet cards include: Western Digital/SMC + 8003, 8013, 8216 and compatibles; NE1000/NE2000 and + compatibles (requires recompile) + + + Setup Instructions + +

+ Find a machine that will be your server. This + machine will require enough disk space to hold the + FreeBSD 2.0 binaries and have bootp, tftp and NFS + services available. + + Tested machines: + + HP9000/8xx running HP-UX 9.04 or later (pre + 9.04 doesn't work) + Sun/Solaries 2.3. (you may need to get + bootp) + + + Set up a bootp server to provide the client with + IP, gateway, netmask. + +diskless:\ + :ht=ether:\ + :ha=0000c01f848a:\ + :sm=255.255.255.0:\ + :hn:\ + :ds=192.1.2.3:\ + :ip=192.1.2.4:\ + :gw=192.1.2.5:\ + :vm=rfc1048: + + + Set up a TFTP server (on same machine as bootp + server) to provide booting information to client. + The name of this file is cfg.X.X.X.X (or + /tftpboot/cfg.X.X.X.X, it will try both) + where X.X.X.X is the IP address of the + client. The contents of this file can be any valid + netboot commands. Under 2.0, netboot has the + following commands: + +help - print help list +ip - print/set client's IP address +server - print/set bootp/tftp server address +netmask - print/set netmask +hostname - print/set hostname +kernel - print/set kernel name +rootfs - print/set rootfilesystem +swapfs - print/set swapfilesystem +swapsize - set diskless swapsize in Kbytes +diskboot - boot from disk +autoboot - continue boot process + + A typical completely diskless cfg file might contain: + +rootfs 192.1.2.3:/rootfs/myclient +swapfs 192.1.2.3:/swapfs +swapsize 20000 +hostname myclient.mydomain + + A cfg file for a machine with local swap might contain: + +rootfs 192.1.2.3:/rootfs/myclient +hostname myclient.mydomain + + + Ensure that your NFS server has exported the root + (and swap if applicable) filesystems to your client, + and that the client has root access to these + filesystems + + A typical /etc/exports file on FreeBSD might + look like: + +/rootfs/myclient -maproot=0:0 myclient.mydomain +/swapfs -maproot=0:0 myclient.mydomain + + + And on HP-UX: + +/rootfs/myclient -root=myclient.mydomain +/swapfs -root=myclient.mydomain + + + If you are swapping over NFS (completely diskless + configuration) create a swap file for your client + using touch. If your swapfs command has the + argument /swapfs as in the example above, + the swapfile for myclient will be called + /swapfs/swap.X.X.X.X where X.X.X.X + is the client's IP addr, eg: + +# touch /swapfs/swap.192.1.2.4 + + + Unpack the root filesystem in the directory the + client will use for its root filesystem + (/rootfs/myclient in the example above). + + + + On HP-UX systems: The server should be + running HP-UX 9.04 or later for HP9000/800 series + machines. Prior versions don't allow the + creation of device files over NFS. + + When extracting /dev in + /rootfs/myclient, beware that some + systems (HPUX) will not create device files that + FreeBSD is happy with. You may have to go to + single user mode on the first bootup (press + control-c during the bootup phase), cd + /dev and do a "sh ./MAKEDEV + all" from the client to fix this. + + + Run netboot.com on the client or make an EPROM + from the netboot.rom file + + + + Using Shared / and /usr filesystems + +

At present there isn't an officially sanctioned way of + doing this, although I have been using a shared /usr + filesystem and individual / filesystems for each client. + If anyone has any suggestions on how to do this cleanly, + please let me and/or the core group know. + + + Compiling netboot for specific setups + +

Netboot can be compiled to support NE1000/2000 cards by + changing the configuration in + /sys/i386/boot/netboot/Makefile. See the + comments at the top of this file. + diff --git a/share/doc/handbook/eresources.sgml b/share/doc/handbook/eresources.sgml new file mode 100644 index 0000000..c4e8574 --- /dev/null +++ b/share/doc/handbook/eresources.sgml @@ -0,0 +1,118 @@ + + + + + Additional resources on the Internet + + + Mailing lists + +

The FreeBSD Project runs a number of Internet mailing + lists dedicated to the discussion of FreeBSD and + related topics. Users with access to Internet mail are + encouraged to subscribe to the lists that interest them + and ask questions. The procedure is quite simple, just + send a mail message to: + + majordomo@freebsd.org + + with a message body of: + + subscribe listname + + where listname is one of the lists described + below. You can subscribe to multiple lists with a + single message by having several subscribe + lines. For more detailed information, send a message + to: + + majordomo@freebsd.org + + with a message body of + + help + + + + General discussion lists +

+ freebsd-announce Important announcements + about FreeBSD are posted here. + + freebsd-questions General discussion of + problems people experience in setting up and using + FreeBSD. + + freebsd-hackers Technical discussions + about the design and implementation of FreeBSD. + + freebsd-bugs Bug reports and discussions + of reported bugs are posted here, although the + discussions are usually moved over to the + freebsd-hackers mailing list if the become involved. + + + + CVS lists + + + Usenet newsgroups + +

While no newsgroups dedicated to FreeBSD exist, there + are many in which FreeBSD is discussed or are otherwise + relevant to FreeBSD users. + + + BSD specific newsgroups + +

+ comp.unix.bsd.freebsd.announce + comp.unix.bsd.freebsd.misc + + + + Other Unix newsgroups of interest + +

+ comp.unix + comp.unix.questions + comp.unix.admin + comp.unix.programmer + comp.unix.shell + comp.unix.user-friendly + comp.security.unix + comp.sources.unix + comp.unix.advocacy + comp.unix.misc + comp.os.386bsd.announce + comp.os.386bsd.apps + comp.os.386bsd.bugs + comp.os.386bsd.development + comp.os.386bsd.misc + comp.os.386bsd.questions + comp.bugs.4bsd + comp.bugs.4bsd.ucb-fixes + comp.unix.bsd + + + + X-Window system + +

+ comp.windows.x.i386unix + comp.windows.x + comp.windows.x.apps + comp.windows.x.announce + comp.windows.x.intrinsics + comp.windows.x.motif + comp.windows.x.pex + comp.emulators.ms-windows.wine + + + + Word Wide Web servers + +

+ + + diff --git a/share/doc/handbook/glossary.sgml b/share/doc/handbook/glossary.sgml new file mode 100644 index 0000000..983f6eb --- /dev/null +++ b/share/doc/handbook/glossary.sgml @@ -0,0 +1,5 @@ + + + +Glossary + diff --git a/share/doc/handbook/handbook.sgml b/share/doc/handbook/handbook.sgml new file mode 100644 index 0000000..9366969 --- /dev/null +++ b/share/doc/handbook/handbook.sgml @@ -0,0 +1,237 @@ + + + + +%authors; + + + + + + + + + + + + + + + + + + + + + +]> + + + + + + + FreeBSD Handbook + <author> + <name></name> + <!-- <date> --> + + + <abstract>Welcome to FreeBSD! This handbook covers the + installation and day to day use of FreeBSD. + + 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 Documentantion + Project mailing list <tt><doc@freebsd.org></tt>. + </abstract> + + <toc> + + + <chapt><heading>Introduction</heading> + + <sect><heading>FreeBSD In a nutshell</heading> + + <sect><heading>History</heading> + + <sect><heading>About this release</heading> + + <sect><heading>FreeBSD now and in the future</heading> + + + <chapt><heading>Installing FreeBSD</heading> + + <sect><heading>Preparing for the installation</heading> + + <sect1><heading>Hardware checklist</heading> + + <sect2><heading>minimal requirements</heading> + + <sect2><heading>IRQs, IO Addresses, and DMA channels</heading> + + <sect1><heading>Software checklist</heading> + + <sect2><heading>Making the installation floppies</heading> + + <sect2><heading>CD-ROM</heading> + + <sect2><heading>Tape</heading> + + <sect2><heading>Disk</heading> + + <sect><heading>Installation</heading> + + <sect><heading>Set up a user account</heading> + + &basics; + + <chapt><heading>Installing applications</heading> + + <sect><heading>Installing packages</heading> + &ports; + &porting; + + <chapt><heading>Reconfiguring the kernel</heading> + + <p>Once you have your FreeBSD system installed and + operational it is a good idead to re-configure the + kernel. You may also need to re-configure the kernel if + you add, change, or remove hardware from your system. + + <p> + + <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> + + <chapt><heading>Printing</heading> + + <chapt><heading>Users, groups and security</heading> + + <sect><heading>DES, MD5 and Crypt</heading> + + &kerberos; + + <sect><heading>S/Key</heading> + + <sect><heading>Firewalls</heading> + + <chapt><heading>The X-Window System</heading> + + <chapt><heading>Managing hardware</heading> + &scsi; + <sect><heading>adding/reconfiguring disks</heading> + <sect><heading>tapes and backups</heading> + <sect><heading>serial ports</heading> + <sect><heading>sound cards</heading> + + <chapt><heading>PC Hardware compatibility</heading> + + <sect><heading>CORE/PROCESSING</heading> + + <sect1><heading>Motherboards</heading> + + <sect2><heading>ISA</heading> + + <sect2><heading>EISA</heading> + + <sect2><heading>VLB</heading> + + <sect2><heading>PCI</heading> + + <sect1><heading>CPUs/FPUs</heading> + + <sect1><heading>Memory</heading> + + <sect1><heading>BIOS</heading> + + <sect><heading>INPUT/OUTPUT</heading> + + <sect1><heading>Video cards</heading> + + <sect1><heading>Sound cards</heading> + + <sect1><heading>Serial ports (including multiport cards)</heading> + + <sect1><heading>Parallel ports</heading> + + <sect1><heading>Modems</heading> + + <sect1><heading>Etherenet cards</heading> + + <sect1><heading>Keyboards</heading> + + <sect1><heading>Mice</heading> + + <sect1><heading>Other (joysticks? tablets?)</heading> + + <sect><heading>STORAGE</heading> + + <sect1><heading>Disk/tape controllers</heading> + + <sect2><heading>SCSI</heading> + + <sect2><heading>IDE</heading> + + <sect2><heading>Floppy</heading> + + <sect1><heading>Hard drives</heading> + + <sect1><heading>Tape drives</heading> + + <sect1><heading>CD-ROM drives</heading> + + <sect1><heading>Other</heading> + + <sect><heading>OTHER</heading> + + <sect1><heading>PCMCIA</heading> + + ¤t; + &ctm; + ⊃ + &troubleshooting; + &submitters; + + &bibliography; + &eresources; + &glossary; + + </book> +</linuxdoc> diff --git a/share/doc/handbook/kerberos.sgml b/share/doc/handbook/kerberos.sgml new file mode 100644 index 0000000..61db933 --- /dev/null +++ b/share/doc/handbook/kerberos.sgml @@ -0,0 +1,329 @@ +<!-- $Id: m_kerberos.sgml,v 1.1 1995/04/10 02:36:02 jfieber Exp $ --> +<!-- The FreeBSD Documentation Project --> + +<sect><heading>Kerberos</heading> + +<p><em>Contributed by &a.md;.</em> + + <p>The following instructions can be used as a quick + guide on how to set up kerberos as distributed in 4.4 + BSD. However, you should refer to the original Athena + documentation for a complete description. + + <sect1> + <heading>Creating the initial database</heading> + + <p>First make sure that you don't have any old kerberos + databases around. You should change to the directory + <tt>/etc/kerberosIV</tt> and check that only the + following files are present: + +<tscreen><verb> +mideon# cd /etc/kerberosIV +mideon# ls +README krb.conf krb.realms register_keys + </verb></tscreen> + + If any additional files (such as <tt>principal.dir</tt>) exist, + then use the <tt>kdb_destroy</tt> command to destroy the + old kerberos database. + + <p>You should now edit the <tt>krb.conf</tt> and + <tt>krb.realms</tt> files to define your kerberos realm. + In this case the realm will be <it>BSC.NO</it> and the + server is <it>mideon.bsc.no</it>. We would edit the + <tt>krb.conf</tt> file to be as follows: + +<tscreen><verb> +mideon# cat krb.conf +BSC.NO +BSC.NO mideon.bsc.no admin server +CS.BERKELEY.EDU okeeffe.berkeley.edu +ATHENA.MIT.EDU kerberos.mit.edu +ATHENA.MIT.EDU kerberos-1.mit.edu +ATHENA.MIT.EDU kerberos-2.mit.edu +ATHENA.MIT.EDU kerberos-3.mit.edu +LCS.MIT.EDU kerberos.lcs.mit.edu +TELECOM.MIT.EDU bitsy.mit.edu +ARC.NASA.GOV trident.arc.nasa.gov + </verb></tscreen> + + <p>Now we have to add <it>mideon.bsc.no</it> to the + <it>BSC.NO</it> realm and also add an entry to put all + hosts in the <it>.bsc.no</it> domain in the + <it>BSC.NO</it> realm. The <tt>krb.realms</tt> file + would be updated as follows: + +<tscreen><verb> + mideon# cat krb.realms + mideon.bsc.no BSC.NO + .bsc.no BSC.NO + .berkeley.edu CS.BERKELEY.EDU + .MIT.EDU ATHENA.MIT.EDU + .mit.edu ATHENA.MIT.EDU +</verb></tscreen> + + <p>Now we're ready to create the database, issue the + <tt>kdb_init</tt> command to do this: + +<tscreen><verb> +mideon# kdb_init +Realm name [default CS.BERKELEY.EDU ]: BSC.NO +You will be prompted for the database Master Password. +It is important that you NOT FORGET this password. + +Enter Kerberos master key: + </verb></tscreen> + + <p>Now we have to save the key so that servers on the local + machine can pick it up. Use the <tt>kstash</tt> command to + do this. + +<tscreen><verb> +mideon# kstash + +Enter Kerberos master key: + +Current Kerberos master key version is 1. + +Master key entered. BEWARE! + </verb></tscreen> + + <sect1> + <heading>Populating the database</heading> + + <p>We now have to add some entries into the database. + First lets create an entry for the user <it>md</it>. Use + the <tt>kdb_edit</tt> command to do this: + +<tscreen><verb> +mideon# kdb_edit +Opening database... + +Enter Kerberos master key: + +Current Kerberos master key version is 1. + +Master key entered. BEWARE! +Previous or default values are in [brackets] , +enter return to leave the same, or new value. + +Principal name: md +Instance: +md. not found, Create [y] ? +Principal: md, Instance: , kdc_key_ver: 1 +New Password: +New Password: + +Principal's new key version = 1 +Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? +Max ticket lifetime (*5 minutes) [ 255 ] ? 100 +Attributes [ 0 ] ? +Edit O.K. + </verb></tscreen> + + <p>Now lets add an entry for the password changing daemon, + <tt>kpasswd</tt>. The principal name must be <it>kpasswd</it> and + the instance must be the name of the local machine, + <it>mideon</it> in this case. Similarily, we must also + add an entry for the principal <it>rcmd</it> with an + instance equal to the hostname of the local machine. + +<tscreen><verb> +Principal name: kpasswd +Instance: mideon +kpasswd.mideon not found, Create [y] ? +Principal: kpasswd, Instance: mideon, kdc_key_ver: 1 +New Password: <---- enter RANDOM here +New Password: <---- and here +Random password [y] ? + +Principal's new key version = 1 +Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? +Max ticket lifetime (*5 minutes) [ 255 ] ? +Attributes [ 0 ] ? +Edit O.K. +Principal name: rcmd +Instance: mideon +rcmd.mideon not found, Create [y] ? +Principal: rcmd, Instance: mideon, kdc_key_ver: 1 +New Password: <---- enter RANDOM here +New Password: <---- and here +Random password [y] ? + +Principal's new key version = 1 +Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? +Max ticket lifetime (*5 minutes) [ 255 ] ? +Attributes [ 0 ] ? +Edit O.K. +Principal name: <---- null entry here will cause an exit + </verb></tscreen> + + <sect1> + <heading>Creating the server file</heading> + + <p>We now have to extract all the instances which define + the services on this machine. For this we use the + <tt>ext_srvtab</tt> command. + +<tscreen><verb> +mideon# ext_srvtab mideon + +Enter Kerberos master key: + +Current Kerberos master key version is 1. + +Master key entered. BEWARE! +Generating 'mideon-new-srvtab'.... + </verb></tscreen> + + <p>Now, this command only generates a temporary file + which must be renamed to <tt>srvtab</tt> so that all the + server can pick it up. Use the <tt>mv</tt> command to move it + into place: + +<tscreen><verb> +mideon# mv mideon-new-srvtab srvtab + </verb></tscreen> + + <sect1> + <heading>Testing it all out</heading> + + <p>First we have to start the kerberos daemon: + +<tscreen><verb> +mideon# kerberos & +[1] 774 +mideon# Kerberos server starting + Sleep forever on error + Log file is /var/log/kerberos.log +Current Kerberos master key version is 1. + +Master key entered. BEWARE! + +Current Kerberos master key version is 1 +Local realm: BSC.NO + </verb></tscreen> + + Now we can try using the <tt>kinit</tt> command to get + tokens for the id <it>md</it> that we created above: + +<tscreen><verb> +mideon# kinit md +Kerberos Initialization for "md" +Kerberos Password: + </verb></tscreen> + + Try listing the tokens using <tt>klist</tt> to see if we + really have them: + +<tscreen><verb> +mideon# klist +Ticket file: /tmp/tkt0 +Principal: md@BSC.NO + + Issued Expires Principal +Mar 23 21:06:52 Mar 24 05:06:52 krbtgt.BSC.NO@BSC.NO + </verb></tscreen> + + And now try changing the password using <tt>passwd</tt> + to check if the kpasswd daemon can get authorisation to + the kerberos database: + +<tscreen><verb> +mideon# passwd md +Changing Kerberos password for md.@BSC.NO. +Old Kerberos password: +New Kerberos password: +Retype new Kerberos password: +Update complete. + </verb></tscreen> + + <sect1> + <heading>Adding <tt>su</tt> priviledges</heading> + + <p>We should now add an id which is authorised to <tt>su</tt> to + <it>root</it>. This is controlled by having an instance of + <it>root</it> associated with a principal. Using + <tt>kdb_edit</tt> we can create the entry + <it>md.root</it> in the kerberos database: + +<tscreen><verb> +mideon# kdb_edit +Opening database... + +Enter Kerberos master key: + +Current Kerberos master key version is 1. + +Master key entered. BEWARE! +Previous or default values are in [brackets] , +enter return to leave the same, or new value. + +Principal name: md +Instance: root +md.admin not found, Create [y] ? +Principal: md, Instance: admin, kdc_key_ver: 1 +New Password: +New Password: + +Principal's new key version = 1 +Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? +Max ticket lifetime (*5 minutes) [ 255 ] ? 12 +Attributes [ 0 ] ? +Edit O.K. +Principal name: + </verb></tscreen> + + Now try getting tokens for it to make sure it works: + +<tscreen><verb> +mideon# kinit md.root +Kerberos Initialization for "md.root" +Kerberos Password: + </verb></tscreen> + + And list them to check expiry times: + +<tscreen><verb> +mideon# klist +Ticket file: /tmp/tkt0 +Principal: md.root@BSC.NO + + Issued Expires Principal +Mar 23 21:08:47 Mar 23 22:08:47 krbtgt.BSC.NO@BSC.NO +mideon# + </verb></tscreen> + + Now we need to add the user to root's <tt>.klogin</tt> file: + +<tscreen><verb> +mideon# cat /root/.klogin +md.root@BSC.NO + </verb></tscreen> + + Now try doing the <tt>su</tt>: + +<tscreen><verb> +[md@mideon.bsc.no 10407] su +Kerberos Password: +Warning: tgt not verified. + </verb></tscreen> + + and take a look at what tokens we have: + +<tscreen><verb> +mideon# klist +Ticket file: /tmp/tkt_root_1250 +Principal: md.root@BSC.NO + + Issued Expires Principal +Mar 23 22:09:59 Mar 23 22:19:59 krbtgt.BSC.NO@BSC.NO +mideon# + </verb></tscreen> + + Notice that with this setup each user has their own entry + for <tt>su</tt>'ing to root (the <it>user</it>.root entry + in kerberos). This can allow you to give root access to + multiple users without the need to share a common root + password. diff --git a/share/doc/handbook/nfs.sgml b/share/doc/handbook/nfs.sgml new file mode 100644 index 0000000..9961ddc --- /dev/null +++ b/share/doc/handbook/nfs.sgml @@ -0,0 +1,79 @@ +<!-- $Id: m_nfs.sgml,v 1.1 1995/04/10 02:36:04 jfieber Exp $ --> +<!-- The FreeBSD Documentation Project --> + +<sect><heading>NFS</heading> + +<p><em>Contributed by &a.john;.</em> + +Certain Ethernet adapters for ISA PC systems have limitations which +can lead to serious network problems, particularly with NFS. This +difficulty is not specific to FreeBSD, but FreeBSD systems are affected +by it. + +The problem nearly always occurs when (FreeBSD) PC systems are networked +with high-performance workstations, such as those made by Silicon Graphics, +Inc., and Sun Microsystems, Inc. The NFS mount will work fine, and some +operations may succeed, but suddenly the server will seem to become +unresponsive to the client, even though requests to and from other systems +continue to be processed. This happens to the client system, whether the +client is the FreeBSD system or the workstation. On many systems, there is +no way to shut down the client gracefully once this problem has manifested +itself. The only solution is often to reset the client, because the NFS +situation cannot be resolved. + +Though the "correct" solution is to get a higher performance and capacity +Ethernet adapter for the FreeBSD system, there is a simple workaround that +will allow satisfactory operation. If the FreeBSD system is the SERVER, +include the option "wsize=1024" on the mount from the client. If the +FreeBSD system is the CLIENT, then mount the NFS file system with the +option "rsize=1024". These options may be specified using the fourth +field of the fstab entry on the client for automatic mounts, or by using +the "-o" parameter of the mount command for manual mounts. + +In the following examples, "fastws" is the host (interface) name of a +high-performance workstation, and "freebox" is the host (interface) name of +a FreeBSD system with a lower-performance Ethernet adapter. Also, +"/sharedfs" will be the exported NFS filesystem (see "man exports"), and +"/project" will be the mount point on the client for the exported file +system. In all cases, note that additional options, such as "hard" or +"soft" and "bg" may be desireable in your application. + +Examples for the FreeBSD system ("freebox") as the client: + in /etc/fstab on freebox: +fastws:/sharedfs /project nfs rw,rsize=1024 0 0 + as a manual mount command on freebox: +mount -t nfs -o rsize=1024 fastws:/sharedfs /project + +Examples for the FreeBSD system as the server: + in /etc/fstab on fastws: +freebox:/sharedfs /project nfs rw,wsize=1024 0 0 + as a manual mount command on fastws: +mount -t nfs -o wsize=1024 freebox:/sharedfs /project + +Nearly any 16-bit Ethernet adapter will allow operation without the above +restrictions on the read or write size. + +For anyone who cares, here is what happens when the failure occurs, which +also explains why it is unrecoverable. NFS typically works with a "block" +size of 8k (though it may do fragments of smaller sizes). Since the maximum +Ethernet packet is around 1500 bytes, the NFS "block" gets split into +multiple Ethernet packets, even though it is still a single unit to the +upper-level code, and must be received, assembled, and ACKNOWLEDGED as a +unit. The high-performance workstations can pump out the packets which +comprise the NFS unit one right after the other, just as close together as +the standard allows. On the smaller, lower capacity cards, the later +packets overrun the earlier packets of the same unit before they can be +transferred to the host and the unit as a whole cannot be reconstructed or +acknowledged. As a result, the workstation will time out and try again, +but it will try again with the entire 8K unit, and the process will be +repeated, ad infinitum. + +By keeping the unit size below the Ethernet packet size limitation, we +ensure that any complete Ethernet packet received can be acknowledged +individually, avoiding the deadlock situation. + +Overruns may still occur when a high-performance workstations is slamming +data out to a PC system, but with the better cards, such overruns are +not guarranteed on NFS "units". When an overrun occurs, the units affected +will be retransmitted, and there will be a fair chance that they will be +received, assembled, and acknowledged. diff --git a/share/doc/handbook/porting.sgml b/share/doc/handbook/porting.sgml new file mode 100644 index 0000000..0f972d0 --- /dev/null +++ b/share/doc/handbook/porting.sgml @@ -0,0 +1,414 @@ +<!-- $Id: m_porting.sgml,v 1.1 1995/04/10 02:36:06 jfieber Exp $ --> +<!-- The FreeBSD Documentation Project --> + +<sect><heading>Porting applications</heading> + +<p><em>Contributed by &a.jkh;.</em> + +Here are the guidelines one should follow in + creating a new port for FreeBSD 2.x . This documentation will + change as this process is progressively refined, so watch + this space for details. The <tt>${..}</tt> + variable names you see in this document all refer to + various user-overridable defaults used (and documented) + by <tt>/usr/share/mk/bsd.port.mk</tt>. Please refer to + that file for more details. + + <sect1> + <heading>Before starting the port</heading> + + <p> <em>Note: Only a fraction of the overridable variables + are mentioned in this document. Most (if not all) are + documented at the start of the <tt>bsd.port.mk</tt> + file which can be found in /usr/share/mk. This file + uses a non-standard tab setting. <tt>Emacs</tt> should + recognise the setting on loading the file. <tt>vi</tt> + or <tt>ex</tt> can be set to using the correct value by + typing "<tt>:set tabstop=4</tt>" once the file has been + loaded. - &a.gpalmer;</em> + + You may come across code that needs modifications or + conditional compilation based upon what version of UNIX + it's running under. If you need to make such changes to + the code for conditional compilation, make sure you make + the changes as general as possible so that we can + back-port code to FreeBSD 1.x systems and cross-port to + other BSD systems such as 4.4bsd from CSRG, BSD/386, + 386BSD and NetBSD. + + The preferred way to tell 4.3BSD/Reno and newer versions + of the BSD code apart is by using the "<tt>BSD</tt>" + macro defined in <tt><sys/param.h></tt>. Hopefully + that file is already included; if not, add the code: + +<tscreen><verb> +#ifdef _HAVE_PARAM_H +#include <sys/param.h> +#endif +</verb></tscreen> + + to the proper place in the <tt>.c</tt> file and add + <tt>-D_HAVE_PARAM_H</tt> to the <tt>CFLAGS</tt> in the + Makefile. + + Then, you may use: + +<tscreen><verb> +#if (defined(BSD) && (BSD >= 199103)) +</verb></tscreen> + + to detect if the code is being compiled on a 4.3 Net2 + code base or newer (e.g. FreeBSD 1.x, 4.3/Reno, NetBSD + 0.9, 386BSD, BSD/386 1.0). + + Use: + +<tscreen><verb> +#if (defined(BSD) && (BSD >= 199306)) +</verb></tscreen> + + to detect if the code is being compiled on a 4.4 code + base or newer (e.g. FreeBSD 2.x, 4.4, NetBSD 1.0, + BSD/386 1.1). + + Use sparingly: + + <itemize> + <item><tt>__FreeBSD__</tt> is defined in all + versions of FreeBSD. Use it if the change you + are making ONLY affects FreeBSD. Porting gotchas + like the use of <tt>sys_errlist[]</tt> vs + <tt>strerror()</tt> are Berkeleyisms, not FreeBSD + changes. + + <item>In FreeBSD 2.x, <tt>__FreeBSD__</tt> is + defined to be <tt>2</tt>. In earlier versions, + it's <tt>1</tt>. + + <item>If you need to tell the difference between a + FreeBSD 1.x system and a FreeBSD 2.x system, + usually the right answer is to use the + <tt>BSD</tt> macros described above. If there + actually is a FreeBSD specific change (such as + special shared library options when using + '<tt>ld</tt>') then it's OK to use + <tt>__FreeBSD__</tt> and "<tt>#if __FreeBSD_ > + 1</tt>" to detect a FreeBSD 2.x system. + + </itemize> + + In the dozens of ports that have been done, there have + only been one or two cases where <tt>__FreeBSD__</tt> + should have been used. Just because an earlier port + screwed up and used it in the wrong place doesn't mean + you should do so too. + + <sect1> + <heading> Doing the port</heading> + + <p>NOTE: If your sources work without change under FreeBSD, + skip to the next section. + + <enum> + <item>Get the original sources (normally) as a + compressed tarball (<tt><foo>.tar.gz</tt> or + <tt><foo>.tar.Z</tt>) and copy it into + <tt>${DISTDIR}</tt>. Always use + <em>mainstream</em> sources when and where you can, + and don't be tempted to patch a tarball 2 or 3 + revisions ahead just to save yourself trouble. The + idea is that the ports collection should be usable + even with all of <tt>${DISTDIR}</tt> blown + away, which is to say that it should be possible for + a user to repopulate all of + <tt>${DISTDIR}</tt> with publically available + files. + + <item>Unpack a copy of the tarball in a private + directory and make whatever changes are necessary to + get the port to compile properly under FreeBSD 2.0. + Keep <em>careful track</em> of everything you do, as + you will be automating the process shortly. + Everything, including the deletion, addition or + modification of files should be doable using an + automated script or patch file when your port is + finished. If your port requires significant user + interaction/customization to compile or install, you + should take a look at one of Larry Wall's classic + Configure scripts and perhaps do something similar + yourself. The goal of the new ports collection is to + make each port as `plug-and-play' as possible for the + end-user while using a minimum of disk space. + + <item>Carefully consider the list of patches, shell + commands or user queries necessary for customizing + the port, then, making sure you understand the + following thoroughly, go for it. The sequence of + events you need to understand is that which occurs + when the user first types `<tt>make</tt>' in your + port's directory, and you may find that having + <tt>bsd.port.mk</tt> in another window while you read + this really helps to understand it: + + Sequence of events: + + <enum> + <item>The pre-fetch and fetch targets are run. The + fetch target is responsible for making sure that + the tarball exists locally in <tt>${DISTDIR}</tt>. + The pre-fetch target hook is optional. If fetch + cannot find the required files in + <tt>${DISTDIR}</tt> it will look up the URL + <tt>${MASTER_SITES}</tt>, which can be set in the + Makefile or allowed to default to the Walnut + Creek CDROM archive site. It will then attempt + to fetch the named distribution file with + <tt>${NCFTP}</tt>, assuming that the requesting + site has direct access to the Internet. If that + succeeds, it will save the file in + <tt>${DISTDIR}</tt> for future use and proceed. + + <item>The pre-extract target hook, if it exists, is + run. + + <item>The extract target, if not disabled, is run. + It looks for your ports' distribution file in + <tt>${DISTDIR}</tt> (typically a gzip'd + tarball) and unpacks it into a temporary + directory. + + <item>The pre-configure target hook is run. + + <item>The configure target is run. This can do any + one of many different things. First, if any + patches are found in the + <tt>${PATCHDIR}</tt> subdirectory, they + are applied at this time in alphabetical order. + Next, a series of scripts, if detected, are run + in the following order: + + <enum> + + <item><tt>${SCRIPTDIR}/pre-configure</tt> + + <item><tt>${SCRIPTDIR/configure</tt> or + <tt>${WRKSRC}/configure</tt> if + <tt>${HAS_CONFIGURE}</tt> is set. + + <item>If <tt>${USE_IMAKE}</tt> is set, an + xmkmf command is done. + + <item><tt>${SCRIPTDIR}/post-configure</tt> + </enum> + + As you can see, it's possible to do just about anything to your + port, in a variety of stages! + + <item>The pre-build target hook is run. + + <item>The build target is run. This is responsible + for decending into the ports' private working + directory (<tt>${WRKSRC}</tt>) and + building it. If <tt>${USE_GMAKE}</tt> is + set, GNU <tt>make</tt> will be used, otherwise + the system <tt>${MAKE}</tt>. + </enum> + + <item>In the preparation of the port, files that have + been added or changed can be picked up with a + recursive diff for later feeding to patch. This is + the easiest kind of change to make as it doesn't + involve any mucking around with configuration files. + Each set of patches you wish to apply should be + collected into a file named + "<tt>patch-<xx></tt>" where <tt><xx></tt> + denotes the sequence in which the patches will be + applied - these are done in <em>alphabetical + order</em>, thus "<tt>aa</tt>" first, "<tt>ab</tt>" + second and so on. These files should be stored in + <tt>${PATCHDIR}</tt>, from where they will be + automatically applied. All patches should be + relative to <tt>${WRKSRC}</tt> (generally the + directory your port's tarball unpacks itself into, + that being where the make is done). + + <item>Include any additional customization commands to + your `<tt>configure</tt>' script and save it to + <tt>${SCRIPTDIR}/configure</tt>. Add your + port to the Makefile one level above it so that it + will be made automatically. + + <item>Always try to install relative to + <tt>${PREFIX}</tt> in your Makefiles. This will + normally be set to <tt>/usr/local</tt>, though it can be can + be reassigned in your Makefile or in the users + environment. Not hardcoding <tt>/usr/local</tt> anywhere in + your installation will make the port much more + flexible and cater to the needs of other sites. Note + that this doesn't count for package `packing list' + files since they have their own scheme for relocating + themselves and can be left independant of + <tt>${PREFIX}</tt> unless the package is one that + hardcodes itself to a compiled-in location. + + <item>If your port requires user input to build, + configure or install, then set + <tt>IS_INTERACTIVE</tt> in your Makefile. This will + allow "overnight builds" to progress past your port + if the user sets the variable <tt>BATCH</tt> in his + environment (and if the user sets the variable + <tt>INTERACTIVE</tt>, then <em>only</em> those ports + requiring interaction are built). + + For more details on any of this (since it may not be + clear at first reading), examine an existing port and + read the contents of <tt>/usr/share/mk/bsd.port.mk</tt>; + you'll see that it's not as difficult as it sounds! + + </enum> + +<sect1> + <heading>Configuring the Makefile</heading> + + <p>Configuring the Makefile is pretty simple, and again I + suggest that you look at existing examples before + starting. Consider the following problems in sequence as + you design your new Makefile: + + <enum> + <item>Does it live in <tt>${DISTDIR}</tt> as a + standard gzip'd tarball? If so, you can go on to the + next step. If not, you should look at overriding any + of the <tt>${EXTRACT_CMD}</tt>, + <tt>${EXTRACT_ARGS}</tt>, + <tt>${EXTRACT_SUFX}</tt>, or + <tt>${DISTFILE}</tt> variables, depending on + how alien a format your port's distribution file is. + In the worst case, you can simply create your own + `<tt>extract</tt>' target to override the default, + though this should be rarely, if ever, necessary. If + you do find it necessary to do your own, your extract + target should take care to "leave tracks" for itself + so that files are not unnecessarily extracted + twice---see the default extract rule in + <tt>bsd.port.mk</tt> for an example of this. + + <item>If your port is integrated into the ports + directory directly (original sources are already part + of FreeBSD), you may also consider simply setting + <tt>NO_EXTRACT</tt> and dispensing with the idea of a + distribution file altogether. + + <item>You should set <tt>${DISTNAME}</tt> to be the base + name of your port. The default rules expect the + distribution file list (<tt>${DISTFILES}</tt>) to be + named + <tt>${DISTDIR}/${DISTFILE}${EXTRACT_SUFX}</tt> + by default which, if it's a normal tarball, is going + to be something like: +<tscreen><verb> +foozolix-1.0.tar.gz +</verb></tscreen> + For a setting of "<tt>DISTNAME=foozolix-1.0</tt>" + + The default rules also expect the tarball(s) to + extract into a subdirectory called + <tt>${WRKDIR}/${DISTNAME}</tt>, e.g. +<tscreen><verb> +"<blah>/foozolix-1.0/" +</verb></tscreen> + + All this behavior can be overridden, of course, it + simply represents the most common time-saving + defaults. For a port requiring multiple distribution + files, simply set <tt>${DISTFILES}</tt> explicitly. If + only a subset of <tt>${DISTFILES}</tt> are actual + extractable archives, then set them up in + <tt>${EXTRACT_ONLY}</tt>, which will override the + <tt>${DISTFILES}</tt> list when it comes to extraction. + + <item>If your package uses GNU <tt>make</tt>, set + "<tt>USE_GMAKE=yes</tt>". If your package uses GNU + <tt>configure</tt>, set "<tt>GNU_CONFIGURE=yes</tt>". + If you want to override the default GNU <tt>configure</tt> + arguments from `<tt>i386--freebsd</tt>' to something else, + set those arguments in <tt>${GNU_CONFIGURE_ARGS}</tt>. + + If your package uses <tt>imake</tt> (e.g. is an X + application that has an <tt>Imakefile</tt>), then set + "<tt>USE_IMAKE=yes</tt>". This will cause the + configure stage to automatically do an <tt>xmkmf</tt> and then + a `<tt>make Makefiles</tt>'. + + <item>If you have a URL pointing at the the original + tarball, record the directory containing the tarball + in <tt>${MASTER_SITES}</tt>. This will provide a + backup site, as well as a direct pointer to the + original source location. + + The make macros will currently try to use this + specification for grabbing the distribution file with + <tt>${NCFTP}</tt> if they can't find it + already on the system. See some of the other ports + for examples. + + <item>Due to a problem in some of the ports, 2.0 was + distributed with a setting which meant ports that + have <tt>${USE_IMAKE}</tt> set do not install their + manpages by default. Although -current has the logic + reversed, for compatability with 2.0 systems (at + least until 2.1 comes out) you should set + "<tt>INSTALL_MANPAGES=yes</tt>". For complete forward + compatability, if the port doesn't understand the + "<tt>install.man</tt>" target, "<tt>NO_INSTALL_MANPAGES=yes</tt>" + should be set (which conforms with the current logic + in <tt>bsd.port.mk</tt>) + + <item>Don't forget to include + <tt><bsd.port.mk></tt> at the bottom. That + should do it! + + </enum> + +<sect1> + <heading>Do's and Dont's</heading> + + <p><enum> + + <item>Don't leave anything valuable lying around in + <tt>${WRKDIR}</tt>, `<tt>make clean</tt>' will + <em>nuke</em> it completely! If you need auxilliary + files that aren't scripts or patches, put them in + <tt> ${FILESDIR}</tt>. + + <item>Do install package information, if possible. It + would sure be nice if `<tt>make package</tt>' worked + for the whole ports tree this time. + + <item>Do look at existing examples and the + <tt>bsd.port.mk</tt> file before asking me questions! + ;-) + + <item>Do ask me questions if you have any trouble! + Don't just beat your head against a wall! :-) + + <item>Don't rely on custom utilities in your local + configure script---they may not be there on the + user's system! If you really need something else to + be installed before you can work, detect this from + your configure script, print a helpful message and + exit with a non-zero status! At least you'll have + given the user some idea of what's needed. If the + custom utility or package is actually part of the + ports tree, then set a pointer to it in your + <tt>DEPENDS</tt> variable---the port structure will + ensure that all <tt>DEPENDS</tt> targets are built + first. + + <item>Do send applicable changes/patches to the + original author/maintainer for inclusion in next + release of the code. This will only make your job + that much easier for the next release. + + </enum> + diff --git a/share/doc/handbook/ports.sgml b/share/doc/handbook/ports.sgml new file mode 100644 index 0000000..23d9f23 --- /dev/null +++ b/share/doc/handbook/ports.sgml @@ -0,0 +1,240 @@ +<!-- $Id: m_ports.sgml,v 1.1 1995/04/10 02:36:12 jfieber Exp $ --> +<!-- The FreeBSD Documentation Project --> + +<sect><heading>The Ports collection</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. + + 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!). + + +<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 +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> + +<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 +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 # (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). + + 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: +<verb> + make describe | sed -e '/===/D' -e 's;/usr/ports/;;' | expand -40 +</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). + + +<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/share/doc/handbook/ppp.sgml b/share/doc/handbook/ppp.sgml new file mode 100644 index 0000000..8fc2125 --- /dev/null +++ b/share/doc/handbook/ppp.sgml @@ -0,0 +1,372 @@ +<!-- $Id: m_ppp.sgml,v 1.1 1995/04/10 02:36:13 jfieber Exp $ --> +<!-- The FreeBSD Documentation Project --> + +<sect><heading>Setting up a PPP link</heading> + +<p><em>Contributed by &a.gena;.</em> + +Before you start setting up PPP on your machine make +sure that pppd is located in /usr/sbin and directory /etc/ppp +exists. + +pppd can work in two modes: +<enum> +<item> as a "client" , i.e. you want to connect your machine to outside +world via PPP serial connection or modem line. + +<item> as a "server" , i.e. your machine is located on the network and +used to connect other computers using PPP. +</enum> +In both cases you will need to set up an options file ( /etc/ppp/options +or ~/.ppprc if you have more then one user on your machine that uses +PPP ). + +You also will need some modem/serial software ( preferably kermit ) +so you can dial and establish connection with remote host. + +<sect1><heading>Working as a PPP client</heading> + +<p>I used the following /etc/ppp/options to connect to CISCO terminal server PPP +line. +<verb> +crtscts # enable hardware flow control +modem # modem control line +noipdefault # remote PPP server must supply your IP address. + # if the remote host doesn't send your IP during IPCP + # negotiation , remove this option +passive # wait for LCP packets +domain ppp.foo.com # put your domain name here + +:<remote_ip> # put the IP of remote PPP host here + # it will be used to route packets via PPP link + # if you didn't specified the noipdefault option + # change this line to <local_ip>:<remote_ip> + +defaultroute # put this if you want that PPP server will be your + # default router +</verb> + +To connect: +<enum> +<item> Dial to the remote host using kermit ( or other modem program ) +enter your user name and password ( or whatever is needed to enable PPP +ont the remote host ) + +<item> Exit kermit. ( without hanging up the line ) + +<item> enter: +<verb> +/usr/src/usr.sbin/pppd.new/pppd /dev/tty01 19200 +</verb> +( put the appropriate speed and device name ) +</enum> + +Now your computer is connected with PPP. If the connection fails for some +reasons you can add the "debug" option to the /etc/ppp/options file +and check messages on the console to track the problem + +Following /etc/ppp/pppup script will make all 3 stages automatically: +<verb> +#!/bin/sh +ps ax |grep pppd |grep -v grep +pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'` +if [ "X${pid}" != "X" ] ; then + echo 'killing pppd, PID=' ${pid} + kill ${pid} +fi +ps ax |grep kermit |grep -v grep +pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'` +if [ "X${pid}" != "X" ] ; then + echo 'killing kermit, PID=' ${pid} + kill -9 ${pid} +fi + +ifconfig ppp0 down +ifconfig ppp0 delete + +kermit -y /etc/ppp/kermit.dial +pppd /dev/tty01 19200 +</verb> + +/etc/ppp/kermit.dial is kermit script that dials and makes all +necessary authorization on the remote host. +( Example of such script is attached to the end of this document ) + +Use the follwing /etc/ppp/pppdown script to disconnect the PPP line: +<verb> +#!/bin/sh +pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'` +if [ X${pid} != "X" ] ; then + echo 'killing pppd, PID=' ${pid} + kill -TERM ${pid} +fi + +ps ax |grep kermit |grep -v grep +pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'` +if [ "X${pid}" != "X" ] ; then + echo 'killing kermit, PID=' ${pid} + kill -9 ${pid} +fi + +/sbin/ifconfig ppp0 down +/sbin/ifconfig ppp0 delete +kermit -y /etc/ppp/kermit.hup +/etc/ppp/ppptest +</verb> + +Check if PPP is still running (/usr/etc/ppp/ppptest): +<verb> +#!/bin/sh +pid=`ps ax| grep pppd |grep -v grep|awk '{print $1;}'` +if [ X${pid} != "X" ] ; then + echo 'pppd running: PID=' ${pid-NONE} +else + echo 'No pppd running.' +fi +set -x +netstat -n -I ppp0 +ifconfig ppp0 +</verb> + +Hangs up modem line (/etc/ppp/kermit.hup): +<verb> +set line /dev/tty01 ; put your modem device here +set speed 19200 +set file type binary +set file names literal +set win 8 +set rec pack 1024 +set send pack 1024 +set block 3 +set term bytesize 8 +set command bytesize 8 +set flow none + +pau 1 +out +++ +inp 5 OK +out ATH0\13 +echo \13 +exit +</verb> + +<sect1><heading>Working as a PPP server</heading> + +<p>/etc/ppp/options: +<verb> +crtscts # Hardware flow control +netmask 255.255.255.0 # netmask ( not required ) +192.114.208.20:192.114.208.165 # ip's of local and remote hosts + # local ip must be different from one + # you assigned to the ethernet ( or other ) + # interface on your machine. + # remote IP is ip address that will be + # assigned to the remote machine +domain ppp.foo.com # your domain +passive # wait for LCP +modem # modem line +</verb> + +Following /etc/ppp/pppserv script will enable ppp server on your machine +<verb> +#!/bin/sh +ps ax |grep pppd |grep -v grep +pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'` +if [ "X${pid}" != "X" ] ; then + echo 'killing pppd, PID=' ${pid} + kill ${pid} +fi +ps ax |grep kermit |grep -v grep +pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'` +if [ "X${pid}" != "X" ] ; then + echo 'killing kermit, PID=' ${pid} + kill -9 ${pid} +fi + +# reset ppp interface +ifconfig ppp0 down +ifconfig ppp0 delete + +# enable autoanswer mode +kermit -y /etc/ppp/kermit.ans + +# run ppp +pppd /dev/tty01 19200 +</verb> + +Use this /etc/ppp/pppservdown script to stop ppp server: +<verb> +#!/bin/sh +ps ax |grep pppd |grep -v grep +pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'` +if [ "X${pid}" != "X" ] ; then + echo 'killing pppd, PID=' ${pid} + kill ${pid} +fi +ps ax |grep kermit |grep -v grep +pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'` +if [ "X${pid}" != "X" ] ; then + echo 'killing kermit, PID=' ${pid} + kill -9 ${pid} +fi +ifconfig ppp0 down +ifconfig ppp0 delete + +kermit -y /etc/ppp/kermit.noans +</verb> + +Following kermit script will enable/disable autoanswer mode +on your modem (/etc/ppp/kermit.ans): +<verb> +set line /dev/tty01 +set speed 19200 +set file type binary +set file names literal +set win 8 +set rec pack 1024 +set send pack 1024 +set block 3 +set term bytesize 8 +set command bytesize 8 +set flow none + +pau 1 +out +++ +inp 5 OK +out ATH0\13 +inp 5 OK +echo \13 +out ATS0=1\13 ; change this to out ATS0=0\13 if you want to disable + ; autoanswer mod +inp 5 OK +echo \13 +exit +</verb> + +This /etc/ppp/kermit.dial script is used for dialing and authorizing on remote host. +You will need to customize it for your needs. +Put your login and password in this script , also you'll need +to change input statement depending on responces from your modem +and remote host. +<verb> +; +; put the com line attached to the modem here: +; +set line /dev/tty01 +; +; put the modem speed here: +; +set speed 19200 +set file type binary ; full 8 bit file xfer +set file names literal +set win 8 +set rec pack 1024 +set send pack 1024 +set block 3 +set term bytesize 8 +set command bytesize 8 +set flow none +set modem hayes +set dial hangup off +set carrier auto ; Then SET CARRIER if necessary, +set dial display on ; Then SET DIAL if necessary, +set input echo on +set input timeout proceed +set input case ignore +def \%x 0 ; login prompt counter +goto slhup + +:slcmd ; put the modem in command mode +echo Put the modem in command mode. +clear ; Clear unread characters from input buffer +pause 1 +output +++ ; hayes escape sequence +input 1 OK\13\10 ; wait for OK +if success goto slhup +output \13 +pause 1 +output at\13 +input 1 OK\13\10 +if fail goto slcmd ; if modem doesn't answer OK, try again + +:slhup ; hang up the phone +clear ; Clear unread characters from input buffer +pause 1 +echo Hanging up the phone. +output ath0\13 ; hayes command for on hook +input 2 OK\13\10 +if fail goto slcmd ; if no OK answer, put modem in command mode + +:sldial ; dial the number +pause 1 +echo Dialing. +output atdt9,550311\13\10 ; put phone number here +assign \%x 0 ; zero the time counter + +:look +clear ; Clear unread characters from input buffer +increment \%x ; Count the seconds +input 1 {CONNECT } +if success goto sllogin +reinput 1 {NO CARRIER\13\10} +if success goto sldial +reinput 1 {NO DIALTONE\13\10} +if success goto slnodial +reinput 1 {\255} +if success goto slhup +reinput 1 {\127} +if success goto slhup +if < \%x 60 goto look +else goto slhup + +:sllogin ; login +assign \%x 0 ; zero the time counter +pause 1 +echo Looking for login prompt. + +:slloop +increment \%x ; Count the seconds +clear ; Clear unread characters from input buffer +output \13 +; +; put your expected login prompt here: +; +input 1 {Username: } +if success goto sluid +reinput 1 {\255} +if success goto slhup +reinput 1 {\127} +if success goto slhup +if < \%x 10 goto slloop ; try 10 times to get a login prompt +else goto slhup ; hang up and start again if 10 failures + +:sluid +; +; put your userid here: +; +output ppp-login\13 +input 1 {Password: } +; +; put your password here: +; +output ppp-password\13 +input 1 {Entering SLIP mode.} +echo +quit + +:slnodial +echo \7No dialtone. Check the telephone line!\7 +exit 1 + +; local variables: +; mode: csh +; comment-start: "; " +; comment-start-skip: "; " +; end: +</verb> + +<!-- +################################################################### +Gennady B. Sorokopud ( gena@NetVision.net.il ) 24/10/94 12:00 +--> + diff --git a/share/doc/handbook/scsi.sgml b/share/doc/handbook/scsi.sgml new file mode 100644 index 0000000..7cad8b0 --- /dev/null +++ b/share/doc/handbook/scsi.sgml @@ -0,0 +1,688 @@ +<!-- $Id: m_scsi.sgml,v 1.1 1995/04/10 02:36:14 jfieber Exp $ --> +<!-- The FreeBSD Documentation Project --> + +<!-- + <title>An introduction to SCSI and its use with FreeBSD + (c) 1995, Wilko Bulte, V0.2, Thu Apr 20 22:45:23 MET DST 1995 + Copyright 1995, W. C. Bulte, Arnhem, The Netherlands + + + This document attempts to describe the background of SCSI, its + (mis)use with FreeBSD and some common pitfalls. + + +--> + SCSI + +

© 1995, &a.wilko;. + + SCSI is an acronym for Small Computer Systems Interface. It is an + ANSI standard that has become one of the leading I/O buses in the + computer industry. The foundation of the SCSI standard was laid by + Shugart Associates (the same guys that gave the world the first + mini floppy disks) when they introduced the SASI bus (Shugart Associates + Standard Interface). + + After some time an industry effort was started to come to a more strict + standard allowing devices from different vendors to work together. + This effort was recognised in the ANSI SCSI-1 standard. The SCSI-1 + standard (approx 1985) is now more or less obsolete. The current + standard is SCSI-2 (see ), with SCSI-3 on the drawing boards. + + In addition to a physical interconnection standard, SCSI defines a + logical (command set) standard to which disk devices must adhere. + This standard is called the Common Command Set (CCS) and was + developed more or less in parallel with ANSI SCSI-1. SCSI-2 + includes the (revised) CCS as part of the standard itself. The + commands are dependent on the type of device at hand. It does not + make much sense of course to define a Write command for a + scanner... + + The SCSI bus is a parallel bus, which comes in a number of + variants. The oldest and most used is an 8 bit wide bus, with + single-ended signals, carried on 50 wires. (If you don't know what + single-ended means, don't worry, that is what this document is all + about.) Modern designs also use 16 bit wides buses, with + differential signals. This allows transfer speeds of + 20Mbytes/second, on cables lengths of up to 25 meters. SCSI-2 + allows a maximum buswidth of 32 bits, using an additional cable. + + Of course the SCSI bus not only has data lines, but also a number + of control signals. A very elaborate protocol is part of the + standard to allow multiple devices to share the bus in an efficient + manner. In SCSI-2, the data is always checked using a seperate + parity line. In pre-SCSI-2 designs parity was optional. + + In SCSI-3 even faster bustypes are introduced, along with a serial + SCSI bus that reduces the cabling overhead and allows a higher + maximum buslength. + + As you could have guessed from the description above, SCSI devices + are intelligent. They have to be to adhere to the SCSI standard + (which is over 2 inches thick BTW). So, for a hard disk drive for + instance you do not specify a head/cylinder/sector to address a + particular block, but simply the number of the block you want. + Elaborate caching schemes, automatic badblock replacement etc + are all made possible by this 'intelligent device' approach. + + On a SCSI bus, each possible pair of devices can communicate. If + their function allows this is another matter, but the standard does + not restrict it. To avoid signal contention, the 2 devices have to + arbitrate for the bus before using it. + + The philosophy of SCSI is to have a standard that allows + older-standard devices to work with newer-standard ones. So, an + old SCSI-1 device should normally work on a SCSI-2 bus. Normally, + because it is not absolutely sure that the implementation of an old + device follows the (old) standard closely enough to be acceptable + on a new bus. Modern devices are usually more well-behaved, + because the standardisation has become more strict and is better + adhered to by the device manufacturers. Generally speaking, the + chances of getting a working set of devices on a single bus is + better when all the devices are SCSI-2 or newer. This does not + imply that you have to dump all your old stuff when you get that + shiny 2Gb disk: I own a system on which a pre-SCSI-1 disk, a SCSI-2 + QIC tape unit, a SCSI-1 helical scan tape unit and 2 SCSI-1 disks + work together quite happily. + + Concepts of SCSI +

+ A smart interface +

+ As said before, SCSI devices are smart. The idea is to put the + knowledge about intimate hardware details onto the SCSI device + itself. In this way, the host system does not have to worry + about things like how many heads are hard disks has, or how many + tracks there are on a specific tape device. If you are curious, + the standard specifies commands with which you can query your + devices on their hardware particulars. + + The advantage of intelligent devices is obvious: the device + drivers on the host can be made in a much more generic fashion, + there is no longer a need to change (and qualify!) drivers for + every odd new device that is introduced. + + Do's and don't's on interconnections +

+ For cabling and connectors there is a golden rule: get good + stuff. With bus speeds going up all the time you will save + yourself a lot of grief by using good material. + + So, gold plated connectors, shielded cabling, sturdy connector + hoods with strain reliefs etc are the way to go. Second golden + rule: don't use cables longer than necessary. I once spent 3 days + hunting down a problem with a flaky machine only to discover that + shortening the SCSI bus with 1 meter solved the problem. And the + original bus length was well within the SCSI specification. + SCSI bus types +

+ From an electrical point of view, there are two Incompatible bus + types: single-ended and differential. This means that there are + two different main groups of SCSI devices and controllers, which + cannot be mixed on the same bus. It is possible however to use + special converter hardware to transform a single-ended bus into a + differential one (and vice versa). The differences between the + bus types are explained in the next sections. + + In lots of SCSI related documentation there is a sort of jargon + in use to abbreviate the different bus types. A small list: + + + FWD: Fast Wide Differential + FND: Fast Narrow Differential + SE: Single Ended + FN: Fast Narrow + etc. + + + With a minor amount of imagination one can usually imagine what + is meant. + + Wide is a bit ambiguous, it can indicate 16 or 32 bit buses. As + far as I know, the 32 bit variant is not (yet) in use, so wide + normally means 16 bit. + + Fast means that the timing on the bus is somewhat different, so + that on a narrow (8 bit) bus 10 Mbytes/sec are possible instead + of 5 Mbytes/sec for 'slow' SCSI. More on this later. + + It should be noted that the datalines > 8 are only used for + datatransfers and device addressing. The transfers of commands + and status messages etc are only performed on the lowest 8 + datalines. The standard allows narrow devices to operate on + a wide bus. The usable buswidth is negotiated + between the devices. You have to watch your device addressing + closely when mixing wide and narrow. + + Single ended buses +

+ A single-ended SCSI bus uses signals that are either 5 Volts or + 0 Volts (indeed, TTL levels) and are relative to a COMMON + ground reference. A singled ended 8 bit SCSI bus has + approximately 25 ground lines, who are all tied to a single + 'rail' on all devices. A standard single ended bus has a + maximum length of 6 meters. If the same bus is used with + fast-SCSI devices, the maximum length allowed drops to 3 + meters. Fast-SCSI means that instead of 5Mbytes/sec the bus + allows 10Mbytes/sec transfers. + + Please note that this means that + if some devices on your bus use 'fast' to communicate your + bus must adhere to the length restrictions for fast buses! + + It is obvious that with the newer fast-SCSI devices the + buslength can become a real bottleneck. This is why the + differential SCSI bus was introduced in the SCSI-2 standard. + + For connector pinning and connector types please refer to the + SCSI-2 standard (see ) itself, connectors etc are listed there in + painstaking detail. + + Beware of devices using non-standard cabling. For instance + Apple uses a 25pin D-type connecter (like the one on serial + ports and parallel printers). Considering + that the official SCSI bus needs 50 pins you can imagine + the use of this connector needs some 'creative cabling'. + The reduction of the number of ground wires they used + is a bad idea, you better stick to 50 pins cabling + in accordance with the SCSI standard. + + Differential buses +

+ A differential SCSI bus has a maximum length of 25 + meters. Quite a difference from the 3 meters for a single-ended + fast-SCSI bus. The idea behind differential signals is that + each bus signal has it's own return wire. So, each signal is + carried on a (preferably twisted) pair of wires. The voltage + difference between these two wires determines whether the + signal is asserted or de-asserted. To a certain extent the + voltage difference between ground and the signal wire pair is + not relevant (don't try 10 kVolts though..). + + It is beyond the scope of this document to explain why this + differential idea is so much better. Just accept that + electrically seen the use of differential signals gives a much + better noise margin. You will normally find differential buses + in use for inter-cabinet connections. Because of the lower cost + single ended is mostly used for shorter buses like inside + cabinets. + + There is nothing that stops you from using differential stuff + with FreeBSD, as long as you use a controller that has device + driver support in FreeBSD. As an example, Adaptec marketed the + AH1740 as a single ended board, whereas the AH1744 was differential. + The software interface to the host is identical for both. + + Terminators +

+ Terminators in SCSI terminology are resistor networks that are + used to get a correct impedance matching. Impedance matching + is important to get clean signals on the bus, without + reflections or ringing. If you once made a long distance + telephone call on a bad line you probably know what reflections + are. With 20Mbytes/sec travelling over your SCSI bus, you + don't want signals echoing back. + + Terminators come in various incarnations, with more or less + sophisticated designs. Of course, there are internal and + external variants. Almost every SCSI device comes with a + number of sockets in which a number of resistor networks can + (must be!) installed. If you remove terminators from a device, + carefully stock 'm. You will need them when you ever decide to + reconfigure your SCSI bus. There is enough variation in even + these simple tiny things to make finding the exact replacement + a frustrating business. There are also SCSI devices that have + a single jumper to enable or disable a builtin terminator. + There are special terminators you can stick onto a flatcable + bus. Others look like external connectors, so a connector hood + without a cable. So, lots of choice as you can see. + + There is much debate going on if and when you should switch + from simple resistor (passive) terminators to active + terminators. Active terminators contain more or less elaborate + circuits to give more clean bus signals. The general consensus + seems to be that the usefullnes of active termination increases + when you have long buses and/or fast devices. If you ever have + problems with your SCSI buses you might consider trying an + active terminator. Try to borrow one first, they reputedly are + quite expensive. + + Please keep in mind that terminators for differential and + single-ended buses are not identical. You should not + mix the two variants. + + OK, and now where should you install your terminators? This is + by far the most misunderstood part of SCSI. And it is by far + the simplest.. The rule is: every SCSI bus has 2 (two) + terminators, one at each end of the bus. So, two and not + one or three or whatever. Do yourself a favour and stick to + this rule. It will save you endless grief, because wrong + termination has the potential to introduce highly mysterious + bugs. + + A common pitfall is to have an internal (flat)cable in a + machine and also an external cable attached to the + controller. It seems almost everybody forgets to remove the + terminators from the controller. The terminator must now be on + the last external device, and not on the controller! In + general, every reconfiguration of a SCSI bus must pay attention + to this. + + What I did myself is remove all terminators from my SCSI + devices and controllers. I own a couple of external + terminators, for both the Centronics-type external cabling and + for the internal flat cable connectors. This makes + reconfiguration much easier. + + Terminator power +

+ The terminators discussed in the previous chapter need power to + operate properly. On the SCSI bus, a line is dedicated to this + purpose. So, simple huh? + + Not so. Each device can provide it's own terminator power to + the terminator sockets it has on-device. But if you have + external terminators, or when the device supplying the + terminator power to the SCSI bus line is switched off you are + in trouble. + + The idea is that initiators (these are devices that initiate + actions on the bus, a discussion follows) must supply + terminator power. All SCSI devices are allowed (but not + required) to supply terminator power. + + To allow for switched-off devices on a bus, the terminator + power must be supplied to the bus via a diode. This prevents + the backflow of current to switched-off devices. + + To prevent all kinds of nastiness, the terminator power is + usually fused. As you can imagine, fuses might blow. This can, + but does not have to, lead to a non functional bus. If multiple + devices supply terminator power, a single blown fuse will not + put you out of business. A single supplier with a blown fuse + certainly will. Clever external terminators sometimes have a + LED indication that shows whether terminator power is present. + + In newer designs auto-restoring fuses are used who 'reset' + themselves after some time. + + On modern devices, sometimes integrated terminators are + used. These things are special purpose integrated circuits that + can be dis/en-abled with a control pin. It is not necessary to + physically remove them from a device. You may find them on + newer host adapters, sometimes they even are software + configurable, using some sort of setup tool. Consult you + documentation! + + Device addressing +

+ Because the SCSI bus is, ehh, a bus there must be a way to + distinguish or address the different devices connected to it. + + This is done by means of the SCSI or target ID. Each device has + a unique target ID. You can select the ID to which a device + must respond using a set of jumpers, or a dipswitch, or + something similar. Consult the documentation of your device for + more information. + + Beware of multiple devices configured to use the same ID. Chaos + normally reigns in this case. + + For an 8 bit bus, a maximum of 8 targets is possible. The + maximum is 8 because the selection is done bitwise using the 8 + datalines on the bus. For wide this increases to the number of + datalines. + + The higher the SCSI target ID, the higher the priority the + devices has. When it comes to arbitration between devices that + want to use the bus at the same time, the device that has the + highest SCSI ID will win. This also means that the SCSI + hostadapter usually uses target ID 7 (for narrow buses). + + For a further subdivision, the standard allows for Logical + Units or LUNs for short. A single target ID may have multiple + LUNs. For example, a tape device including a tape changer may + have LUN 0 for the tape device itself, and LUN 1 for the + tapechanger. In this way, the host system can address each of + the parts of the tape unit as desired. + + Bus layout +

+ SCSI buses are linear. So, not shaped like Y-junctions, star + topologies, cobwebbs or whatever else people might want to + invent. + + You might notice that the terminator issue discussed earlier + becomes rather hairy if your bus is not linear.. + + The electrical characteristics, it's noise margins and + ultimately the reliability of it all are tightly related to + linear bus rule. + + Stick to the linear bus rule! + + Using SCSI with FreeBSD +

+ About translations, BIOSes and magic.. +

+ As stated before, you should first make sure that you have a + electrically sound bus. + + When you want to use a SCSI disk on your PC as boot disk, you + must aware of some quirks related to PC BIOSes. The PC BIOS in + it's first incarnation used a low level physical interface to the + harddisk. So, you had to tell the BIOS (using a setup tool or a + BIOS builtin setup) how your disk physically looked like. This + involved stating number of heads, number of cylinders, number of + sectors per track, obscure things like precompensation and + reduced write current cylinder etc. + + One might be inclined to think that since SCSI disks are smart + you can forget about this. Alas, the arcane setup issue is still + present today. The system BIOS needs to know how to access your + SCSI disk with the head/cyl/sector method. + + The SCSI host adapter or SCSI controller you have put in your + AT/EISA/PCI/whatever bus to connect your disk therefore has it's + own onboard BIOS. During system startup, the SCSI BIOS takes over + the harddisk interface routines from the system BIOS. To fool the + system BIOS, the system setup is normally set to No harddisk + present. Obvious, isn't it? + + The SCSI BIOS itself presents to the system a so called + translated drive. This means that a fake drive table is + constructed that allows the PC to boot the drive. This + translation is often (but not always) done using a pseudo drive + with 32 heads and 64 sectors per track. By varying the number of + cylinders, the SCSI BIOS adapts to the actual drive size. It is + useful to note that 32 * 64 / 2 = the size of your drive in + megabytes. The division by 2 is to get from disk blocks that are + normally 512 bytes in size to Kbytes. + + Right.. All is well now?! No, it isn't. The system BIOS has + another quirk you might run into. The number of cylinders of a + bootable harddisk cannot be greater than 1024. Using the + translation above, this is a showstopper for disks greater than + 1 Gb. With disk capacities going up all the time this is causing + problems. + + Fortunately, the solution is simple: just use another + translation, e.g. with 128 heads instead of 32. In most cases new + SCSI BIOS versions are available to upgrade older SCSI host + adapters. Some newer adapters have an option, in the form of a + jumper or software setup selection, to switch the translation the + SCSI BIOS uses. + + It is very important that all operating systems on the disk use + the same translation to get the right idea about where to find + the relevant partitions. So, when installing FreeBSD you must + answer any questions about heads/cylinders etc using the + translated values your host adapter uses. + + Failing to observe the translation issue might be un-bootable systems or + operating systems overwriting eachothers partitions. Using fdisk + you should be able to see all partitions. + + As promised earlier: what is this talk about 'lying' devices? As + you might already know, the FreeBSD kernel reports the geometry + of SCSI disks when booting. An example from one of my systems: + + +Feb 9 19:33:46 yedi /386bsd: aha0 targ 0 lun 0: +Feb 9 19:33:46 yedi /386bsd: sd0: 636MB (1303250 total sec), 1632 cyl, 15 head, + 53 sec, bytes/sec 512 + + + This info is retrieved from the SCSI disk itself. Newer disks + often use a technique called zone bit recording. The idea is that + on the outer cylinders of the drive there is more space so more + sectors per track can be put on them. This results in disks that + have more tracks on outer cylinders than on the inner cylinders + and, last but not least, have more capacity. You can imagine that + the value reported by the drive when inquiring about the geometry + now becomes fake. + + SCSI subsystem design +

+ FreeBSD uses a sort of layered SCSI subsystem. For each different + controller card a so called device driver is written. This driver + knows all the intimate details about the hardware it + controls. The driver has a interface to the upper layers of the + SCSI subsystem through which it receives it's commands and + reports back any status. + + On top of the card drivers there are a number of more generic + drivers for a class of devices. More specific: a driver for + tape devices (abbreviation: st), magnetic disks (sd), cdroms (cd) + etc. In case you are wondering where you can find this stuff, it + all lives in /sys/scsi. See the man pages in section 4 + for more details. + + The multi level design allows a decoupling of low-level bit + banging and more high level stuff. Adding support for another + piece of hardware is a much more managable problem. + + Kernel configuration +

+ Dependent on your hardware, the kernel configuration file must + contain a line which describes your hostadapter. This includes + I/O addresses, interrupts etc. Consult the man page for your + adapter driver to get more info. + + Although it is probably an obvious remark: the kernel config + file should reflect your actual hardware setup. So, interrupts, + I/O addresses etc must match the kernel config file. + + An example from the kernel config file (they live in + /sys/i386/conf BTW), with some added comments (between + []): + + +controller ahb0 at isa? bio irq 11 vector ahbintr [driver for Adaptec 174x] +controller aha0 at isa? port "IO_AHA0" bio irq 11 drq 5 vector ahaintr [for Adaptec 154x] +controller sea0 at isa? bio irq 5 iomem 0xc8000 iosiz 0x2000 vector seaintr [for Seagate +ST01/02] +controller scbus0 + +device sd0 [support for 4 SCSI harddisks, sd0 up sd3] +device sd1 +device sd2 +device sd3 + +device st0 [support for 2 SCSI tapes] +device st1 + +device cd0 #Only need one of these, the code dynamically grows [for the cdrom] + + + So, the ahb driver is used for the Adaptec 1740, the aha driver + for the Adaptec 154x etc. If you have more than one card of the + same type in your system you get an ahb1, ahb2 line etc. + + The example above supports 4 SCSI disks. If during boot more + devices of a specific type (e.g. sd disks) are found than are + configured in the booting kernel, the system will complain. You + will have to build and boot a new kernel (after adapting the kernel + configuration file) before you can use all of the devices. It + does not hurt to have 'extra' devices in the kernel, the example + above will work fine when you have only 2 SCSI disks. + + Use man 4 scsi to check for the latest info on the SCSI + subsystem. For more detailed info on hostadapter drivers use eg + man 4 aha for info on the Adaptec 154x driver. + + Tuning your SCSI kernel setup +

+ Experience has shown that some devices are slow to respond to INQUIRY + commands after a SCSI bus reset. An INQUIRY command is sent by the kernel + on boot to see what kind of device (disk, tape, cdrom etc) is connected + to a specific target ID. This process is called device probing by the way. + + To work around this problem, FreeBSD allows a tunable delay time before + the SCSI devices are probed following a SCSI bus reset. You can set this + delaytime in your kernel configuration file using a line like: + + +options "SCSI_DELAY=15" #Be pessimistic about Joe SCSI device + + This line sets the delay time to 15 seconds. On my own system I had to + use 3 seconds minimum to get my trusty old CDROM drive to be recognised. + Start with a high value (say 30 seconds or so) when you have problems + with device recognition. If this helps, tune it back until it just stays + working. + + Rogue SCSI devices +

+ Although the SCSI standard tries to be complete and concise, it is + a complex standard and implementing things correctly is no easy task. + Some vendors do a better job then others. + + This is exactly where the 'rogue' devices come into view. Rogues are + devices that are recognised by the FreeBSD kernel as behaving slightly + (...) non-standard. Rogue devices are reported by the kernel when + booting. An example for two of my cartridge tape units: + + +Feb 25 21:03:34 yedi /386bsd: ahb0 targ 5 lun 0: +Feb 25 21:03:34 yedi /386bsd: st0: Tandberg tdc3600 is a known rogue + +Mar 29 21:16:37 yedi /386bsd: aha0 targ 5 lun 0: +Mar 29 21:16:37 yedi /386bsd: st1: Archive Viper 150 is a known rogue + + + For instance, there are devices that respond to + all LUNs on a certain target ID, even if they are actually only one + device. It is easy to see that the kernel might be fooled into + believing that there are 8 LUNs at that particular target ID. The + confusion this causes is left as an exercise to the user. + + The SCSI subsystem of FreeBSD recognises devices with bad habits by + looking at the INQUIRY response they send when probed. Because the + INQUIRY response also includes the version number of the device + firmware, it is even possible that for different firmware versions + different workarounds are used. + + This scheme works fine, but keep in mind that it of course only + works for devices that are KNOWN to be weird. If you are the first + to connect your bogus Mumbletech SCSI cdrom you might be the one + that has to define which workaround is needed. + + Busmaster host adapters +

+ Most, but not all, SCSI host adapters are bus mastering controllers. + This means that they can do I/O on their own without putting load onto + the host CPU for data movement. + + This is of course an advantage for a multitasking operating system like + FreeBSD. It must be noted however that there might be some rough edges. + + For instance an Adaptec 1542 controller can be set to use different + transferspeeds on the host bus (ISA or AT in this case). The controller + is settable to different rates because not all motherboards can handle + the higher speeds. Problems like hangups, bad data etc might be the + result of using a higher data transfer rate then your motherboard + can stomach. + + The solution is of course obvious: switch to a lower data transfer rate + and try if that works better. + + In the case of a Adaptec 1542, there is an option that can be put + into the kernel config file to allow dynamic determination of the + right, read: fastest feasible, transfer rate. This option is + disabled by default: + + +options "TUNE_1542" #dynamic tune of bus DMA speed + + + Check the man pages for the host adapter that you use. Or better + still, use the ultimate documentation (read: driver source). + + Tracking down problems +

+ The following list is an attempt to give a guideline for the most + common SCSI problems and their solutions. It is by no means + complete. + + + + Check for loose connectors and cables. + + Check and doublecheck the location and number of your terminators. + + Check if your bus has at least one supplier of terminator power + (especially with external terminators. + + Check if no double target IDs are used. + + Check if at least one device provides terminator power to the bus. + + Check if all devices to be used are powered up. + + Make a minimal bus config with as little devices as possible. + + If possible, configure your hostadapter to use slow bus speeds. + + + Further reading

+ If you intend to do some serious SCSI hacking, you might want to + have the official standard at hand: + + Approved American National Standards can be purchased from ANSI at + 11 West 42nd Street, 13th Floor, New York, NY 10036, Sales Dept: + (212) 642-4900. You can also buy many ANSI standards and most + committee draft documents from Global Engineering Documents, 15 + Inverness Way East, Englewood, CO 80112-5704, Phone: (800) + 854-7179, Outside USA and Canada: (303) 792-2181, FAX: (303) 792- + 2192. + + Many X3T10 draft documents are available electronically on the SCSI + BBS (719-574-0424) and on the ncrinfo.ncr.com anonymous ftp site. + + Latest X3T10 committee documents are: + + AT Attachment (ATA or IDE) [X3.221-1994] Approved + ATA Extensions (ATA-2) [X3T10/948D Rev 2i] + Enhanced Small Device Interface (ESDI) [X3.170-1990/X3.170a-1991] Approved + Small Computer System Interface - 2 (SCSI-2) [X3.131-1994] Approved + SCSI-2 Common Access Method Transport and SCSI Interface Module (CAM) + [X3T10/792D Rev 11] + + Other publications that might provide you with additional information are: + +"SCSI: Understanding the Small Computer System Interface", written by NCR +Corporation. Available from: Prentice Hall, Englewood Cliffs, NJ, 07632 +Phone: (201) 767-5937 ISBN 0-13-796855-8 + +"Basics of SCSI", a SCSI tutorial written by Ancot Corporation +Contact Ancot for availability information at: +Phone: (415) 322-5322 Fax: (415) 322-0455 + +"SCSI Interconnection Guide Book", an AMP publication (dated 4/93, Catalog +65237) that lists the various SCSI connectors and suggests cabling schemes. +Available from AMP at (800) 522-6752 or (717) 564-0100 + +"Fast Track to SCSI", A Product Guide written by Fujitsu. +Available from: Prentice Hall, Englewood Cliffs, NJ, 07632 +Phone: (201) 767-5937 ISBN 0-13-307000-X + +"The SCSI Bench Reference", "The SCSI Encyclopedia", and the "SCSI Tutor", +ENDL Publications, 14426 Black Walnut Court, Saratoga CA, 95070 +Phone: (408) 867-6642 + +"Zadian SCSI Navigator" (quick ref. book) and "Discover the Power of SCSI" +(First book along with a one-hour video and tutorial book), Zadian Software, +Suite 214, 1210 S. Bascom Ave., San Jose, CA 92128, (408) 293-0800 + + + On Usenet the newsgroups comp.periphs.scsi and comp.periphs are + noteworthy places to look for more info. You can also find the + SCSI-Faq there, which posted periodically. + + Most major SCSI device and hostadapter suppliers operate ftp sites + and/or BBS systems. They may be valuable sources of information + about the devices you own. diff --git a/share/doc/handbook/slipc.sgml b/share/doc/handbook/slipc.sgml new file mode 100644 index 0000000..39b709f --- /dev/null +++ b/share/doc/handbook/slipc.sgml @@ -0,0 +1,196 @@ + + + +Setting up a SLIP client + +

Contributed by &a.asami;. + +The following is one way to set up a FreeBSD machine for SLIP on a +static host network. For dynamic hostname assignments (i.e., your +address changes each time you dial up), you probably need to do +something much fancier. + + + +Note: for 1.1 systems (not 1.1.5), you need to use /dev/tty01 instead +of /dev/cua01. substitute all the occurences of "cua" in this document +with "tty". + +Note: the default 1.1.5(.1) system only comes with cua/ttyd pairs for +the last two ports (2 and 3), so if your modem is at sio0/sio1 +(COM1/COM2), you need to make the devices. Try "cd /dev; sh MAKEDEV +cua01" to make the new special files for sio1 (ditto for sio0). This +will delete tty01, but you shouldn't need it anymore...or you can make +a symbolic link /dev/tty01 -> ttyd1 if you don't want to hunt down all +occurences of tty01 in your setup files. + +I actually have a symbolic link /dev/modem -> cua01 (and /dev/mouse -> +ttyd0). I use only the modem/mouse names in my configuration files. +This helped a lot when I switched from 1.1 to 1.1.5.1 (tty01 => cua01) +and when I had to move my modem temporarily to sio2 to enable the +RS-232C port on the serial card. It can become quite cumbersome when +you need to fix a bunch of files in /etc and .kermrc's all over the +system! + +First, make sure you have + +pseudo-device sl 2 + +in your kernel's config file. It is included in the GENERIC, GENERICAH +and GENERICBT kernels, so this won't be a problem unless you deleted it. + +Things you have to do only once + +

+ Add your home machine, the gateway and nameservers to your + /etc/hosts file. Mine looks like this: + +127.0.0.1 localhost loghost +136.152.64.181 silvia.HIP.Berkeley.EDU silvia.HIP silvia + +136.152.64.1 inr-3.Berkeley.EDU inr-3 slip-gateway +128.32.136.9 ns1.Berkeley.edu ns1 +128.32.136.12 ns2.Berkeley.edu ns2 + + By the way, silvia is the name of the car that I had when I was + back in Japan (it's called 2?0SX here in U.S.). + + Make sure you have "hosts" before "bind" in your /etc/host.conf. + Otherwise, funny things may happen. + + Edit the /etc/netstart and add this to the end of the file: + +# set up slip +gateway=slip-gateway +ifconfig sl0 inet $hostname $gateway netmask 0xffffff00 +route add default $gateway + + Note that because of the "slip-gateway" entry in /etc/hosts, there + is no local dependency in the netstart file. Also, you might want + to un-comment the "route add $hostname localhost" line. + + Make a file /etc/resolv.conf which contains: + +domain HIP.Berkeley.EDU +nameserver 128.32.136.9 +nameserver 128.32.136.12 + + As you can see, these set up the nameserver hosts. Of course, the + actual addresses depend on your environment. + + Set the password for root and toor (and any other accounts that + doesn't have a password). Use passwd, don't edit the passwd or + passwd.master files! + + Edit /etc/myname and reboot the machine. + + + +Making a SLIP connection + +

+ Dial up, type "slip" at the prompt, enter your machine name and + password. The things you need to enter depends on your + environment. I use kermit, with a script like this: + +# kermit setup +set modem hayes +set line /dev/cua01 +set speed 57600 +set parity none +set flow rts/cts +set terminal bytesize 8 +set file type binary +# The next macro will dial up and login +define slip dial 643-9600, input 10 =>, if failure stop, - +output slip\x0d, input 10 Username:, if failure stop, - +output silvia\x0d, input 10 Password:, if failure stop, - +output ***\x0d, echo \x0aCONNECTED\x0a + + (of course, you have to change the hostname and password to fit + yours). Then you can just type "slip" from the kermit prompt to + get connected. + + Note: leaving your password in plain text anywhere in the + filesystem is generally a BAD idea. Do it at your own risk. I'm + just too lazy. + + Note: If you have an 1.1 machine, and kermit doesn't give you a + prompt, try "stty -f /dev/tty01 clocal". I put this in + /etc/rc.local so that it works the first time I boot the machine. + This doesn't apply to 1.1.5(.1) systems, as cua0? are already + configured for dialouts. + + Leave the kermit there (you can suspend it by "z") and as root, + type + +slattach -h -c -s 57600 /dev/cua01 + + if you are able to "ping" hosts on campus, you are connected! + If it doesn't work, you might want to try "-a" instead of "-c". + + +How to shutdown the connection + +

Type "ps gx" (as root) to find out the PID of slattach, and use + "kill -INT" to kill it. + Then go back to kermit ("fg" if you suspended it) and exit from it + ("q"). + + The slattach man page says you have to use "ifconfig sl0 down" to + mark the interface down, but this doesn't seem to make any + difference for me. ("ifconfig sl0" reports the same thing.) + + Some times, your modem might refuse to drop the carrier (mine + often does). In that case, simply start kermit and quit it again. + It usually goes out on the second try. + + When you want to connect again, go back to (XXX). You may have to + watch out for clocal mode. If "stty -f /dev/tty01" doesn't tell + you it's clocal, you need to re-set it before kermitting. Again, + this is only for 1.1 machines. + +Troubleshooting + +

If it doesn't work, feel free to ask me. The things that people +tripped over so far: + + Not using "-c" or "-a" in slattach (I have no idea why this can be + fatal, but adding this flag solved the problem for at least one + person) + + Using "s10" instead of "sl0" (might be hard to see the difference on + some fonts. + + Try "ifconfig sl0" to see your interface status. I get: + +silvia# ifconfig sl0 +sl0: flags=10 + inet 136.152.64.181 --> 136.152.64.1 netmask ffffff00 + + +Also, "netstat -r" will give the routing table, in case you get the +"no route to host" messages from ping. Mine looks like: + +silvia# netstat -r +Routing tables +Destination Gateway Flags Refs Use IfaceMTU Rtt +Netmasks: +(root node) +(root node) + +Route Tree for Protocol Family inet: +(root node) => +default inr-3.Berkeley.EDU UG 8 224515 sl0 - - +localhost.Berkel localhost.Berkeley UH 5 42127 lo0 - 0.438 +inr-3.Berkeley.E silvia.HIP.Berkele UH 1 0 sl0 - - +silvia.HIP.Berke localhost.Berkeley UGH 34 47641234 lo0 - 0.438 +(root node) + +(this is after transferring a bunch of files, your numbers should be +smaller). + \ No newline at end of file diff --git a/share/doc/handbook/slips.sgml b/share/doc/handbook/slips.sgml new file mode 100644 index 0000000..799ead0 --- /dev/null +++ b/share/doc/handbook/slips.sgml @@ -0,0 +1,488 @@ + + +Setting up a SLIP server + +

Contributed by &a.ghelmer;. + +This document provides suggestions for setting up SLIP Server services +on a FreeBSD system, which typically means configuring your system to +automatically startup connections upon login for remote SLIP clients. +I've written this document based on my own experience; however, as +your system and needs may be different, this document may not answer +all of your questions, and I cannot be responsible if you damage your +system or lose data due to attempting to follow the suggestions here. + +I have only setup SLIP Server services on a FreeBSD 1.1 system, so if +you are running a different version (such as FreeBSD 2.0), your system +may be different. + +Prerequisites

+This document is very technical in nature, so background knowledge is +required. I must assume that you are familiar with the TCP/IP network +protocol, and in particular, network and node addressing, network +address masks, subnetting, routing, and routing protocols, such as +RIP. Configuring SLIP services on a dial-up server requires a +knowledge of these concepts, and if you are not familiar with them, +please read a copy of either Craig Hunt's TCP/IP Network +Administration published by O'Reilly & Associates, Inc. (ISBN +Number 0-937175-82-X), or Douglas Comer's book on the TCP/IP protocol. + +I will assume that you have already setup your modem(s) and configured +the appropriate system files to allow logins through your modems (see +the manual pages for sio(4) for information on the serial +port device driver and ttys(5), gettytab(5), +getty(8), & init(8) for information relevant to +configuring the system to accept logins on modems, and perhaps +stty(1) for information on setting serial port parameters +[such as clocal for directly-connected serial +interfaces]). + +Quick Overview + +

+In its typical configuration, using FreeBSD as a SLIP server works as +follows: a SLIP user dials up your FreeBSD SLIP Server system and logs +in with a special SLIP login ID that uses /usr/sbin/sliplogin +as the special user's shell. The /etc/slip.hosts to find a matching line for the special +user, and if it finds a match, connects the serial line to an +available SLIP interface and then runs the shell script +/etc/slip.login to configure the SLIP interface. + +An Example of a SLIP Server Login + +

+For example, if my SLIP user ID were Shelmerg, that user's +entry in /etc/master.passwd would look something like this +(except it would be all on one line): + + +Shelmerg:password:1964:89::0:0:Guy Helmer - SLIP: + /usr/users/Shelmerg:/usr/sbin/sliplogin + + +and, when I log in with that user ID, sliplogin will search +/etc/slip.hosts for a line that had a matching user ID; on my +system, I may have a line in /etc/slip.hosts that reads: + + +Shelmerg dc-slip sl-helmer 0xfffffc00 autocomp + + +sliplogin will find that matching line, hook the serial line I'm on +into the next available SLIP interface, and then execute +/etc/slip.login like this: + + +/etc/slip.login 0 19200 Shelmerg dc-slip sl-helmer 0xfffffc00 autocomp + + +If all goes well, /etc/slip.login will issue an +ifconfig for the SLIP interface to which sliplogin attached +itself (slip interface 0, in the above example, which was the first +parameter in the list given to slip.login) to set the local +IP address (dc-slip), remote IP address (sl-helmer), +network mask for the SLIP interface (0xfffffc00), and any +additional flags (autocomp). If something goes wrong, +sliplogin usually logs good informational messages via the daemon +syslog facility, which usually goes into /var/log/messages +(see the manual pages for syslogd(8) and +syslog.conf(5), and perhaps check /etc/syslog.conf +to see to which files syslogd is logging). + +OK, enough of the examples -- let's dive into setting up the system. + +Kernel Configuration +

+FreeBSD's default kernels usually come with two SLIP interfaces +defined (sl0 and sl1); you can use netstat +-i to see whether these interfaces are defined in your kernel. + +Sample output from netstat -i: + + +Name Mtu Network Address Ipkts Ierrs Opkts Oerrs Coll +ed0 1500 0.0.c0.2c.5f.4a 291311 0 174209 0 133 +ed0 1500 138.247.224 ivory 291311 0 174209 0 133 +lo0 65535 79 0 79 0 0 +lo0 65535 loop localhost 79 0 79 0 0 +sl0* 296 0 0 0 0 0 +sl1* 296 0 0 0 0 0 + + +The sl0 and sl1 interfaces shown in netstat +-i's output indicate that there are two SLIP interfaces built +into the kernel. (The asterisks after the sl0 and +sl1 indicate that the interfaces are ``down''.) + +However, FreeBSD's default kernels do not come configured to forward +packets (ie, your FreeBSD machine will not act as a router) due to +Internet RFC requirements for Internet hosts (see RFC's 1009 +[Requirements for Internet Gateways], 1122 +[Requirements for Internet Hosts -- Communication Layers], +and perhaps 1127 [A Perspective on the Host Requirements +RFCs]), so if you want your FreeBSD SLIP Server to act as a +router, you'll have to add the line options GATEWAY to your +machine's kernel configuration file and re-compile the kernel anyway. +(Trivia: ``Gateways'' are the Internet's old name for what are now +usually called ``routers''.) + +Please see the BSD System Manager's Manual chapter on ``Building +Berkeley Kernels with Config'' [the source for which is in +/usr/src/share/doc/smm] and ``FreeBSD Configuration +Options'' [in /sys/doc/options.doc] for more +information on configuring and building kernels. You may have to +unpack the kernel source distribution if haven't installed the system +sources already (srcdist/srcsys.?? in FreeBSD 1.1, +srcdist/sys.?? in FreeBSD 1.1.5.1, or the entire source +distribution in FreeBSD 2.0) to be able to configure and build +kernels. + +You'll notice that near the end of the default kernel configuration +file (/sys/i386/conf/GENERICAH) is a line that reads: + + +pseudo-device sl 2 + + +which is the line that defines the number of SLIP devices available in +the kernel; the number at the end of the line is the maximum number of +SLIP connections that may be operating simultaneously. + +See the document ``Building Berkeley Kernels with Config'' and the +manual page for config(8) to see how to configure and build +kernels. + +Sliplogin Configuration + +

+As mentioned earlier, there are three files in the /etc directory that are part of the configuration for +/usr/sbin/sliplogin (see sliplogin(8) for the actual +manual page for sliplogin): slip.hosts, which +defines the SLIP users & their associated IP addresses; +slip.login, which usually just configures the SLIP interface; +and (optionally) slip.logout, which undoes slip.login's +effects when the serial connection is terminated. + +slip.hosts Configuration + +

+/etc/slip.hosts contains lines which have at least four items +listed: + + + SLIP user's login ID + Local address (local to the SLIP server) of the SLIP link + Remote address of the SLIP link + Network mask + + +The local and remote addresses may be host names (resolved to IP +addresses by /etc/hosts or by the domain name service, +depending on your specifications in /etc/host.conf), and I +believe the network mask may be a name that can be resolved by a +lookup into /etc/networks. On one of my systems, +/etc/slip.hosts looks like this: + + +----- begin /etc/slip.hosts ----- +# +# login local-addr remote-addr mask opt1 opt2 +# (normal,compress,noicmp) +# +Shelmerg dc-slip sl-helmerg 0xfffffc00 autocomp +----- end /etc/slip.hosts ------ + + +At the end of the line is one or more of the options: + + + normal - no header compression + compress - compress headers + autocomp - compress headers if the remote end allows it + noicmp - disable ICMP packets (so any ``ping'' packets will be + dropped instead of using up your bandwidth) + + +Your choice of local and remote addresses for your SLIP links depends +on whether you are going to dedicate a TCP/IP subnet or if you are +going to use ``proxy ARP'' on your SLIP server (it's not ``true'' proxy +ARP, but that is the terminology that I will use in this document to +describe it). If you're not sure which method to select or how to +assign IP addresses, please refer to the TCP/IP books referenced in +the section and/or consult your IP network manager. + +If you are going to use a separate subnet for your SLIP clients, you +will need to allocate the subnet number out of your assigned IP +network number and assign each of your SLIP client's IP numbers out of +that subnet. Then, you will probably either need to configure a +static route to the SLIP subnet via your SLIP server on your nearest +IP router, or install gated on your FreeBSD SLIP server and +configure it to talk the appropriate routing protocols to your other +routers to inform them about your SLIP server's route to the SLIP +subnet. + +Otherwise, if you will use the ``proxy ARP'' method, you will need to +assign your SLIP client's IP addresses out of your SLIP server's +Ethernet subnet, and you'll also need to adjust your +/etc/slip.login and /etc/slip.logout scripts to use +arp(8) to manage the proxy-ARP entries in the SLIP server's +ARP table. + +slip.login Configuration + +

+The typical /etc/slip.login file looks like this: + + +----- begin /etc/slip.login ----- +#!/bin/sh - +# +# @(#)slip.login 5.1 (Berkeley) 7/1/90 + +# +# generic login file for a slip line. sliplogin invokes this with +# the parameters: +# 1 2 3 4 5 6 7-n +# slipunit ttyspeed loginname local-addr remote-addr mask opt-args +# +/sbin/ifconfig sl$1 inet $4 $5 netmask $6 +----- end /etc/slip.login ----- + + +This slip.login file merely ifconfig's the appropriate SLIP +interface with the local and remote addresses and network mask of the +SLIP interface. + +If you have decided to use the ``proxy ARP'' method (instead of using +a separate subnet for your SLIP clients), your /etc/slip.login +file will need to look something like this: + + +----- begin /etc/slip.login for "proxy ARP" ----- +#!/bin/sh - +# +# @(#)slip.login 5.1 (Berkeley) 7/1/90 + +# +# generic login file for a slip line. sliplogin invokes this with +# the parameters: +# 1 2 3 4 5 6 7-n +# slipunit ttyspeed loginname local-addr remote-addr mask opt-args +# +/sbin/ifconfig sl$1 inet $4 $5 netmask $6 +# Answer ARP requests for the SLIP client with our Ethernet addr +/usr/sbin/arp -s $5 00:11:22:33:44:55 pub +----- end /etc/slip.login for "proxy ARP" ----- + + +The additional line in this slip.login, arp -s $5 +00:11:22:33:44:55 pub, creates an ARP entry in the SLIP server's +ARP table. This ARP entry causes the SLIP server to respond with the +SLIP server's Ethernet MAC address whenever a another IP node on the +Ethernet asks to speak to the SLIP client's IP address. + +When using the example above, be sure to replace the Ethernet MAC +address (00:11:22:33:44:55) with the MAC address of your +system's Ethernet card, or your ``proxy ARP'' will definitely not work! +You can discover your SLIP server's Ethernet MAC address by looking at +the results of running netstat -i; the second line of the output +should look something like: + + +ed0 1500 0.2.c1.28.5f.4a 191923 0 129457 0 116 + ^^^^^^^^^^^^^^^ + + +which indicates that this particular system's Ethernet MAC address is +00:02:c1:28:5f:4a -- the periods in the Ethernet MAC address +given by netstat -i must be changed to colons and leading zeros +should be added to each single-digit hexadecimal number to convert the +address into the form that arp(8) desires; see the manual page on +arp(8) for complete information on usage. + +Note that when you create /etc/slip.login and +/etc/slip.logout, the ``execute'' bit (ie, chmod 755 +/etc/slip.login /etc/slip.logout) must be set, or +sliplogin will be unable to execute it. + +slip.logout Configuration + +

+ +/etc/slip.logout isn't strictly needed (unless you are +implementing ``proxy ARP''), but if you decide to create it, this is +an example of a basic slip.logout script: + + +----- begin /etc/slip.logout ----- +#!/bin/sh - +# +# slip.logout + +# +# logout file for a slip line. sliplogin invokes this with +# the parameters: +# 1 2 3 4 5 6 7-n +# slipunit ttyspeed loginname local-addr remote-addr mask opt-args +# +/sbin/ifconfig sl$1 down +----- end /etc/slip.logout ----- + + +If you are using ``proxy ARP'', you'll want to have +/etc/slip.logout remove the ARP entry for the SLIP client: + + +----- begin /etc/slip.logout for "proxy ARP" ----- +#!/bin/sh - +# +# @(#)slip.logout + +# +# logout file for a slip line. sliplogin invokes this with +# the parameters: +# 1 2 3 4 5 6 7-n +# slipunit ttyspeed loginname local-addr remote-addr mask opt-args +# +/sbin/ifconfig sl$1 down +# Quit answering ARP requests for the SLIP client +/usr/sbin/arp -d $5 +----- end /etc/slip.logout for "proxy ARP" ----- + + +The arp -d $5 removes the ARP entry that the ``proxy ARP'' +slip.login added when the SLIP client logged in. + +It bears repeating: make sure /etc/slip.logout has the +execute bit set for after you create it (ie, chmod 755 +/etc/slip.logout). + +Routing Considerations + +

+If you are not using the ``proxy ARP'' method for routing packets +between your SLIP clients and the rest of your network (and perhaps +the Internet), you will probably either have to add static routes to +your closest default router(s) to route your SLIP client subnet via +your SLIP server, or you will probably need to install and configure +gated on your FreeBSD SLIP server so that it will tell your +routers via appropriate routing protocols about your SLIP subnet. + +Static Routes + +

+Adding static routes to your nearest default routers can be +troublesome (or impossible, if you don't have authority to do so...). +If you have a multiple-router network in your organization, some +routers, such as Cisco and Proteon, may not only need to be configured +with the static route to the SLIP subnet, but also need to be told +which static routes to tell other routers about, so some expertise and +troubleshooting/tweaking may be necessary to get static-route-based +routing to work. + +Running gated + +

+An alternative to the headaches of static routes is to install +gated on your FreeBSD SLIP server and configure it to use the +appropriate routing protocols (RIP/OSPF/BGP/EGP) to tell other routers +about your SLIP subnet. ftp.gated.cornell.edu in the directory /pub/gated; I +believe the current version as of this writing is +gated-R3_5Alpha_8.tar.Z, which includes support for FreeBSD +``out-of-the-box''. Complete information and documentation on +gated is available on the Web starting at +http://www.gated.cornell.edu/. Compile and install it, and +then write a /etc/gated.conf file to configure your gated; +here's a sample, similar to what I use on my FreeBSD SLIP server: + + +----- begin sample /etc/gated.conf for gated version 3.5Alpha5 ----- +# +# gated configuration file for dc.dsu.edu; for gated version 3.5alpha5 +# Only broadcast RIP information for xxx.xxx.yy out the ed Ethernet interface +# +# +# tracing options +# +traceoptions "/var/tmp/gated.output" replace size 100k files 2 general ; + +rip yes { + interface sl noripout noripin ; + interface ed ripin ripout version 1 ; + traceoptions route ; +} ; + +# +# Turn on a bunch of tracing info for the interface to the kernel: +kernel { + traceoptions remnants request routes info interface ; +} ; + +# +# Propagate the route to xxx.xxx.yy out the Ethernet interface via RIP +# + +export proto rip interface ed { + proto direct { + xxx.xxx.yy mask 255.255.252.0 metric 1; # SLIP connections + } ; +} ; + +# +# Accept routes from RIP via ed Ethernet interfaces + +import proto rip interface ed { + all ; +} ; + +----- end sample /etc/gated.conf ----- + + +The above sample gated.conf file broadcasts routing +information regarding the SLIP subnet xxx.xxx.yy via RIP onto +the Ethernet; if you are using a different Ethernet driver than the +/var/tmp/gated.output for debugging gated's +activity; you can certainly turn off the tracing options if +gated works OK for you. I've changed my SLIP subnet's +address to xxx.xxx.yy throughout the above file; you'll need +to change the xxx.xxx.yy's into the network address of your +own SLIP subnet (be sure to change the net mask in the proto +direct clause as well). + +When you get gated built and installed and create a +configuration file for it, you'll need to run gated in place +of routed on your FreeBSD system; change the +routed/gated startup parameters in /etc/netstart as +appropriate for your system. Please see the manual page for +gated for information on gated's command-line +parameters. + +Acknowledgements + +

+Thanks to these people for comments and advice regarding this FAQ: + + + + + + diff --git a/share/doc/handbook/submitters.sgml b/share/doc/handbook/submitters.sgml new file mode 100644 index 0000000..eefc21a --- /dev/null +++ b/share/doc/handbook/submitters.sgml @@ -0,0 +1,181 @@ + + + +Contributing to FreeBSD + +

Contributed by &a.jkh;. + +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 *tested*! Many people have developed an original concept +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! :-) + +Submissions to FreeBSD can generally be classified into four catagories: + + Ideas, general suggestions, bug reports. + Addition, deletion, renaming or patching of existing sources. + Significant contribution of a large body of independant work. + Porting of freely available software. + +A submission in *any* of these catagories is highly welcomed as they +are each, in their own way, quite significant to the project. + + +Ideas and suggestions + +

An idea, suggestion or fix can be communicated in one of the following ways: + + An idea or suggestion of general technical interest should be + mailed to <hackers@freebsd.org>. Likewise, people with an interest + in such things (and a tolerance for a HIGH volume of mail!) may + subscribe by sendimg mail to <majordomo@freebsd.org>. See also the + file /usr/share/FAQ/mailing-list.FAQ. + + An actual bug report should be filed by using the send-pr(1) + command (``man send-pr'' for information). This will prompt + you for various fields to fill in. Simply go to the fields + surrounded by <>'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 (which you should also reference 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 send-pr command, then you may also + file a bug report (or follow-up to one) by sending mail to: + + <bugs@freebsd.org> + + +Changes to the existing code + +

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 (see /usr/share/FAQ/current-policy.FAQ and /usr/share/FAQ/ctm.FAQ) for + the convenience of developers who wish to actively work on the system. + + 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 + <announce@freebsd.org> 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, + then please, 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 (or easier :) 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 diff(1) command, with the FreeBSD maintainers preferring to receive + diffs in `context diff' form. See the man page for diff for more details + on producing both context and recursive context diffs + (diff -c <oldfile> <newfile> or diff -c -r <olddir> <newdir>). + + 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 patch(1) command - see patch man page), you + should bundle them up in an email message and send it, along with a brief + description of what the diffs are for, to <hackers@freebsd.org>. 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 tar file and running the `uuencode' program on it before + sending the output of that to <hackers@freebsd.org>. See the man pages + on tar and uuencode for more info on bundling files through the mail this + way. + + If your change is of a potentially sensitive nature, e.g. 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 <core@freebsd.org> rather than <hackers@freebsd.org>. 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 VERY BUSY and so + you should really only mail to them in cases where mailing to hackers + truly is impractical. + + +Contributions of new code + +

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 (see above) + or upload them to our ftp site: + + + + 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. The view of the FreeBSD project towards + acceptable copyrights (for code included in FreeBSD) are: + + + Contributions under the BSD copyright (see the file + /usr/share/examples/etc/bsd-style-copyright for a template) + is 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. + + Contributions under the GNU Public License, or "GPL". This is + not quite as popular a solution for us, due to (all religious + issues aside) 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 /sys/gnu or /usr/src/gnu. + + 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. + + +Porting of software + +

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 (we hope) framework. The ports collection also saves + considerable space by not actually containing the the majority of the + sources being ported. This can be confusing to the new user and the file + /usr/share/FAQ/ports.FAQ goes some way towards explaing how it all works. + + If you have the ports collection on your machine, the file + /usr/ports/GUIDELINES also helps to explain the process of creating + and contributing a port of your own. For more information on the ports + collection (that wasn't available in the FAQ), you may also send mail to + <ports@freebsd.org>. + + +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/share/doc/handbook/sup.sgml b/share/doc/handbook/sup.sgml new file mode 100644 index 0000000..fd43baf --- /dev/null +++ b/share/doc/handbook/sup.sgml @@ -0,0 +1,92 @@ + + + + +SUP + +

Contributed by &a.jkh; and &a.gclarkii;. + +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. + +Getting setup + +

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: + + ftp://ftp.FreeBSD.ORG:/pub/FreeBSD/packages/sup.tgz + +Install the sup package using pkg_add and add the following line to +your /etc/services file: + + sup 871/tcp #sup + + +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: + + sup supfile + +If you wish to see what sup is doing "verbosely", give it the -v option, +like so: + + sup -v supfile + +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: + + ftp://ftp.FreeBSD.ORG:/pub/FreeBSD/FAQ/current-policy.FAQ + +For important information on just what we can and cannot do for you as +a -current user. + +Description of FreeBSD SUP distributions + +

For the main FreeBSD distribution: + +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 + + +And for the ports collection: + +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-shells: /usr/ports/shells various UN*X shells +ports-utils: /usr/ports/utils miscellaneous utilities +ports-x11: /usr/ports/x11 X11 software + \ No newline at end of file diff --git a/share/doc/handbook/troubleshooting.sgml b/share/doc/handbook/troubleshooting.sgml new file mode 100644 index 0000000..4b6271a --- /dev/null +++ b/share/doc/handbook/troubleshooting.sgml @@ -0,0 +1,185 @@ + + + +Troubleshooting + +

The following tips and tricks may help you turn a + failing (or failed) installation attempt into a success. + Please read them carefully. + + + Hardware conflict or misconfiguration + + +

+ Problem: A device is conflicting with + another or doesn't match the kernel's compiled-in IRQ or + address. + + Cause: 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. + + Solution: There are several possible + solutions. The first, and easiest, is to boot the kernel + with the -c flag. When you see the initial boot prompt + (from floppy or hard disk), type: + + +/kernel -c + + + This will boot just past the memory sizing code and then + drop into a dynamic kernel configuration utility. Type + `?' 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 -c 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. + + 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. + + + + + My floppy-tape drive isn't probed + +

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! + + + When I boot for the first time, it still looks for + /386bsd! + +

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! :-) + + + I want to boot FreeBSD off the second drive. It + doesn't! + +

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. + + + Newfs crashes, requesting that blocksize be 32K + +

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. + + + FreeBSD won't boot off the hard disk + +

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. + + + + FreeBSD still won't boot off the hard disk + +

Cause: No boot code is installed in sector 1. + + Solution: Chose the Write MBR (B)oot code in the FDISK + editor. + + + Nope, FreeBSD's still not booting from the hard + disk + +

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. -- cgit v1.1