
User's Guide for 'agetty'
-------------------------
by Dennis Cronin

Serial line login administration issues on Unix have always been
complicated, usually involving correctly configuring several files and
sorting through cryptic stty-style options.  This has become even more
convoluted with the arrival of SVR4's Service Access Control facility,
comprised of such tools as ttymon, ttyadm, sacadm, and pmadm.

'agetty' is a little freely redistributable portable "alternate getty" which
attempts to simplify things by gathering into one small package all the
ingredients necessary to support logins over serial lines.  It
incorporates some intelligence so that you don't need to specify so
many parameters, but it also allows you to specify many things
explicitly if you choose.

If you've ever worked with ttymons, sacadm and the like, you know
it's a bit confusing trying to get all the pieces together to
establish a working login.  Imagine being able to provide a fully
functional modem login by simply adding one line to a file:

   tt20:234:respawn:/usr/sbin/agetty /dev/term/20 9600

That's all it takes to establish a working 9600 baud modem connect with
'agetty'!

In addition to making things simpler, 'agetty' provides some features
not available with a standard getty or ttymon including special
"session cleanup" features, direct support for hardware flow control,
more versatile configuration of sign on messages, and support for baud
rates above 38400 on certain hardware.

In this user's guide, we will focus primarily on the use of 'agetty'
as a replacement for the above mentioned tangle of TTY
administration commands provided with SVR4.  'agetty' is very
portable and can also be used on SunOS 4.1 and other BSD-derived
systems.  The 'agetty' man page provides information about use in
those environments.  However many of the usage suggestions made
here will apply to either environment.

The first two sections discuss preliminaries you'll need to attend to
before using 'agetty' in general.  The remaining sections discuss the
various common usages.



Getting SAC Out of the Way
--------------------------
The first step to using 'agetty' on an SVR4 system is to make sure that
Service Access Controller (SAC) et. al. are not using the ports you
want to configure.  The accompanying man page suggests turning off SAC
entirely-- we won't be quite so dire here.

As root, type:

  sacadm -l

This gives a list of all sacadm ongoing activities.  Some may in fact
not be enabled, but they are shown anyhow.  Simply look for entries
like:

  ttymon0  ttymon   -    2   ENABLED   /usr/lib/saf/ttymon

There may be several.  The first field is just a tag field, the second
field is what to look for.  If it says "ttymon" we want to make sure it
stays out of the way.

For every entry that has "ttymon" as a second field, substitute in the
_first_ field for "handle" in the following command:

  sacadm -r -p handle

Thus to remove the above ttymons, you would type:

  sacadm -r -p ttymon0

Repeat as necessary to make sure all ttymons are removed.

Note:  when you reboot, you may find that these entries have a way of
reappearing.  I'm not quite sure why sacadm does this, but don't
worry.  They may be listed, but all the ttymons will in fact be in a
disabled state.  You can check for sure by using:

  pmadm -l

This lists all current ttymon processes and (somewhat cryptically)
shows their state.  Check for an "x" or a "ux" in the fourth field
indicating that ttymon is inactive.

Also, don't be thrown off by the fact that "sacadm -l" reports ENABLED
for these reappearing ttymons even when pmadm reports that they're
disabled.  They're not really active.  This little "x" is what counts,
not the all-upper-case "ENABLED".  That's just one of the beautiful
features of SAC, its totally counter-intuitive interface!


One other note for the paranoid: the console ttymon is usually spawned
directly from /etc/inittab and will not be affected by this.  If you're
worried, make sure you see an entry directly in /etc/inittab for a
/dev/console ttymon before disabling all ttymons as described above.



Adding an Entry to /etc/inittab
-------------------------------
To enable an 'agetty' login, you will add an entry to the /etc/inittab
file.  That's all there is to it.  No other files to modify.

A typical /etc/inittab entry for 'agetty' will look like so:

   tt20:234:respawn:/usr/sbin/agetty /dev/term/20 9600

As noted above, this simple entry will enable a perfectly functional
dialup 9600 baud login!

The first field is merely a tag field.  It must be unique, and should
not exceed four characters in length.  It's not used for anything that
I'm aware of so I wouldn't try to encode any useful information in it,
just pick a unique string.

The next field specifies what run levels will invoke the entry.  "234"
will be the almost universal proper value here.

The third field determines whether the entry is active or not.  A value
of "respawn" means active, and "off" means inactive.

The last field is the spec for the command to run, in our case,
'agetty'.  We have placed 'agetty' in /usr/sbin and we specify its full
path.   We also fully specify the device path (you can leave off the
"/dev/" if you like).  The last argument sets the baud rate to 9600.


After you modify /etc/inittab and write it back out, you need to notify
the 'init' process to cause it to reread this file.  Do this by typing
one of the following cryptic commands:

  kill -HUP 1

or:

  telinit q

These equivalent commands both force 'init' to rescan /etc/inittab and
respond to any changes.  Remember one of these quirky commands-- you'll
use it a lot.

Tip: to disable a login without completely removing an entry, change
the "respawn" field to "off" and type one of the above commands (and
vice versa to re-enable).

Tip: if you change a parameter in an /etc/inittab entry, you must
disable and then re-enable the login to get 'init' to recognize the
change.  Simply changing the parameter and then using "telinit q" won't
do it.



Local 3-Wire Terminal Login
---------------------------
To use a local terminal connected via a 3-wire cable (or other cabling
which does not carry the DCD signal), you will use the "-L" option.
This tells 'agetty' to open in "ignore carrier" mode.  Since it is a
local terminal, you probably know the baud rate it will be operating at
so you won't need any autobauding features.  And you probably also know
the terminal type so you can pass that explicitly to 'agetty' so that
it can prepare the environment.  You might use:

  tt20:234:respawn:/usr/sbin/agetty -L -T vt100 /dev/term/20 9600

This passes a terminal type of "vt100" to the login environment, and
sets the baud rate to 9600 baud.  This will recognize any
7-bits-with-parity line settings or 8 bits-no-parity.


If you want to explicitly specify the line settings as 7 bits, even
parity, 1 stop bit, 19200 baud, you could use:

  tt20:234:respawn:/usr/sbin/agetty -7 -E -1 -L -T vt100 \
    /dev/term/20 19200

Note: you may enter the above as one long line or use the backslash
character (as shown) to continue to a second line.

The "-N", "-E", and "-O" options set "none", "even", and "odd" parity
modes respectively.  The character size must be either "-7" or "-8",
and the stop bits must be either "-1" or "-2".



Local Terminal with "Flat Cable" Wiring
---------------------------------------
If you have a local terminal connected via full 25 wire cable (or
wiring that carries the DCD signal), you would use a similar login to
the one described above for a 3-wire connection, but you would probably
also want to monitor carrier.  This would cause a session to be
properly terminated if the user turned off the terminal.

Again, we'll assume that since it's a local terminal you know the
terminal type and baud rate.  You might use:

  tt20:234:respawn:/usr/sbin/agetty -T wy30 /dev/term/20 9600

This passes a terminal type of "wy30" to the login environment, and
sets the baud rate to 9600 baud.  This will recognize any
7-bits-with-parity line settings or 8-bits-no-parity.


If you want to explicitly specify the line settings as 8 bits, odd
parity, 2 stop bit, 300 baud, you could use:

  tt20:234:respawn:/usr/sbin/agetty -8 -O -2 -L -T vt100 \
    /dev/term/20 300

Note: you may enter the above as one long line or use the backslash
character (as shown) to continue to a second line.

The "-N", "-E", and "-O" options set "none", "even", and "odd" parity
modes respectively.  The character size must be either "-7" or "-8",
and the stop bits must be either "-1" or "-2".



Simplest Modem Login
--------------------
As indicated above, you can establish a perfectly functional 9600 baud
modem login as simply as:

   tt20:234:respawn:/usr/sbin/agetty /dev/term/20 9600

This will work just fine for many purposes!



Better Modem Login
------------------
Next we'll look at a few ways to enhance the basic modem login.

One thing we should mention before we get into modem logins in any more
detail is that you'll probably want to ignore the autobauding features
of 'agetty' with modern modems.  Autobauding was useful back before
before intelligent modems with data compression and error correction
arrived on the scene.  The modem simply encoded the line transitions of
the transmit signal, and it was up to the host to determine the baud
rate and line settings.

With modern modems, the interface characteristic between the host and
the modem should be set and left alone, preferably written to
non-volatile memory in the modem.  The rest is left to the intelligent
modems themselves to work out.

So the first thing we'll add to the basic modem login is an explicitly
specified line setting of 8 bits, no parity, 1 stop bit.  The
associated options are "-8 -N -1".  You will probably never want to use
any 7-bits-with-parity mode since modern modems do the error correction
for you; parity checking would be redundant.

We'll also want to specify the terminal type as "unknown" or "dialup"
to make it clear to any applications if the user fails to establish
their terminal type after logging in.  The option "-T unknown" or "-T
dialup" should be used.

And finally, we'll add a timeout so that if the user fails to complete
a login within 60 seconds, the connection will be dropped.  This will
prevent a failing login from unnecessarily tying up a modem.  We'll use
the option "-t 60" to set this timeout interval.

Thus we have:

   tt20:234:respawn:/usr/sbin/agetty -8 -N -1 -T unknown -t 60 \
     /dev/term/20 9600

Note: you may enter the above as one long line or use the backslash
character (as shown) to continue to a second line.


A few more nicities:

You might want to change the login prompt from the standard terse
"login: " to "Enter username: " or something similar.  You would set
this via the "-b" option.  Note that a multi-word prompt must be
enclosed in double quotes.  Thus you would have:

   tt20:234:respawn:/usr/sbin/agetty -8 -N -1 -T unknown -t 60 \
     -b "Enter username: " /dev/term/20 9600

You can add a short welcome message prior to the login prompt by using
the "-c" option.

   tt20:234:respawn:/usr/sbin/agetty -8 -N -1 -T unknown -t 60 \
     -b "Enter username: " -c "*** Welcome to NetLag ***" \
     /dev/term/20 9600

The "-c" option does not provide any way to embed newlines or carriage
returns.  If you want display a longer welcome message, you may create
a file called "/etc/issue".  No additional options are necessary.  If
this file exists, by default it will be displayed.  However, if
"/etc/issue" exists and you _don't_ want it displayed you can use the
"-i" option to suppress it.

Tip: beware of using excessively long "/etc/issue" messages.  The
modem's and/or user's flow control modes may not yet be in place
resulting in a garbled display.



Advanced Modem Logins
---------------------
There are still a few more things you might want to incorporate
if you are a modem "power user" or are servicing a large modem
dialup pool.

Hardware flow control can be useful, maybe even vital, when operating
at baud rates much above 9600.  Simply add the "-h" option to enable
hardware flow control.  Note: some Unix serial port hardware may not
(fully) support hardware flow control.

Adding in hardware flow control, we might have something like:

   tt20:234:respawn:/usr/sbin/agetty -8 -N -1 -h -T unknown -t 60 \
     -b "Username: " /dev/term/20 9600


You might find you want to use baudrates above 38400 to fully utilize
a modem's data compression capabilities.  'agetty' recognizes the
additional baud rates of 57600, 76800, and 115200.  Currently, it has
only been modified to support these baud rates on Digi International
(formerly Central Data) EtherLite and SCSI Terminal Server hardware,
but there is no reason that other vendors could not provide their own
extensions to 'agetty' in the future.

Here we set 57600 baud just like we would any other:

   tt20:234:respawn:/usr/sbin/agetty -8 -N -1 -h -T unknown -t 60 \
     -b "Username: " /dev/term/20 57600

One final and very useful feature is the entry/exit command option.
The "-e" option lets you specify a command which will be executed
before starting a new session.

Of particular interest in this regard is a little script developed by
John DiMarco (included with this package) which addresses the common
problem of background jobs left running after a session terminates.  A
user who leaves a background job running after they log off can cause
problems as this background job may make the operating system think the
serial port is still open.  The connection may fail to be properly
dropped when the user logs out, or other side effects may result.  In
any case, if you are administering a large Unix dialup modem pool, this
option and the 'ttyclean' command may come in quite handy.

If we put a copy of 'ttyclean' in /usr/sbin/ we might use the "-e"
option thusly:

   tt20:234:respawn:/usr/sbin/agetty -8 -N -1 -h -T unknown -t 60 \
     -b "Username: " -e /usr/sbin/ttyclean /dev/term/20 76800



Dialout Connections
-------------------
'agetty' will coexist peacefully with the standard dialout commands
such as 'cu', 'tip', 'uucico', 'kermit', and others given that the OS
provides two distinct nodes per serial port: a dialin flavor and a
dialout flavor.  'agetty' uses the dialin nodes exclusively while those
other commands would be restricted to using the dialout ones.

Sometimes the dialout nodes are located in /dev/cua or are named 
something like /dev/cua*.  Other naming conventions abound however.

We won't go into the use of 'cu', 'tip', and friends here, we will
provide a pointer to one other utility you might find useful when
administrating serial ports.  A little utility called 'dinc' is
available from ftp.cd.com.  Like 'agetty', this utility avoids the use
of setup files entirely, and in addition provides some handy features
not supplied by the traditional Unix dialout tools.  While it may not
really be a tool for the average user, it's still probably a welcome
addition to the tool set of anyone who regularly has to deal with Unix
serial ports.


Credits
-------
'agetty' was written by Wietse Venema, enhanced by John DiMarco,
and enhanced some more by Dennis Cronin.  It is freely redistributable,
source code is supplied, and you may modify further to suit your
needs.  Refer to the accompanying COPYRIGHT file for details.
