.H2 "Terminology"
A quick rundown of terminology:
.LB 10 0 \& \& 1 1
.LI "bps"
Bits per Second - the rate at which data is transmitted
.LI "DTE"
Data Terminal Equipment - for example, your computer
.LI "DCE"
Data Communications Equipment -  your modem
.LI "RS-232"
EIA standard for serial communications via hardware
.LE
If you need more information about these terms and data communications
in general, the author remembers reading that \fIThe RS-232 Bible\fP
(anybody have an ISBN?) is a good reference.
.P
When talking about communications data rates, the author doesn't use the term
\fBbaud\fP.  Baud refers to the number of electrical state transitions that may
be made in a period of time, while \fBbps\fP (bits per second) is the
``correct'' term to use (at least it doesn't seem to bother the curmudgeons
quite a much).
.H2 "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.
.P
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.
.H2 "Modems and Cables"
A background knowledge of these items is assumed
.Ls B
.LI
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)
.LI
You are familiar with your modem's command set, or know where to look up needed
commands
.LI
You know how to configure your modem (probably via a terminal communications
program) so you can set the non-volatile RAM parameters
.LE
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:
.Ls B
.LI
Transmitted Data (\fISD\fP)
.LI
Received Data (\fIRD\fP)
.LI
Request to Send (\fIRTS\fP)
.LI
Clear to Send (\fICTS\fP)
.LI
Data Set Ready (\fIDSR\fP)
.LI
Data Terminal Ready (\fIDTR\fP)
.LI
Carrier Detect (\fICD\fP)
.LI
Signal Ground (\fISG\fP)
.LE
FreeBSD needs the \fIRTS\fP and \fICTS\fP signals for flow-control at speeds
above 2400bps, the \fICD\fP signal to detect when a call has been answered or
the line has been hung up, and the \fIDTR\fP signal to reset the modem after a
session is complete.  Some cables are wired without all of the needed signals,
so if you have problems, such as a login session not going away when the line
hangs up, you may have a problem with your cable.
.P
The second prerequisite depends on the modem(s) you use.  If you don't know your
modem's command set by heart, you will need to have the modem's reference book
or user's guide handy.  Sample commands for USR Sportster 14,400 external modems
will be given, which you may be able to use as a reference for your own modem's
commands.
.P
Lastly, you'll need to know how to setup your modem so that it will work well
with FreeBSD.  Like other UNIX-like operating systems, FreeBSD uses the hardware
signals to find out when a call has been answered or a line has been hung up and
to hangup and reset the modem after a call.  FreeBSD avoids sending commands to
the modem or watching for status reports from the modem.  If you are familiar
with connecting modems to PC-based bulletin board systems, this may seem
awkward.
.H2 "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.
.H2 "Quick Overview"
Here is the process that FreeBSD follows to accept dialup logins.  A \fIgetty\fP
process, spawned by \fIinit\fP, patiently waits to open the assigned serial port
(\fI/dev/ttyd0\fP, for our example).  The command \fCps ax\fP might show this:
.Ds
4850 ??  I      0:00.09 /usr/libexec/getty V19200 ttyd0
.De
When a user dials the modem's line and the modems connect, the \fICD\fP line is
asserted by the modem.  The kernel notices that carrier has been detected and
completes \fIgetty\fP's open of the port.  \fIgetty\fP sends a \fClogin:\fP
prompt at the specified initial line speed.  \fIgetty\fP watches to see if
legitimate characters are received, and, in a typical configuration, if it finds
junk (probably due to the modem's connection speed being different than
\fIgetty\fP's speed), \fIgetty\fP tries adjusting the line speeds until it
receives reasonable characters.
.P
We hope \fIgetty\fP finds the correct speed and the user sees a \fClogin:\fP
prompt.  After the user enters his/her login name, \fIgetty\fP executes
\fI/usr/bin/login\fP, which completes the login by asking for the user's
password and then starting the user's shell.
.P
Let's dive into the configuration...
.H2 "Kernel Configuration"
FreeBSD kernels typically come prepared to search for four serial ports, known
in the PC-DOS world as \fCCOM1:\fP, \fCCOM2:\fP, \fCCOM3:\fP, and \fCCOM4:\fP.
FreeBSD can presently also handle ``dumb'' multiport serial interface cards,
such as the Boca Board 1008 and 2016 (please see the manual page \fIsio\fP
for kernel configuration information if you have a multiport serial card).  The
default kernel only looks for the standard COM ports, though.
.P
To see if your kernel recognizes any of your serial ports, watch for messages
while the kernel is booting, or use the \fI/sbin/dmesg\fP command to replay the
kernel's boot messages.  In particular, look for messages that start with the
characters \fIsio\fP.  Hint: to view just the messages that have the word
\fIsio\fP, use the command
.Ds
/usr/sbin/dmesg | grep 'sio'
.De
For example, on a system with four serial ports, these are the serial-port
specific kernel boot messages:
.Ds
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
.De
If your kernel doesn't recognize all of your serial ports, you'll probably need
to configure a custom FreeBSD kernel for your system.
.P
Please see the BSD System Manager's Manual chapter on ``Building Berkeley
Kernels with Config'' [the source for which is in \fI/usr/src/share/doc/smm\fP]
and ``FreeBSD Configuration Options'' [in \fI/sys/doc/options.doc\fP] 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 to be
able to configure and build kernels.
.P
Create a kernel configuration file for your system (if you haven't already) by
\fIcd\fPing to \fI/sys/i386/conf\fP.  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 \fIYOURSYS\fP, where \fIYOURSYS\fP is the
name of your system, but in upper-case letters.  Edit the file, and change the
device lines
.Ds
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
.De
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
\fCsio\fP man page for complete information on how to write configuration
lines for multiport boards.  Be careful if you are using a configuration file
that was previously used for a different version of FreeBSD because the device
flags have changed between versions.
.P
Note that \fCport "IO_COM1"\fP is a substitution for \fCport 0x3f8\fP,
\fCIO_COM2\fP is \fC0x2f8\fP, \fCIO_COM3\fP is \fC0x3e8\fP, and \fCIO_COM4\fP is
\fC0x2e8\fP, which are fairly common port addresses for their respective serial
ports; interrupts 4, 3, 5, and 9 are fairly common interrupt request lines.
Also note that regular serial ports \fBcan't\fP 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).
.P
When you are finished adjusting the kernel configuration file, use the program
\fIconfig\fP as documented in ``Building Berkeley Kernels with Config'' and the
\fIconfig\fP manual page to prepare a kernel building directory, then build,
install, and test the new kernel.
.H2 "Device Special Files"
Most devices in the kernel are accessed through ``device special files'', which
are located in the \fI/dev\fP directory.  The \fIsio\fP devices are accessed
through the \fI/dev/ttyd?\fP (dial-in) and \fI/dev/cua0?\fP (call-out) devices.
There are also initialization devices (\fI/dev/ttyid?\fP and \fI/dev/cuai0?\fP)
and locking devices (\fI/dev/ttyld?\fP and \fI/dev/cual0?\fP).  The
initialization devices are used to initialize communications port parameters
each time a port is opened, such as \fCcrtscts\fP for modems which use
\fICTS/RTS\fP 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 \fItermios\fP, \fIsio\fP, and \fIstty\fP for information
on the terminal settings, locking & initializing devices, and setting terminal
options, respectively.
.H2 "Making Device Special Files"
A shell script called \fIMAKEDEV\fP in the \fI/dev\fP directory manages the
device special files.  To use \fIMAKEDEV\fP to make dialup device special files
for \fICOM1:\fP (port 0), \fIcd\fP to \fI/dev\fP and issue the command
\fIMAKEDEV ttyd0\fP.  Likewise, to make dialup device special files for
\fICOM2:\fP (port 1), use \fIMAKEDEV ttyd1\fP.
.P
\fIMAKDEV\fP not only creates the \fI/dev/ttyd?\fP device special files, but
also creates the \fI/dev/cua0?\fP and all of the initializing and locking
special filesand removes the hardwired terminal special file \fI/dev/tty0?\fP,
if it exists.
.P
After making new device special files, be sure to check the permissions on the
files (especially the \fI/dev/cua*\fP 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 \fI/dev/cua*\fP files should be sufficient:
.Ds
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
.De
These permissions allow the user \fCuucp\fP and users in the group \fCdialer\fP
to use the call-out devices.
.H2 "Configuration Files"
There are three system configuration files in the \fI/etc\fP directory that
you'll probably need to edit to allow dialup access to your FreeBSD system.  The
first, \fI/etc/gettytab\fP, contains configuration information for the
\fI/usr/libexec/getty\fP daemon.  Second, \fI/etc/ttys\fP holds information that
tells \fI/sbin/init\fP what \fItty\fP devices should have \fIgetty\fP processes
running on them.  Lastly, you can place port initialization commands in the
\fI/etc/rc.serial\fP script.
.P
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.
.P
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 \fIgetty\fP doesn't understand any particular modem's connection
speed reporting, \fIgetty\fP gives a \fClogin:\fP message at an initial speed
and watches the characters that come back in response.  If the user sees junk,
it's assumed that they know they should press the \fC<Enter>\fP key until they
see a recognizable prompt.  If the data rates don't match, \fIgetty\fP sees
anything the user types as ``junk'', tries going to the next speed and gives the
\fClogin:\fP prompt again.  This procedure can continue ad nauseum, but normally
only takes a keystroke or two before the user sees a good prompt.  Obviously,
this login sequence doesn't look as clean as the former ``locked-speed'' method,
but a user on a low-speed connection should receive better interactive response
from full-screen programs.
.H2 "/etc/gettytab"
\fI/etc/gettytab\fP is a \fItermcap\fP-style file of configuration
information for \fIgetty\fP.  Please see the \fIgettytab\fP manual page
for complete information on the format of the file and the list of capabilities.
.H2 "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 \fI/etc/gettytab\fP.
.H2 "Matching-Speed Config"
You'll need to setup an entry in \fI/etc/gettytab\fP to give \fIgetty\fP
information about the speeds you wish to use for your modem.  If you have a 2400
bps modem, you can probably use the existing \fCD2400\fP entry.  This entry
already exists in the \fIgettytab\fP file, so you don't need to add it unless it
is missing under your version of FreeBSD:
.Ds
#
# 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:
.De
If you have a higher speed modem, you'll probably need to add an entry in
\fI/etc/gettytab\fP; here's an entry you could use for a 14.4 Kbps modem with a
top interface speed of 19.2 Kpbs:
.Ds
#
# 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:
.De
This will result in 8-bit, no parity connections.
.P
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
\fCnx=\fP (\fBnext table\fP) capability.  Each of the lines uses a \fCtc=\fP
(\fBtable continuation\fP) entry to pick up the rest of the ``standard''
settings for a particular data rate.
.P
If you have a 28.8 Kbps modem and/or you want to take advantage of compression
on a 14.4 Kbps modem, you need to use a higher communications rate than 19.2
Kbps.  Here's an example of a \fIgettytab\fP entry starting a 57.6 Kpbs:
.Ds
#
# 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:
.De
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.
.H2 "/etc/ttys"
\fI/etc/ttys\fP is the list of \fIttys\fP for \fIinit\fP to monitor.
\fI/etc/ttys\fP also provides security information to \fIlogin\fP (user
\fCroot\fP may only login on ttys marked \fCsecure\fP).  See the manual page for
\fIttys\fP for more information.
.P
You'll need to either modify existing lines in \fI/etc/ttys\fP or add new lines
to make \fIinit\fP run \fIgetty\fP processes automatically on your new dialup
ports.  The general format of the line will be the same, whether you are using a
locked-speed or matching-speed configuration:
.Ds
ttyd0   "/usr/libexec/getty xxx"   dialup on
.De
The first item in the above line is the device special file for this
entry - \fIttyd0\fP means \fI/dev/ttyd0\fP is the file that this
\fIgetty\fP will be watching.  The second item, \fC/usr/libexec/getty
\fIxxx\fP (\fIxxx\fP will be replaced by the initial \fIgettytab\fP
capability) is the process \fIinit\fP will run on the device.  The
third item, \fCdialup\fP, is the default terminal type.  The fourth
parameter, \fCon\fP, indicates to \fIinit\fP that the line is
operational.  There can be a fifth parameter, \fCsecure\fP, but it
should only be used for terminals which are physically secure (such as
the system console).
.P
The default terminal type (\fCdialup\fP in the example above) may
depend on local preferences.  \fCdialup\fP is the traditional default
terminal type on dialup lines so that users may customize their login
scripts to notice when the terminal is \fCdialup\fP and automatically
adjust their terminal type.  However, the author finds it easier at
his site to specify \fCvt102\fP as the default terminal type, since the
users just use VT102 emulation on their remote systems.
.P
After you have made changes to \fI/etc/ttys\fP, you may send the \fIinit\fP
process a \fIHUP\fP signal to re-read the file.  You can use the command
.Ds
kill -1 1
.De
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 \fIinit\fP.
.H2 "Locked-Speed Config"
For a locked-speed configuration, your \fIttys\fP entry needs to have a
fixed-speed entry provided to \fIgetty\fP.  For a modem whose port speed is
locked at 19.2 Kbps, the \fIttys\fP entry might look like this:
.Ds
ttyd0   "/usr/libexec/getty std.19200"   dialup on
.De
If your modem is locked at a different data rate, substitute the appropriate
name for the \fCstd.\fIspeed\fP\fP entry for \fCstd.19200\fP from
\fI/etc/gettytab\fP for your modem's data rate.
.H2 "Matching-Speed Config"
In a matching-speed configuration, your \fIttys\fP entry needs to reference the
appropriate beginning ``auto-baud'' (sic) entry in \fI/etc/gettytab\fP.  For
example, if you added the above suggested entry for a matching-speed modem that
starts at 19.2 Kbps (the \fIgettytab\fP entry containing the \fCV19200\fP
starting point), your \fIttys\fP entry might look like this:
.Ds
ttyd0   "/usr/libexec/getty V19200"   dialup on
.De
.H2 "/etc/rc.serial or /etc/rc.local"
High-speed modems, like V.32, V.32bis, and V.34 modems, need to use hardware
(\fIRTS/CTS\fP) flow control.  You can add \fIstty\fP commands to
\fI/etc/rc.serial\fP to set the hardware flow control flag in the FreeBSD kernel
for the modem ports.
.P
Here's a sample \fI/etc/rc.serial\fP:
.Ds
#!/bin/sh
#
# Serial port initial configuration

stty -f /dev/ttyid1 crtscts
stty -f /dev/cuai01 crtscts
.De
which sets the \fItermios\fP flag \fCcrtscts\fP on serial port #1's
(\fICOM2:\fP) dialin and dialout initialization devices.
.H2 "Modem Settings"
.P
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 \fItip\fP
under FreeBSD) to set the parameters.  Connect to the modem using the same
communications speed as the initial speed \fIgetty\fP will use and configure the
modem's non-volatile RAM to match these requirements:
.Ls B
.LI
\fICD\fP asserted when connected
.LI
\fIDTR\fP asserted for operation; dropping DTR hangs up line and resets the
modem.
.LI
\fICTS\fP transmitted data flow control
.LI
Disable \fIXON/XOFF\fP flow control
.LI
\fIRTS\fP received data flow control
.LI
Quiet mode (no result codes)
.LI
No command echo
.LE
Please read the documentation for your modem to find out what commands
and/or DIP switch settings you need to give it.
.P
For example, to set the above parameters on a USRobotics Sportster 14,400
external modem, one could give these commands to the modem:
.Ds
ATZ
AT&C1&D2&H1&I0&R2&W
.De
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.
.P
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:
.Ls B
.LI
Switch 1: UP - DTR Normal
.LI
Switch 2: Don't care (Verbal Result Codes/Numeric Result Codes)
.LI
Switch 3: UP - Suppress Result Codes
.LI
Switch 4: DOWN - No echo, offline commands
.LI
Switch 5: UP - Auto Answer
.LI
Switch 6: UP - Carrier Detect Normal
.LI
Switch 7: UP - Load NVRAM Defaults
.LI
Switch 8: Don't care (Smart Mode/Dumb Mode)
.P
Result codes should be disabled/suppressed for dialup modems to avoid problems
that can occur if \fIgetty\fP mistakenly gives a \fClogin:\fP prompt to a modem
that is in command mode and the modem echoes the command or returns a result
code.  I've heard this sequence can result in a extended, silly conversation
between \fIgetty\fP and the modem.
.H2 "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:
.Ds
ATZ
AT&B1&W
.De
.H2 "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:
.Ds
ATZ
AT&B2&W
.De
.H2 "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 \fCATI5\fP displays the settings that are stored in
the non-volatile RAM.  To see the true operating parameters of the modem (as
influenced by the USR's DIP switch settings), use the commands \fCATZ\fP and
then \fCATI4\fP.
.P
If you have a different brand of modem, check your modem's manual to see how to
double-check your modem's configuration parameters.
.H2 "Troubleshooting"
Here are a few steps you can follow to check out the dialup modem on your
system.
.H2 "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 \fIDTR\fP
indicator lights when the \fClogin:\fP prompt appears on the system's console -
if it lights up, that should mean that FreeBSD has started a \fIgetty\fP process
on the appropriate communications port and is waiting for the modem to accept a
call.
.P
If the \fIDTR\fP indicator doesn't light, login to the FreeBSD system through
the console and issue a \f(CWps ax\fP to see if FreeBSD is trying to run a
\fIgetty\fP process on the correct port.  You should see a lines like this among
the processes displayed:
.Ds
  114 ??  I      0:00.10 /usr/libexec/getty V19200 ttyd0
  115 ??  I      0:00.10 /usr/libexec/getty V19200 ttyd1
.De
If you see something different, like this:
.Ds
  114 d0  I      0:00.10 /usr/libexec/getty V19200 ttyd0
      ^^
.De
and the modem hasn't accepted a call yet, this means that \fIgetty\fP has
completed its open on the communications port.  This could indicate a problem
with the cabling or a mis-configured modem, because \fIgetty\fP should not be
able to open the communications port until \fICD\fP (carrier detect) has been
asserted by the modem.
.P
If you don't see any \fIgetty\fP processes waiting to open the desired
\fIttyd?\fP port, double-check your entries in \fI/etc/ttys\fP to see if there
are any mistakes there.  Also, check the log file \fI/var/log/messages\fP to see
if there are any log messages from \fIinit\fP or \fIgetty\fP regarding any
problems.  If there are any messages, triple-check the configuration files
\fI/etc/ttys\fP and \fI/etc/gettytab\fP, as well as the appropriate device
special files \fI/dev/ttyd?\fP, for any mistakes, missing entries, or missing
device special files.
.H2 "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 \fC<Enter>\fP about once per
second.  If you still don't see a \fClogin:\fP prompt after a while,
try sending a \fCBREAK\fP.  If you are using a high-speed modem to
do the dialing, try dialing again after locking the dialing modem's
interface speed (via \fCAT&B1\fP on a USR Sportster, for
example).
.P
If you still can't get a \fClogin:\fP prompt, check \fI/etc/gettytab\fP again
and double-check that
.Ls B
.LI
The initial capability name specified in \fI/etc/ttys\fP for the line matches a
name of a capability in \fI/etc/gettytab\fP
.LI
Each \fCnx=\fP entry matches another \fIgettytab\fP capability name
.LI
Each \fCtc=\fP entry matches another \fIgettytab\fP capability name
.P
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 \fIDTR\fP is asserted.  If the
modem seems to be configured correctly, verify that the \fIDTR\fP line is
asserted by checking the modem's indicator lights (if it has any).
.P
If you've gone over everything several times and it still doesn't work, take a
break and come back to it later.  If it still doesn't work, perhaps you can send
an electronic mail message to \fCFreeBSD-Questions@freebsd.org\fP describing
your modem and your problem, and the good folks on the list will try to help.
.H2 "Acknowledgements"
.H2 "PPP and SLIP"
If your connection to the internet is through a modem, or you wish to provide
other people with dialup connections to the internet using FreeBSD, you have the
option of using PPP or SLIP.  Furthermore, two varieties of PPP are provided:
\fIuser\fP (sometimes referred to as iijppp) and \fIkernel\fP.  The procedures
for configuring both types of PPP, and for setting up SLIP are described in this
chapter.
.H2 "Setting up user PPP"
User PPP is an addition to the exisiting kernel implementation of PPP.  So, what
is different about this new PPP that warrants its addition?  To quote from the
manual page:
.P
This is a user process PPP software package. Normally, PPP is implemented as a
part of the kernel (e.g. as managed by pppd) and it's thus somewhat hard to
debug and/or modify its behavior. However, in this implementation PPP is done as
a user process with the help of the tunnel device driver (tun).
.P
In essence, this means that rather than running a PPP daemon, the ppp program
can be run as and when desired. No PPP interface needs to be compiled into the
kernel, as the program can use the generic tunnel device to to get data into and
out of the kernel.
.P
From here on out, user ppp will be referred to as simply as ppp unless a
distinction need to be made be it and any other PPP client/server software.
Unless otherwise stated, all commands in this section should be executed as
root.
.H2 "Before you start"
This document assumes you're in roughly this position:
.P
You have an account with an Internet Service Provider (ISP) which lets you use
PPP. Further, you have a modem (or other device) connected and configured
correctly which allows you to connect to your ISP.
.P
You are going to need the following information to hand:
.Ls B
.LI
IP address of your ISP's gateway
.LI
Your ISP's netmask setting
.LI
IP adresses of one or more nameservers
.LI
If your ISP allocates you a static IP address and/or hostname then you will need
that as well. If not, you will need to know from what range of IP addresses your
allocated IP address will fall in.
.P
If you do not have any of this information then contact your ISP and make
sure they provide it to you.
.P
As well as this, you may need the files required to recompile your kernel. Check
``Kernel Configuration'' for more information on how to acquire these.
.P
In addition, I've assumed that because your connection to the Internet is not
full time you are not running a name server (\fInamed\fP).
.H2 "Building a ppp ready kernel"
As the description states, ``ppp'' uses the kernel ``tun'' device. It is
necessary to make sure that your kernel has support for this device compiled
in.
.P
To check this, go to your kernel compile directory (probably /sys/i386/conf)
and examine your kernel configuration file. It needs to have the line
.Ds
pseudo-device	  tun		1
.De
in it somewhere. The stock GENERIC kernel has this as standard, so if you
have not installed a custom kernel you don't have to change anything.
If your kernel configuration file does not have this line in it then you
should add the line, re-compile and then re-install the kernel. Boot from
this new kernel.
.H2 "Check the tun device"
My experiences with ppp have only been with one ``tun'' device (tun0). If
you have used more (i.e., a number other than `1' in the pseudo-device line
in the kernel configuration file) then alter all references to ``tun0''
below to reflect whichever device number you are using.
.P
The easiest way to make sure that the tun0 device is configured correctly is
to re-make it. To this end, execute the following commands,
.Ds
# cd /dev
# ./MAKEDEV tun0
.De
.H2 "PPP Configuration"
The meat of the problem.
.P
Confusingly, it appears that both user ppp and pppd (the kernel level
implementation of PPP) both assume configuration files kept in
/etc/ppp. However, the sample configuration files provided are good for
user ppp, so keep them around for reference. The easiest way to do this is,
.Ds
# cd /etc
# mv ppp ppp.orig
# mkdir ppp
.De
Configuring ppp requires that you edit somewhere between one and three
files, depending on your requirements. What you put in them depends to some
extent on whether your ISP allocates IP addresses statically (i.e., you get
given one IP address, and always use that one) or dynamically (i.e., your IP
address can be different during different PPP sessions).
.P
However, there are a few things that you should do first, regardless of
whether you are using static or dynamic IP addresses.
.H2 "Configure the resolver"
The resolver is the part of the networking system that turns IP addresses
into hostnames. It can be configured to look for maps that describe IP to
hostname mappings in one of two places.
.P
The first is a file called /etc/hosts (``hosts'' in section 5 of the
manual). The second is the Internet Domain Name Service, a distributed
data base, the discussion of which is beyond the realm of this document.
.P
The resolver is a set of system calls that do the mappings,
and you have to tell them where to get their information
from. You do this by editing the file /etc/host.conf. Do
\fBnot\fP call this file /etc/hosts.conf (note the extra
``s'') as the results can be confusing.
.P
This file should contain the following two lines,
.Ds
hosts
bind
.De
which instruct the resolver to look in the file /etc/hosts first, and
then to consult the DNS if the name was not found in the /etc/hosts file.
.P
It's probably a good idea to make sure you are not running the ``named''
service. Check your /etc/sysconfig file for the line that refers to
\f(CWnamedflags\fP, and make sure the line reads
.Ds
namedflags="NO"
.De
.H2 "Create the /etc/hosts file"
This file should contain the IP addresses and names of machines on your
network. At a bare minimum it should contain entries for the machine
which will be running ppp. Assuming that you're machine is called
foo.bar.com with the IP address 10.0.0.1, /etc/hosts should contain
.Ds
127.0.0.0    localhost
10.0.0.1     foo.bar.com	       foo
.De
The first line defines the alias ``localhost'' as a synonym for the
current machine. Regardless of your own IP address, the IP address for
this line should always be 127.0.0.1. The second line maps the name
``foo.bar.com'' (and the shorthand ``foo'') to the IP address 10.0.0.1.
.P
If your provider allocates you a static IP address then use this in place
of 10.0.0.1.
.H2 "Create the /etc/resolv.conf file"
/etc/resolv.conf contains some extra information required when you are
not running a nameserver. It points the resolver routines at real
nameservers, and specifies some other information.
.P
At the very least, /etc/resolv.conf should contain one line with a
nameserver which can be queried. You should enter this as an IP
address. My /etc/resolv.conf contains
.Ds
nameserver 158.152.1.193
nameserver 158.152.1.65
.De
Which are Demon Internet's two nameservers. Add as many ``nameserver''
lines as your ISP provides nameservers.
.H2 "PPP and static IP addresses"
Probably the easiest to configure for. You will need to create three files
in the /etc/ppp directory.
.P
The first of these is ppp.conf. It should look similar to the example
below. Note that lines that end in a ``:'' start in column 1, all other
lines should be indented as shown.
.P
/etc/ppp/ppp.conf
.Ds
1     default:
2       set device /dev/cuaa0
3       set speed 9600
4       disable lqr
5       deny lqr
6       set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \"\" ATE1Q0 OK-AT-OK
\\dATDT\\T TIMEOUT 40 CONNECT"
7      provider:
8        set phone 01234567890
9	 set login "TIMEOUT 10 gin:-BREAK-gin: foo word: bar col: ppp"
10       set timeout 120
11       set ifaddr x.x.x.x y.y.y.y
.De
Don't include the line numbers, they're just for this discussion.
.LI "Line 1:"
Identifies the default entry. Commands in this entry are
executed automatically when ppp is run.
.LI "Line 2:"
Identifies the device that has the modem hanging from it.
COM1: is /dev/cuaa0 and COM2: is /dev/cuaa1
.LI "Line 3:"
Sets the speed you want to connect at.
.LI "* Lines 4 and 5:"
Don't know exactly what effect these lines have
.LI "Line 6:"
Dial string commands. user ppp uses the chat language. Check
the manual page for information on the features of this
language.
.LI "Line 7:"
Identifies an entry for a provider called ``provider''.
.LI "Line 8:"
Sets the phone number for this provider. Don't include any
spaces in the phone number.
.LI "Line 9:"
Set's the login string sequence. In this example, the string is
for a service who's login session looks like
.Ds
J. Random Provider
login: foo
password: bar
protocol: ppp
.De
You will need to alter this script to suit your own needs. It is
written in the chat language.
.LI "Line 10:"
Sets the default timeout (in seconds) for the connection. So
the connectioned will be closed automatically after 120 seconds
of inactivity.
.LI "Line 11:"
Sets the interface addresses. The string x.x.x.x should be
replaced by the IP address that your provider allocates you. The
string y.y.y.y should be replaced by the IP address that your
ISP indicated for their gateway.
.P
Now you have to edit the file /etc/ppp/ppp.linkup:
.Ds
x.x.x.x:
  add 0 0 HISADDR
.De
Replace x.x.x.x with your IP address as before. This file is used to
automatically add a default route from your ISP (who's address is
automatically inserted with the HISADDR macro) to you.
.P
Finally, you can create the file /etc/ppp/ppp.secret, which sets some
passwords to prevent people messing around with ppp on your system. You
may or may not want to do this, depending on how many people have access
to your ppp system.
.H2 "PPP and Dynamic IP configuration"
If you service provider does not assign static IP numbers,
\fIppp\fP can be configured to negotiate the local address.  This is
done by specifying 0 as the local IP address:
.Ds
set ifaddr 0 0
.De
See the \fIppp\fP manual page for more detailed information.
.H2 "Final system configuration"
You now have PPP configured, but there's a few more things to do before
it's ready to work. They all involve editing the /etc/sysconfig file.
.P
Working from the top down in this file, make sure the ``hostname='' line
is set, e.g.,
.Ds
hostname=foo.bar.com
.De
Look for the network_interfaces variable, and make sure the tun0 device is
added to the list. My line looks like
.Ds
network_interfaces="lo0 tun0 ep0"
.De
but I have an ethernet card (ep0) to configure as well.
.P
Now add an ifconfig line for the tun0 device. It should look something
like
.Ds
ifconfig_tun0="inet foo.bar.com y.y.y.y netmask 0xffffffff"
.De
as before, change ``foo.bar.com'' to be your hostname, y.y.y.y is the IP
address of your providers gateway, and 0xffffffff is the netmask they
provided you with (in hexadecimal). Two common values for the netmask are
.Ds
255.255.255.255 = 0xffffffff
255.255.255.0   = 0xffffff00
.De
Set the routed flags to ``-s'' with the line
.Ds
routedflags=-s
.De
It's probably worth your while ensuring that the ``sendmail_flags'' line
does not include the ``-q'' option, otherwise sendmail will attempt to do
a network lookup every now and then, possibly causing your machine to dial
out. My sendmail line looks like
.Ds
sendmail_flags="-bd"
.De
The upshot of this is that I must force sendmail to re-examine the
mailqueue whenever I have the PPP link up, by typing
.Ds
# /usr/sbin/sendmail -q
.De
That should be about all you need to do to get PPP working with a static
IP address. All that's left is to reboot the machine. During startup the
tun0 device should be detected, and two lines like the following should be
printed,
.Ds
tun0: flags=51<UP,POINTOPOINT,RUNNING> mtu 1500
inet x.x.x.x --> y.y.y.y netmask 0xffffffff 
.De
At this point, it should all be working. You can now either type
.Ds
# ppp
.De
and then ``dial provider'' to start the PPP session, or, if you want ppp
to establish sessions automatically when there is outbound traffic, type
.Ds
# ppp -auto provider
.De
This line could be added to your /etc/rc.local file.
.H2 "Setting up kernel PPP"
Before you start setting up PPP on your machine make
sure that pppd is located in /usr/sbin and directory /etc/ppp
exists.
.P
pppd can work in two modes:
.Ls N
.LI
as a "client" , i.e. you want to connect your machine to outside
world via PPP serial connection or modem line.
.LI
as a "server" , i.e. your machine is located on the network and
used to connect other computers using PPP.
.LE
In both cases you will need to set up an options file (\fI/etc/ppp/options\fP or
\fI~/.ppprc\fP if you have more then one user on your machine that uses PPP).
.P
You also will need some modem/serial software (preferably kermit) so you can
dial and establish connection with remote host.
.H2 "Working as a PPP client"
I used the following /etc/ppp/options to connect to CISCO terminal server PPP
line.
.DS L
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
.De
To connect:
.Ls B
.LI
Dial to the remote host using kermit (or other modem program) enter your user
name and password (or whatever is needed to enable PPP on the remote host)
.LI
Exit kermit. (without hanging up the line)
.LI
enter: 
.Ds
/usr/src/usr.sbin/pppd.new/pppd /dev/tty01 19200
.De
(put the appropriate speed and device name)
.LE
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
.P
Following /etc/ppp/pppup script will make all 3 stages automatically:
.Ds
#!/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
.De
/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)
.P
Use the following /etc/ppp/pppdown script to disconnect the PPP line:
.Ds
#!/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
.De
Check if PPP is still running (/usr/etc/ppp/ppptest):
.Ds
#!/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
.De
Hangs up modem line (/etc/ppp/kermit.hup):
.Ds
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
.De
.H2 "Working as a PPP server"
/etc/ppp/options:
.Ds
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
.De
Following /etc/ppp/pppserv script will enable ppp server on your machine
.Ds
#!/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
.De
Use this /etc/ppp/pppservdown script to stop ppp server:
.Ds
#!/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
.De
Following kermit script will enable/disable autoanswer mode 
on your modem (/etc/ppp/kermit.ans):
.Ds
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
.De
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 responses from your modem
and remote host.
.Ds
;
; 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:
.De
.H2 "Setting up a SLIP client"
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.
.P
First, determine which serial port your modem is connected to.  I have a
symbolic link from \fI/dev/modem\fR to \fIcuaa1\fP, and only use the modem name
in my configuration files.  It can become quite cumbersome when you need to fix
a bunch of files in \fI/etc\fP and \fC.kermrc\fP's all over the system!  (Note
that \fI/dev/cuaa0\fP is COM1, \fCcuaa1\fP is COM2, etc.)
.P
Make sure you have
.Ds
pseudo-device   sl      1
.De
in your kernel's config file.  It is included in the \f(CWGENERIC\fP kernel, so
this won't be a problem unless you deleted it.
.H2 "Things you have to do only once"
.Ls B
.LI
Add your home machine, the gateway and nameservers to your
/etc/hosts file.  Mine looks like this:
.Ds
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
.De
Make sure you have \f(CWhosts\fP before \f(CWbind\fP in your
\fI/etc/host.conf\fP.  Otherwise funny things may happen.
.LI
Edit the file /etc/sysconfig.
.Ls B
.LI
Set your hostname by editing the line that says:
.Ds
hostname=myname.my.domain
.De
You should give it your full Internet hostname.
.LI
Add sl0 to the list of network interfaces by changing the line
that says:
.Ds
network_interfaces="lo0"
.De
to:
.Ds
network_interfaces="lo0 sl0"
.De
.LI
Set the startup flags of sl0 by adding a line:
.Ds
ifconfig_sl0="inet ${hostname} slip-gateway netmask 0xffffff00 up"            
.De
.LI
Designate the default router by changing the line:
.Ds
defaultrouter=NO
.De
to:
.Ds
defaultrouter=slip-gateway
.De
.LI
Make a file /etc/resolv.conf which contains:
.Ds
domain HIP.Berkeley.EDU
nameserver 128.32.136.9
nameserver 128.32.136.12
.De
As you can see, these set up the nameserver hosts.  Of course, the actual domain
names and addresses depend on your environment.
.LI
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!
.LI
Reboot your machine and make sure it comes up with the correct hostname.
.LE
.H2 "Making a SLIP connection"
.Ls B
.LI
Dial up, type \f(CWslip\fP 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:
.Ds
# kermit setup
set modem hayes
set line /dev/modem
set speed 115200
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
.De
(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.
.Aside
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.
.End-aside
.LI
Leave the kermit there (you can suspend it by "z") and as root, type
.Ds
slattach -h -c -s 115200 /dev/modem
.De
If you are able to "ping" hosts on the other side of the router, you are
connected! If it doesn't work, you might want to try "-a" instead of "-c" as an
argument to slattach.
.LE
.H2 "How to shutdown the connection"
Type \f(CWkill -INT `cat /var/run/slattach.modem.pid`\fP" (as root) to kill
slattach.  Then go back to kermit ("fg" if you suspended it) and exit from it
("q").
.P
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.)
.P
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.
.H2 "Troubleshooting"
If it doesn't work, feel free to ask me.  The things that people tripped over so
far:
.Ls B
.LI
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)
.LI
Using "s10" instead of "sl0" (might be hard to see the difference on some fonts.
.LI
Try "ifconfig sl0" to see your interface status.  I get:
.Ds
silvia# ifconfig sl0
sl0: flags=10<POINTOPOINT>
        inet 136.152.64.181 --> 136.152.64.1 netmask ffffff00
.De
.LI
Also, "netstat -r" will give the routing table, in case you get the
"no route to host" messages from ping.  Mine looks like:
.Ds
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)
.De
(this is after transferring a bunch of files, your numbers should be
smaller).
.LE
.H2 "Setting up a SLIP server"
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.  The author has written
this document based on his experience; however, as your system and needs may be
different, this document may not answer all of your questions, and the author
cannot be responsible if you damage your system or lose data due to attempting
to follow the suggestions here.
.P
This guide was originally written for SLIP Server services on a FreeBSD 1.x
system.  It has been modified to reflect changes in the pathnames and the
removal of the SLIP interface compression flags in FreeBSD 2.x, which appear to
be the only major changes between FreeBSD versions.  If you do run encounter
mistakes in this document, please email the author with enough information to
help correct the problem.
.P
For FreeBSD 1.x users, all of the files referenced in the directory
\fI/etc/sliphome\fP are actually in the \fI/etc\fP directory.
.H2 "Prerequisites"
This document is very technical in nature, so background knowledge is required.
It is assumed 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 \fITCP/IP Network
Administration\fP published by O'Reilly & Associates, Inc. (ISBN Number
0-937175-82-X), or Douglas Comer's books on the TCP/IP protocol.
.P
It's further assumed that you have already setup your modem(s) and configured
the appropriate system files to allow logins through your modems.  If you
haven't prepared your system for this yet, please see the tutorial for
configuring dialup services; if you have a World-Wide Web browser available,
browse the list of tutorials at \fChttp://www.freebsd.org/How\fP; otherwise,
check the place where you found this document for a document named
\fCdialup.txt\fP or something similar.  You may also want to check the manual
pages for \fCsio\fP for information on the serial port device driver and
\fCttys\fP, \fCgettytab\fP, \fCgetty\fP, & \fCinit\fP for information relevant
to configuring the system to accept logins on modems, and perhaps \fCstty\fP for
information on setting serial port parameters [such as \fCclocal\fP for
directly-connected serial interfaces].
.H2 "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 \fI/usr/sbin/sliplogin\fP as the special user's shell.
The \fCsliplogin\fP program browses the file \fI/etc/sliphome/slip.hosts\fP 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
\fI/etc/sliphome/slip.login\fP to configure the SLIP interface.
.H2 "An Example of a SLIP Server Login"
For example, if a SLIP user ID were \fCShelmerg\fP, \fCShelmerg\fP's entry in
\fI/etc/master.passwd\fP would look something like this (except it would be all
on one line):
.Ds
Shelmerg:password:1964:89::0:0:Guy Helmer - SLIP:
        /usr/users/Shelmerg:/usr/sbin/sliplogin
.De
and, when \fCShelmerg\fP logs in, \fCsliplogin\fP will search
\fI/etc/sliphome/slip.hosts\fP for a line that had a matching user ID; for
example, there may be a line in \fI/etc/sliphome/slip.hosts\fP that reads:
.Ds
Shelmerg        dc-slip sl-helmer       0xfffffc00      autocomp
.De
\fCsliplogin\fP will find that matching line, hook the serial line into the next
available SLIP interface, and then execute \fI/etc/sliphome/slip.login\fP like
this:
.Ds
/etc/sliphome/slip.login 0 19200 Shelmerg dc-slip sl-helmer 0xfffffc00 autocomp
.De
If all goes well, \fI/etc/sliphome/slip.login\fP will issue an \fCifconfig\fP
for the SLIP interface to which \fCsliplogin\fP attached itself (slip interface
0, in the above example, which was the first parameter in the list given to
\fCslip.login\fP) to set the local IP address (\fCdc-slip\fP), remote IP address
(\fCsl-helmer\fP), network mask for the SLIP interface (\fC0xfffffc00\fP), and
any additional flags (\fCautocomp\fP).  If something goes wrong, \fCsliplogin\fP
usually logs good informational messages via the daemon syslog facility, which
usually goes into \fI/var/log/messages\fP (see the manual pages for
\fCsyslogd\fP and \fCsyslog.conf\fP, and perhaps check \fI/etc/syslog.conf\fP to
see to which files \fCsyslogd\fP is logging).
.P
OK, enough of the examples -- let's dive into setting up the system.
.H2 "Kernel Configuration"
FreeBSD's default kernels usually come with two SLIP interfaces defined
(\fCsl0\fP and \fCsl1\fP); you can use \fCnetstat -i\fP to see whether these
interfaces are defined in your kernel.
.P
Sample output from \fCnetstat -i\fP:
.Ds
Name  Mtu   Network     Address            Ipkts Ierrs    Opkts Oerrs  Coll
ed0   1500  <Link>0.0.c0.2c.5f.4a         291311     0   174209     0   133
ed0   1500  138.247.224 ivory             291311     0   174209     0   133
lo0   65535 <Link>                            79     0       79     0     0
lo0   65535 loop        localhost             79     0       79     0     0
sl0*  296   <Link>                             0     0        0     0     0
sl1*  296   <Link>                             0     0        0     0     0
.De
The \fCsl0\fP and \fCsl1\fP interfaces shown in \fCnetstat -i\fP's output
indicate that there are two SLIP interfaces built into the kernel.  (The
asterisks after the \fCsl0\fP and \fCsl1\fP indicate that the interfaces are
``down''.)
.P
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 \fCoptions
GATEWAY \fP 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''.)
.P
Please see the BSD System Manager's Manual chapter on ``Building Berkeley
Kernels with Config'' [the source for which is in \fI/usr/src/share/doc/smm\fP]
and ``FreeBSD Configuration Options'' [in \fI/sys/doc/options.doc\fP] 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 to be
able to configure and build kernels.
.P
You'll notice that near the end of the default kernel configuration file
(\fI/sys/i386/conf/GENERICAH\fP) is a line that reads:
.Ds
pseudo-device sl 2
.De
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.
.P
See the document ``Building Berkeley Kernels with Config'' and the manual page
for \fCconfig\fP to see how to configure and build kernels.
.H2 "Sliplogin Configuration"
As mentioned earlier, there are three files in the \fI/etc/sliphome\fP directory
that are part of the configuration for \fI/usr/sbin/sliplogin\fP (see
\fCsliplogin\fP for the actual manual page for \fCsliplogin\fP):
\fCslip.hosts\fP, which defines the SLIP users & their associated IP addresses;
\fCslip.login\fP, which usually just configures the SLIP interface; and
(optionally) \fCslip.logout\fP, which undoes \fCslip.login\fP's effects when the
serial connection is terminated.
.H2 "slip.hosts Configuration"
\fI/etc/sliphome/slip.hosts\fP contains lines which have at least four items,
separated by whitespace:
.Ls B
.LI
SLIP user's login ID
.LI
Local address (local to the SLIP server) of the SLIP link
.LI
Remote address of the SLIP link
.LI
Network mask
.LE
The local and remote addresses may be host names (resolved to IP addresses by
\fI/etc/hosts\fP or by the domain name service, depending on your specifications
in \fI/etc/host.conf\fP), and I believe the network mask may be a name that can
be resolved by a lookup into \fI/etc/networks\fP.  On a sample system,
\fI/etc/sliphome/slip.hosts\fP looks like this:
.Ds
----- begin /etc/sliphome/slip.hosts -----
#
# login local-addr      remote-addr     mask            opt1    opt2 
#                                               (normal,compress,noicmp)
#
Shelmerg  dc-slip       sl-helmerg      0xfffffc00      autocomp
----- end /etc/sliphome/slip.hosts ------
.De
At the end of the line is one or more of the options.
.Ls B
.LI
\fCnormal\fP - no header compression
.LI
\fCcompress\fP - compress headers
.LI
\fCautocomp\fP - compress headers if the remote end allows it
.LI
\fCnoicmp\fP - disable ICMP packets (so any ``ping'' packets will be
dropped instead of using up your bandwidth)
.P
It appears that \fCsliplogin\fP under FreeBSD 2.x ignores the options that
FreeBSD 1.x recognized, so the options \fCnormal\fP, \fCcompress\fP,
\fCautocomp\fP, and \fCnoicmp\fP will have no effect under FreeBSD 2.x unless
your \fCslip.login\fP script includes code to make use of the flags.
.P
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 used 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.
.P
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 \fCgated\fP 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.
.P
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 \fI/etc/sliphome/slip.login\fP and
\fI/etc/sliphome/slip.logout\fP scripts to use \fCarp\fP to manage the proxy-ARP
entries in the SLIP server's ARP table.
.H2 "slip.login Configuration"
The typical \fI/etc/sliphome/slip.login\fP file looks like this:
.Ds
----- begin /etc/sliphome/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/sliphome/slip.login -----
.De
This \fCslip.login\fP file merely ifconfig's the appropriate SLIP interface with
the local and remote addresses and network mask of the SLIP interface.
.P
If you have decided to use the ``proxy ARP'' method (instead of using a separate
subnet for your SLIP clients), your \fI/etc/sliphome/slip.login\fP file will
need to look something like this:
.Ds
----- begin /etc/sliphome/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/sliphome/slip.login for "proxy ARP" -----
.De
The additional line in this \fCslip.login\fP, \fCarp -s \*(dR5 00:11:22:33:44:55
pub\fP, 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.
.P
When using the example above, be sure to replace the Ethernet MAC address
(\fC00:11:22:33:44:55\fP) 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 \fCnetstat
-i\fP; the second line of the output should look something like:
.Ds
ed0   1500  <Link>0.2.c1.28.5f.4a         191923     0   129457     0   116
                  ^^^^^^^^^^^^^^^
.De
which indicates that this particular system's Ethernet MAC address is
\fC00:02:c1:28:5f:4a\fP -- the periods in the Ethernet MAC address given by
\fCnetstat -i\fP 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
\fCarp\fP desires; see the manual page on \fCarp\fP for complete
information on usage.
.P
Note that when you create \fI/etc/sliphome/slip.login\fP and
\fI/etc/sliphome/slip.logout\fP, the ``execute'' bit (ie, \fCchmod 755
/etc/sliphome/slip.login /etc/sliphome/slip.logout\fP) must be set, or
\fCsliplogin\fP will be unable to execute it.
.H2 "slip.logout Configuration"
\fI/etc/sliphome/slip.logout\fP isn't strictly needed (unless you are
implementing ``proxy ARP''), but if you decide to create it, this is an example
of a basic \fCslip.logout\fP script:
.Ds
----- begin /etc/sliphome/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/sliphome/slip.logout -----
.De
If you are using ``proxy ARP'', you'll want to have
\fI/etc/sliphome/slip.logout\fP remove the ARP entry for the SLIP
client:
.Ds
----- begin /etc/sliphome/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/sliphome/slip.logout for "proxy ARP" -----
.De
The \fCarp -d \*(dR5\fP removes the ARP entry that the ``proxy ARP''
\fCslip.login\fP added when the SLIP client logged in.
.P
It bears repeating: make sure \fI/etc/sliphome/slip.logout\fP has the execute
bit set for after you create it (ie, \fCchmod 755 /etc/sliphome/slip.logout\fP).
.H2 "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 \fCgated\fP on your FreeBSD SLIP server so that it will
tell your routers via appropriate routing protocols about your SLIP subnet.
.H2 "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.
.H2 "Running gated"
An alternative to the headaches of static routes is to install \fCgated\fP 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.
\fCgated\fP is available via anonymous ftp from \fCftp.gated.cornell.edu\fP in
the directory \fI/pub/gated\fP; I believe the current version as of this writing
is \fCgated-R3_5Alpha_8.tar.Z\fP, which includes support for FreeBSD
``out-of-the-box''.  Complete information and documentation on \fCgated\fP is
available on the Web starting at \fChttp://www.gated.cornell.edu/\fP.  Compile
and install it, and then write a \fI/etc/gated.conf\fP file to configure your
gated; here's a sample, similar to what the author used on a FreeBSD SLIP
server:
.Ds
----- 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 -----
.De
The above sample \fCgated.conf\fP file broadcasts routing information regarding
the SLIP subnet \fCxxx.xxx.yy\fP via RIP onto the Ethernet; if you are using a
different Ethernet driver than the \fCed\fP driver, you'll need to change the
references to the \fCed\fP interface appropriately.  This sample file also sets
up tracing to \fI/var/tmp/gated.output\fP for debugging \fCgated\fP's activity;
you can certainly turn off the tracing options if \fCgated\fP works OK for you.
You'll need to change the \fCxxx.xxx.yy\fP's into the network address of your
own SLIP subnet (be sure to change the net mask in the \fCproto direct\fP clause
as well).
.P
When you get \fCgated\fP built and installed and create a configuration file for
it, you'll need to run \fCgated\fP in place of \fCrouted\fP on your FreeBSD
system; change the \fCrouted/gated\fP startup parameters in \fI/etc/netstart\fP
as appropriate for your system.  Please see the manual page for \fCgated\fP for
information on \fCgated\fP's command-line parameters.
.H2 "Advanced networking"
.H2 "Gateways and routes"
For one machine to be able to find another, there must be a mechanism in place
to describe how to get from one to the other. This is called Routing.  A
``route'' is a defined pair of addresses: a \fBdestination\fP and a
\fBgateway\fP.  The pair indicates that if you are trying to get to this
\fIdestination\fP, send along through this \fIgateway\fP. There are three types
of destinations: individual hosts, subnets, and ``default''. The ``default
route'' is used if none of the other routes apply. We will talk a little bit
more about default routes later on.  There are also three types of gateways:
individual hosts, interfaces (also called ``links''), and ethernet hardware
addresses.
.H2 "An example"
To illustrate different aspects of routing, we will use the following example
which is the output of the command \fCnetstat -r\fP:
.Ds
Destination      Gateway            Flags     Refs     Use     Netif Expire

default          outside-gw         UGSc       37      418      ppp0
localhost        localhost          UH          0      181       lo0
test0            0:e0:b5:36:cf:4f   UHLW        5    63288       ed0     77
10.20.30.255     link#1             UHLW        1     2421 
foobar.com       link#1             UC          0        0 
host1            0:e0:a8:37:8:1e    UHLW        3     4601       lo0
host2            0:e0:a8:37:8:1e    UHLW        0        5       lo0 =>
host2.foobar.com link#1             UC          0        0
224              link#1	            UC          0        0
.De
The first two lines specify the default route (which we will cover in the next
section) and the \fClocalhost\fP route.
.P
The interface (\fCNetif\fP column) that it specifies to use for \fClocalhost\fP
is \fClo0\fP, also known as the loopback device. This says to keep all traffic
for this destination internal, rather than sending it out over the LAN, since it
will only end up back where it started anyway.
.P
The next thing that stands out are the ``\fC0:e0:...\fP'' addresses. These are
ethernet hardware addresses. FreeBSD will automatically identify any hosts
(\fCtest0\fP in the example) on the local ethernet and add a route for that
host, directly to it over the ethernet interface, \fCed0\fP. There is also a
timeout (\fCExpire\fP column) associated with this type of route, which is used
if we fail to hear from the host in a specific amount of time. In this case the
route will be automatically deleted. These hosts are identified using a
mechanism known as RIP (Routing Information Protocol), which figures out routes
to local hosts based upon a shortest path determination.
.P
FreeBSD will also add subnet routes for the local subnet (\fC10.20.30.255\fP is
the broadcast address for the subnet \fC10.20.30\fP, and \fCfoobar.com\fP is the
domain name associated with that subnet). The designation \fClink#1\fP refers to
the first ethernet card in the machine. You'll notice no additional interface is
specified for those.
.P
Both of these groups (local network hosts and local subnets) have their routes
automatically configured by a daemon called \fCrouted\fP. If this is not run,
then only routes which are statically defined (ie. entered explicitly) will
exist.
.P
The \fChost1\fP line refers to our host, which it knows by ethernet address.
Since we are the sending host, FreeBSD knows to use the loopback interface
(\fClo0\fP) rather than sending it out over the ethernet interface.
.P
The two \fChost2\fP lines are an example of what happens when we use an ifconfig
alias (see the section of ethernet for reasons why we would do this).  The
\fC=>\fP symbol after the \fClo0\fP interface says that not only are we using
the loopback (since this is address also refers to the local host), but
specifically it is an alias. Such routes only show up on the host that supports
the alias; all other hosts on the local network will simply have a \fClink#1\fP
line for such.
.P
The final line (destination subnet \fC224\fP) deals with MultiCasting, which
will be covered in a another section.
.P
The other column that we should talk about are the \fCFlags\fP.  Each route has
different attributes that are described in the column.  Below is a short table
of some of these flags and their meanings:
.P
.RS
.LI "U"
\fBUp:\fP The route is active.
.LI "H"
\fBHost:\fP The route destination is a single host.
.LI "G"
\fBGateway:\fP Send anything for this destination on to this remote system,
which will figure out from there where to send it.
.LI "S"
\fBStatic:\fP This route was configured manually, not automatically generated by
the system.
.LI "C"
\fBClone:\fP Generates a new route based upon this route for machines we connect
to. This type of route is normally used for local networks.
.LI "W"
\fBWasCloned\fP Indicated a route that was auto-configured based upon a local
area network (Clone) route.
.LI "L"
\fBLink:\fP Route involves references to ethernet hardware.
.H2 "Default routes"
When the local system needs to make a connection to remote host, it checks the
routing table to determine if a known path exists. If the remote host falls into
a subnet that we know how to reach (Cloned routes), then the system checks to
see if it can connect along that interface.
.P
If all known paths fail, the system has one last option: the \fBdefault\fP
route.  This route is a special type of gateway route (usually the only one
present in the system), and is always marked with a ``\fCc\fP'' in the flags
field.  For hosts on a local area network, this gateway is set to whatever
machine has a direct connection to the outside world (whether via PPP link, or
your hardware device attached to a dedicated data line).
.P
If you are configuring the default route for a machine which itself is
functioning as the gateway to the outside world, then the default route will be
the gateway machine at your Internet Service Provider's (ISP) site.
.P
Let's look at an example of default routes. This is a
common configuration:
.Ds
[Local2]  <--ether-->  [Local1]  <--PPP-->  [ISP-Serv]  <--ether-->  [T1-GW]
.De
The hosts \fCLocal1\fP and \fCLocal2\fP are at your site, with the formed being
your PPP connection to your ISP's Terminal Server. Your ISP has a local network
at their site, which has, among other things, the server where you connect and a
hardware device (T1-GW) attached to the ISP's internet feed.
.P
The default routes for each of your machines will be:
.Ds
host            default gateway        interface
----            ---------------        ---------
Local2          Local1                 ethernet
Local1          T1-GW                  PPP
.De
A common question is ``Why (or how) would we set the T1-GW to be the default
gateway for Local1, rather than the ISP server it is connected to?''.
.P
Remember, since the PPP interface is using an address on the ISP's local network
for your side of the connection, routes for any other machines on the ISP's
local network will be automatically generated. Hence, you will already know how
to reach the T1-GW machine, so there is no need for the intermediate step of
sending traffic to the ISP server.
.P
As a final note, it is common to use the address ``\fC...1\fP'' as the gateway
address for your local network. So (using the same example), if your local
class-C address space was \fC10.20.30\fP and your ISP was using \fC10.9.9\fP
then the default routes would be:
.Ds
Local2 (10.20.30.2)             -->  Local1 (10.20.30.1)
Local1 (10.20.30.1, 10.9.9.30)  -->  T1-GW (10.9.9.1)
.De
.H2 "Dual homed hosts"
There is one other type of configuration that we should cover, and that is a
host that sits on two different networks. Technically, any machine functioning
as a gateway (in the example above, using a PPP connection) counts as a
dual-homed host. But the term is really only used to refer to a machine that
sits on two local-area networks.
.P
In one case, the machine as two ethernet cards, each having an address on the
seperate subnets. Alternately, the machine may only have one ethernet card, and
be using ifconfig aliasing. The former is used if two physically separate
ethernet networks are in use, the latter if there is one physical network
segment, but two logically seperate subnets.
.P
Either way, routing tables are set up so that each subnet knows that this
machine is the defined gateway (inbound route) to the other subnet.  This
configuration, with the machine acting as a Bridge between the two subnets, is
often used when we need to implement packet filtering or firewall security in
either or both directions.
.H2 "Routing propogation"
We have already talked about how we define our routes to the outside world, but
not about how the outside world finds us.
.P
We already know that routing tables can be set up so that all traffic for a
particular address space (in our examples, a class-C subnet) can be sent to a
particular host on that network, which will forward the packets inbound.
.P
When you get an address space assigned to your site, your service provider will
set up their routing tables so that all traffic for your subnet will be sent
down your PPP link to your site. But how do sites across the country know to
send to your ISP?
.P
There is a system (much like the distributed DNS information) that keeps track
of all assigned address-spaces, and defines their point of connection to the
Internet Backbone. The ``Backbone'' are the main trunk lines that carry internet
traffic across the country, and around the world. Each backbone machine has a
copy of a master set of tables, which direct traffic for a particular network to
a specific backbone carrier, and from there down the chain of service providers
until it reaches your network.
.P
It is the task of your service provider to advertise to the backbone sites that
they are the point of connection (and thus the path inward) for your site.  This
is known as route propogation.
.H2 "Troubleshooting"
Sometimes, there is a problem with routing propogation, and some sites are
unable to connect to you. Perhaps the most useful command for trying to figure
out where a routing is breaking down is the \fCtraceroute\fP command.  It is
equally useful if you cannot seem to make a connection to a remote machine
(ie. \fCping\fP fails).
.P
The \fCtraceroute\fP command is run with the name of the remote host you are
trying to connect to. It will show the gateway hosts along the path of the
attempt, eventually either reaching the target host, or terminating because of a
lack of connection.
.P
For more information, see the manual page for \fCtraceroute\fP.
.H2 "NFS"
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.
.P
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.
.P
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.
.P
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 desirable in
your application.
.P
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
.P
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
.P
Nearly any 16-bit Ethernet adapter will allow operation without the above
restrictions on the read or write size.
.P
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.
.P
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.
.P
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 guaranteed
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.
