freebsd-src/share/doc/handbook/dialup.sgml

<!-- This is an SGML document in the linuxdoc DTD of the Tutorial for
     Configuring a FreeBSD for Dialup Services by Guy Helmer.
     $FreeBSD$

<!DOCTYPE linuxdoc PUBLIC "-//Linux//DTD linuxdoc//EN">


<article>

<title>
Configuring FreeBSD for Dialup Services
<author>Guy Helmer, <tt/ghelmer@alpha.dsu.edu/
<date>v0.1, 28 March 1995
<abstract>

-->

<sect><heading>Dialin service<label id="dialup"></heading>

<p><em>Contributed by &a.ghelmer;.</em>

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.

<sect1><heading>Prerequisites<label id="dialup:prereqs"></>
<p>

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 will need certain versions of FreeBSD,
and knowledge of some terminology &amp; modem and cabling.

<sect2><heading>FreeBSD Version</heading>
<p>

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 (<tt/sio/) has improved in every release of FreeBSD, so
more recent versions of FreeBSD are assumed to have better and more
efficient drivers than earlier versions.

<sect2><heading>Terminology</heading>
<p>

A quick rundown of terminology:

<descrip>

<tag/bps/ Bits per Second - the rate at which data is transmitted

<tag/DTE/ Data Terminal Equipment - for example, your computer

<tag/DCE/ Data Communications Equipment -  your modem

<tag/RS-232/ EIA standard for serial communications via hardware

</descrip>

If you need more information about these terms and data communications
in general, the author remembers reading that <em/The RS-232 Bible/
(anybody have an ISBN?) is a good reference.

When talking about communications data rates, the author does not use
the term <bf/baud/.  Baud refers to the number of electrical state
transitions that may be made in a period of time, while <bf/bps/ (bits
per second) is the ``correct'' term to use (at least it does not seem
to bother the curmudgeons quite a much).

<sect2><heading>External vs. Internal Modems</heading>
<p>

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.

<sect2><heading>Modems and Cables</heading>
<p>

A background knowledge of these items is assumed

<itemize>

<item> You know how to connect your modem to your computer so that the
two can communicate (unless you have an internal modem, which does not
need such a cable)

<item> You are familiar with your modem's command set, or know where
to look up needed commands

<item> You know how to configure your modem (probably via a terminal
communications program) so you can set the non-volatile RAM
parameters

</itemize>

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:

<itemize>
<item> Transmitted Data (<tt/SD/)
<item> Received Data (<tt/RD/)
<item> Request to Send (<tt/RTS/)
<item> Clear to Send (<tt/CTS/)
<item> Data Set Ready (<tt/DSR/)
<item> Data Terminal Ready (<tt/DTR/)
<item> Carrier Detect (<tt/CD/)
<item> Signal Ground (<tt/SG/)
</itemize>

FreeBSD needs the <tt/RTS/ and <tt/CTS/ signals for flow-control at
speeds above 2400bps, the <tt/CD/ signal to detect when a call has
been answered or the line has been hung up, and the <tt/DTR/ 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.

The second prerequisite depends on the modem(s) you use.  If you do not
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.

Lastly, you will 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.

<sect2><heading>Serial Interface Considerations</heading>
<p>

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.

<sect1><heading>Quick Overview</heading>
<p>

Here is the process that FreeBSD follows to accept dialup logins.  A
<tt/getty/ process, spawned by <tt/init/, patiently waits to open the
assigned serial port (<tt>/dev/ttyd0</tt>, for our example).  The
command <tt/ps ax/ might show this:

<tscreen><verb>
 4850 ??  I      0:00.09 /usr/libexec/getty V19200 ttyd0
</verb></tscreen>

When a user dials the modem's line and the modems connect, the <tt/CD/
line is asserted by the modem.  The kernel notices that carrier has
been detected and completes <tt/getty/'s open of the port.  <tt/getty/
sends a <tt/login:/ prompt at the specified initial line speed.
<tt/getty/ 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 <tt/getty/'s speed),
<tt/getty/ tries adjusting the line speeds until it receives
reasonable characters.

We hope <tt/getty/ finds the correct speed and the user sees a
<tt/login:/ prompt.  After the user enters his/her login name,
<tt/getty/ executes <tt>/usr/bin/login</tt>, which completes the login
by asking for the user's password and then starting the user's shell.

Let's dive into the configuration...

<sect1><heading>Kernel Configuration</heading>
<p>

FreeBSD kernels typically come prepared to search for four serial
ports, known in the PC-DOS world as <tt/COM1:/, <tt/COM2:/,
<tt/COM3:/, and <tt/COM4:/.  FreeBSD can presently also handle
``dumb'' multiport serial interface cards, such as the Boca Board
1008 and 2016 (please see the manual page <tt/sio(4)/ for kernel
configuration information if you have a multiport serial card).  The
default kernel only looks for the standard COM ports, though.

To see if your kernel recognizes any of your serial ports, watch for
messages while the kernel is booting, or use the
<tt>/sbin/dmesg</tt> command to replay the kernel's boot messages.  In
particular, look for messages that start with the characters <tt/sio/.
Hint: to view just the messages that have the word <tt/sio/, use the
command: 

<tscreen><verb>
/sbin/dmesg | grep 'sio'
</verb></tscreen>

For example, on a system with four serial ports, these are the
serial-port specific kernel boot messages:

<tscreen><verb>
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
</verb></tscreen>

If your kernel does not recognize all of your serial ports, you will
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'' &lsqb;the source for which is in
<tt>/usr/src/share/doc/smm</tt>&rsqb; and ``FreeBSD Configuration
Options'' &lsqb;in <tt>/sys/conf/options</tt> and in
<tt>/sys/<em>arch</em>/conf/options.<em>arch</em></tt>, with
<em>arch</em> for example being <tt>i386</tt>&rsqb; for more
information on configuring and building kernels.  You may have to
unpack the kernel source distribution if have not installed the system
sources already (<tt>srcdist/srcsys.??</tt> in FreeBSD 1.1,
<tt>srcdist/sys.??</tt> 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 have not
already) by <tt/cd/ing to <tt>/sys/i386/conf</tt>.  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
<em/YOURSYS/, where <em/YOURSYS/ is the name of your system, but in
upper-case letters.  Edit the file, and change the device lines:

<tscreen><verb>
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
</verb></tscreen>

You can comment-out or completely remove lines for devices you do not
have.  If you have a multiport serial board, such as the Boca Board
BB2016, please see the <tt/sio(4)/ 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.

Note that <tt/port "IO_COM1"/ is a substitution for <tt/port 0x3f8/,
<tt/IO_COM2/ is <tt/0x2f8/, <tt/IO_COM3/ is <tt/0x3e8/, and
<tt/IO_COM4/ is <tt/0x2e8/, 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
<bf>cannot</bf> 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 <tt/config/ as documented in ``Building Berkeley Kernels with
Config'' and the <tt/config(8)/ manual page to prepare a kernel
building directory, then build, install, and test the new kernel.

<sect1><heading>Device Special Files</heading>
<p>

Most devices in the kernel are accessed through ``device special
files'', which are located in the <tt>/dev</tt> directory.  The
<tt/sio/ devices are accessed through the <tt>/dev/ttyd?</tt>
(dial-in) and <tt>/dev/cua0?</tt> (call-out) devices.  On FreeBSD
version 1.1.5 and higher, there are also initialization devices
(<tt>/dev/ttyid?</tt> and <tt>/dev/cuai0?</tt>) and locking devices
(<tt>/dev/ttyld?</tt> and <tt>/dev/cual0?</tt>).  The initialization
devices are used to initialize communications port parameters each
time a port is opened, such as <tt>crtscts</tt> for modems which use
<tt>CTS/RTS</tt> signaling 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 <tt/termios(4)/, <tt/sio(4)/,
and <tt/stty(1)/ for information on the terminal settings, locking
&amp; initializing devices, and setting terminal options,
respectively.

<sect2><heading>Making Device Special Files</heading>
<p>

A shell script called <tt/MAKEDEV/ in the <tt>/dev</tt> directory
manages the device special files.  (The manual page for
<tt/MAKEDEV(8)/ on FreeBSD 1.1.5 is fairly bogus in its discussion of
<tt/COM/ ports, so ignore it.)  To use <tt/MAKEDEV/ to make dialup
device special files for <tt/COM1:/ (port 0), <tt/cd/ to <tt>/dev</tt>
and issue the command <tt/MAKEDEV ttyd0/.  Likewise, to make dialup
device special files for <tt/COM2:/ (port 1), use <tt/MAKEDEV ttyd1/.

<tt/MAKEDEV/ not only creates the <tt>/dev/ttyd?</tt> device special
files, but also creates the <tt>/dev/cua0?</tt> (and all of the
initializing and locking special files under FreeBSD 1.1.5 and up) and
removes the hardwired terminal special file <tt>/dev/tty0?</tt>, if it
exists. 

After making new device special files, be sure to check the
permissions on the files (especially the <tt>/dev/cua*</tt> files) to
make sure that only users who should have access to those device
special files can read &amp; write on them - you probably do not want
to allow your average user to use your modems to dialout.  The default
permissions on the <tt>/dev/cua*</tt> files should be sufficient:

<tscreen><verb>
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
</verb></tscreen>

These permissions allow the user <tt/uucp/ and users in the group
<tt/dialer/ to use the call-out devices.

<sect1><heading>Configuration Files</heading>
<p>

There are three system configuration files in the <tt>/etc</tt>
directory that you will probably need to edit to allow dialup access to
your FreeBSD system.  The first, <tt>/etc/gettytab</tt>, contains
configuration information for the <tt>/usr/libexec/getty</tt> daemon.
Second, <tt>/etc/ttys</tt> holds information that tells
<tt>/sbin/init</tt> what <tt/tty/ devices should have <tt/getty/
processes running on them.  Lastly, you can place port initialization
commands in the <tt>/etc/rc.serial</tt> script if you have FreeBSD
1.1.5.1 or higher; otherwise, you can initialize ports in the
<tt>/etc/rc.local</tt> 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 does not know what a user's true data
rate is, so full-screen programs like Emacs will not 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 <tt/getty/ does not
understand any particular modem's connection speed reporting,
<tt/getty/ gives a <tt/login:/ message at an initial speed and watches
the characters that come back in response.  If the user sees junk,
it is assumed that they know they should press the
<tt>&lt;Enter&gt;</tt> key until they see a recognizable prompt.  If
the data rates do not match, <tt/getty/ sees anything the user types as
``junk'', tries going to the next speed and gives the <tt/login:/
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 does not 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.

The author will try to give balanced configuration information, but is
biased towards having the modem's data rate follow the connection
rate.

<sect2><heading>/etc/gettytab</heading>
<p>

<tt>/etc/gettytab</tt> is a <tt/termcap(5)/-style file of
configuration information for <tt/getty(8)/.  Please see the
<tt/gettytab(4)/ manual page for complete information on the format of
the file and the list of capabilities.

<sect3><heading>Locked-Speed Config</heading>
<p>

If you are locking your modem's data communications rate at a
particular speed, you probably will not need to make any changes to
<tt>/etc/gettytab</tt>.

<sect3><heading>Matching-Speed Config</heading>
<p>

You will need to setup an entry in <tt>/etc/gettytab</tt> to give
<tt/getty/ information about the speeds you wish to use for your
modem.  If you have a 2400 bps modem, you can probably use the
existing <tt/D2400/ entry.  This entry already exists in the FreeBSD
1.1.5.1 <tt/gettytab/ file, so you do not need to add it unless it is
missing under your version of FreeBSD:

<tscreen><verb>
#
# 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:
</verb></tscreen>

If you have a higher speed modem, you will probably need to add an entry
in <tt>/etc/gettytab</tt>; here is an entry you could use for a 14.4
Kbps modem with a top interface speed of 19.2 Kbps:

<tscreen><verb>
#
# 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:
</verb></tscreen>

On FreeBSD 1.1.5 and later, this will result in 8-bit, no parity
connections.  Under FreeBSD 1.1, add <tt/:np:/ parameters to the
<tt>std.<em/xxx/</tt> 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.  Communications rate
cycling is implemented with the <tt/nx=/ (<bf/next table/) capability.
Each of the lines uses a <tt/tc=/ (<bf/table continuation/) entry to
pick up the rest of the ``standard'' settings for a particular data
rate.

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 is an example of a
<tt/gettytab/ entry starting a 57.6 Kbps:

<tscreen><verb>
#
# Additions for a V.32bis or V.34 Modem
# Starting at 57.6 Kbps
#
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:
</verb></tscreen>

If you have a slow CPU or a heavily loaded system and you do not have
16550A-based serial ports, you may receive sio ``silo'' errors at 57.6
Kbps.

<sect2><heading>/etc/ttys<label id="dialup:ttys"></heading>
<p>

<tt>/etc/ttys</tt> is the list of <tt/ttys/ for <tt/init/ to monitor.
<tt>/etc/ttys</tt> also provides security information to <tt/login/
(user <tt/root/ may only login on ttys marked <tt/secure/).  See the
manual page for <tt/ttys(5)/ for more information.

You will need to either modify existing lines in <tt>/etc/ttys</tt> or
add new lines to make <tt/init/ run <tt/getty/ 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: 

<tscreen><verb>
ttyd0   "/usr/libexec/getty xxx"   dialup on
</verb></tscreen>

The first item in the above line is the device special file for this
entry - <tt/ttyd0/ means <tt>/dev/ttyd0</tt> is the file that this
<tt/getty/ will be watching.  The second item, <tt>"/usr/libexec/getty
<em/xxx/"</tt> (<em/xxx/ will be replaced by the initial <tt/gettytab/
capability) is the process <tt/init/ will run on the device.  The
third item, <tt/dialup/, is the default terminal type.  The fourth
parameter, <tt/on/, indicates to <tt/init/ that the line is
operational.  There can be a fifth parameter, <tt>secure</tt>, but it
should only be used for terminals which are physically secure (such as
the system console).

The default terminal type (<tt/dialup/ in the example above) may
depend on local preferences.  <tt/dialup/ is the traditional default
terminal type on dialup lines so that users may customize their login
scripts to notice when the terminal is <tt/dialup/ and automatically
adjust their terminal type.  However, the author finds it easier at
his site to specify <tt/vt102/ as the default terminal type, since the
users just use VT102 emulation on their remote systems.

After you have made changes to <tt>/etc/ttys</tt>, you may send the
<tt/init/ process a <tt/HUP/ signal to re-read the file.  You can use
the command

<tscreen><verb>
kill -1 1
</verb></tscreen>

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 signaling <tt/init/.

<sect3><heading>Locked-Speed Config</heading>
<p>

For a locked-speed configuration, your <tt/ttys/ entry needs to
have a fixed-speed entry provided to <tt/getty/.  For a modem whose
port speed is locked at 19.2 Kbps, the <tt/ttys/ entry might look like
this: 

<tscreen><verb>
ttyd0   "/usr/libexec/getty std.19200"   dialup on
</verb></tscreen>

If your modem is locked at a different data rate, substitute the
appropriate name for the <tt>std.<em/speed/</tt> entry for
<tt/std.19200/ from <tt>/etc/gettytab</tt> for your modem's data rate.

<sect3><heading>Matching-Speed Config</heading>
<p>

In a matching-speed configuration, your <tt/ttys/ entry needs to
reference the appropriate beginning ``auto-baud'' (sic) entry in
<tt>/etc/gettytab</tt>.  For example, if you added the above suggested
entry for a matching-speed modem that starts at 19.2 Kbps (the
<tt/gettytab/ entry containing the <tt/V19200/ starting point), your
<tt/ttys/ entry might look like this:

<tscreen><verb>
ttyd0   "/usr/libexec/getty V19200"   dialup on
</verb></tscreen>

<sect2><heading>/etc/rc.serial or /etc/rc.local</heading>
<p>

High-speed modems, like V.32, V.32bis, and V.34 modems, need to use
hardware (<tt>RTS/CTS</tt>) flow control.  You can add <tt/stty/
commands to <tt>/etc/rc.serial</tt> on FreeBSD 1.1.5.1 and up, or
<tt>/etc/rc.local</tt> 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,
<tt>/etc/rc.serial</tt> reads:

<tscreen><verb>
#!/bin/sh
#
# Serial port initial configuration

stty -f /dev/ttyid1 crtscts
stty -f /dev/cuai01 crtscts
</verb></tscreen>

which sets the <tt/termios/ flag <tt/crtscts/ on serial port &num;1's
(<tt/COM2:/) dialin and dialout initialization devices.

On an old FreeBSD 1.1 system, these entries were added to
/etc/rc.local to set the <tt/crtscts/ flag on the devices:

<tscreen><verb>
# 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
</verb></tscreen>

Since there is no 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 are not cleared by a miscreant.

<sect1><heading>Modem Settings</heading>
<p>

If you have a modem whose parameters may be permanently set in
non-volatile RAM, you will need to use a terminal program (such as Telix
under PC-DOS or <tt/tip/ under FreeBSD) to set the parameters.
Connect to the modem using the same communications speed as the
initial speed <tt/getty/ will use and configure the modem's
non-volatile RAM to match these requirements:

<itemize>

<item> <tt/CD/ asserted when connected

<item> <tt/DTR/ asserted for operation; dropping DTR hangs up line
&amp; resets modem

<item> <tt/CTS/ transmitted data flow control

<item> Disable <tt>XON/XOFF</tt> flow control

<item> <tt/RTS/ received data flow control

<item> Quiet mode (no result codes)

<item> No command echo

</itemize>

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:

<tscreen><verb>
ATZ
AT&amp;C1&amp;D2&amp;H1&amp;I0&amp;R2&amp;W
</verb></tscreen>

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:

<itemize>

<item> Switch 1: UP - DTR Normal

<item> Switch 2: Do not care (Verbal Result Codes/Numeric Result Codes)

<item> Switch 3: UP - Suppress Result Codes

<item> Switch 4: DOWN - No echo, offline commands

<item> Switch 5: UP - Auto Answer

<item> Switch 6: UP - Carrier Detect Normal

<item> Switch 7: UP - Load NVRAM Defaults

<item> Switch 8: Do not care (Smart Mode/Dumb Mode)

</itemize>

Result codes should be disabled/suppressed for dialup modems to avoid
problems that can occur if <tt/getty/ mistakenly gives a <tt/login:/
prompt to a modem that is in command mode and the modem echoes the
command or returns a result code.  I have heard this sequence can result
in a extended, silly conversation between <tt/getty/ and the modem.

<sect2><heading>Locked-speed Config</heading>
<p>

For a locked-speed configuration, you will 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:

<tscreen><verb>
ATZ
AT&amp;B1&amp;W
</verb></tscreen>

<sect2><heading>Matching-speed Config</heading>
<p>

For a variable-speed configuration, you will 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:

<tscreen><verb>
ATZ
AT&amp;B2&amp;W
</verb></tscreen>

<sect2><heading>Checking the Modem's Configuration</heading>
<p>

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 <tt/ATI5/ 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 <tt/ATZ/ and then <tt/ATI4/.

If you have a different brand of modem, check your modem's manual to
see how to double-check your modem's configuration parameters.

<sect1><heading>Troubleshooting</heading>
<p>

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

<sect2><heading>Checking out the FreeBSD system</heading>
<p>

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 <tt/DTR/ indicator lights when the <tt/login:/ prompt appears
on the system's console - if it lights up, that should mean that
FreeBSD has started a <tt/getty/ process on the appropriate
communications port and is waiting for the modem to accept a call.

If the <tt/DTR/ indicator doesn't light, login to the FreeBSD system
through the console and issue a <tt/ps ax/ to see if FreeBSD is trying
to run a <tt/getty/ process on the correct port.  You should see a
lines like this among the processes displayed:

<tscreen><verb>
  114 ??  I      0:00.10 /usr/libexec/getty V19200 ttyd0
  115 ??  I      0:00.10 /usr/libexec/getty V19200 ttyd1
</verb></tscreen>

If you see something different, like this:

<tscreen><verb>
  114 d0  I      0:00.10 /usr/libexec/getty V19200 ttyd0
      ^^
</verb></tscreen>

and the modem has not accepted a call yet, this means that <tt/getty/
has completed its open on the communications port.  This could
indicate a problem with the cabling or a mis-configured modem, because
<tt/getty/ should not be able to open the communications port until
<tt/CD/ (carrier detect) has been asserted by the modem.

If you do not see any <tt/getty/ processes waiting to open the desired
<tt/ttyd?/ port, double-check your entries in <tt>/etc/ttys</tt> to
see if there are any mistakes there.  Also, check the log file
<tt>/var/log/messages</tt> to see if there are any log messages from
<tt/init/ or <tt/getty/ regarding any problems.  If there are any
messages, triple-check the configuration files <tt>/etc/ttys</tt> and
<tt>/etc/gettytab</tt>, as well as the appropriate device special
files <tt>/dev/ttyd?</tt>, for any mistakes, missing entries, or
missing device special files.

<sect2><heading>Try Dialing In</heading>
<p>

Try dialing into the system; be sure to use 8 bits, no parity, 1 stop
bit on the remote system.  If you do not get a prompt right away, or
get garbage, try pressing <tt>&lt;Enter&gt;</tt> about once per
second.  If you still do not see a <tt/login:/ prompt after a while,
try sending a <tt>BREAK</tt>.  If you are using a high-speed modem to
do the dialing, try dialing again after locking the dialing modem's
interface speed (via <tt>AT&amp;B1</tt> on a USR Sportster, for
example).

If you still cannot get a <tt/login:/ prompt, check
<tt>/etc/gettytab</tt> again and double-check that

<itemize>
<item> The initial capability name specified in <tt>/etc/ttys</tt> for
the line matches a name of a capability in <tt>/etc/gettytab</tt>

<item> Each <tt/nx=/ entry matches another <tt/gettytab/ capability
name

<item> Each <tt/tc=/ entry matches another <tt/gettytab/ capability
name

</itemize>

If you dial but the modem on the FreeBSD system will not answer, make
sure that the modem is configured to answer the phone when <tt/DTR/ is
asserted.  If the modem seems to be configured correctly, verify that
the <tt/DTR/ line is asserted by checking the modem's indicator lights
(if it has any).

If you have gone over everything several times and it still does not work,
take a break and come back to it later.  If it still does not work,
perhaps you can send an electronic mail message to the &a.questions
describing your modem and your problem, and the good folks on the list will
try to help.

<sect1><heading>Acknowledgments</heading>
<p>

Thanks to these people for comments and advice:

<descrip>

<tag>&a.kelly</tag> for a number of good suggestions

</descrip>