Digi International agetty User's Guide and Tutorial 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. On our FTP site, it is in /pub/prog/agetty. The one for Solaris 2.x is called agetty.sol2, and is the actual binary. Just download it, rename it to simply agetty, and put in in /usr/sbin. 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's 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. This document was written by Dennis Cronin, but later modified by Vic Serbe (Vic_Serbe@dgii.com).