GETTY(1m)

NAME
getty - sets terminal mode, speed, and conditions port

SYNOPSIS
/sbin/getty [-d defaults_file ] [-C connect_script ] [-D debug_value ] [-R] [-a] [-h] [-r delay ] [-t timeout ] [-w waitfor ] port [speed [type [lined]]]
/sbin/getty -c gettydefs_file

DESCRIPTION
Getty is the second in the series of programs ( init(1m), getty(1m), login(1m), and shell [bash, sh, or others]), used by the system to connect the user to the system (i.e., allow the user to login and thus gain access to system resources). Note that telnet has it's own login process and does not use getty. Getty is invoked by init(1m) to:

1.  Open the tty port (usually a serial port) and condition the port (by setting its modes);

2.  Print the login prompt, and get the user's name;

3.  Initiate a login process for the user (which prompts the user for the password and validates it).

Getty has many extremely convenient features, for both direct connect devices, as well as modems, such as:

1   Conditioning the port is done by changing the stty attributes associated with that port. Any attribute settable with stty can be used to condition the port, including enabling or disabling modem controls, hardware flow-control or software flow-control, and setting 7 or 8 data bits and odd, even, mark or space parity;

2   Allows a multiple-use port for inbound and/or outbound connections - data and fax;

3   Allows extensive prompt substitution, for custom login banners and login prompts.

4   Auto-baud detects under a variety of conditions.

5   Optionally uses an alternate /etc/issue file, or does not issue a login banner;

6   Optionally uses the /etc/ttytype file, or the tty type can be set from the command line (the former is a nice feature if you want others to be able to change terminal types, but don't want to give them access to /etc/inittab );

7   Optionally invokes an alternate login program, instead of the default /bin/login ;

8   Supports ringback, if desired.

The actual procedure that getty uses is as follows:

Initially, getty parses its command line. If no errors are found, and the tty type from the command line is set to "unknown" (the default value), or not set, getty checks for the tty type in /etc/ttytype if the program was compiled with TTYTYPE defined. If a tty type is found, either on the command line or in the /etc/ttytype file, then it is placed into the TERM environment variable. Next, getty scans the defaults file, normally /etc/default/getty, to determine certain runtime values (/etc/conf.getty if compiled with FSSTND option). The values in the defaults file (whose compiled-in name can be altered with the optional -d defaults_file argument) take precedence to those on the command line. Getty then opens the port for reading and writing, and disables stdio buffering. If an initialization was specified, it is performed (see LINE INITIALIZATION).

After the initialization, the port is closed and reopened. This time, however, the port is opened in blocking mode so that the device is not tied up. Detection of the carrier signal will allow the port to be opened.

Next, getty displays the issue (or login banner, usually from /etc/issue) if configured to do so, and login prompt. Finally, getty reads the user's login name and invokes login(1m) (or another program, if configured) with the user's name as an argument. While reading the name, getty attempts to adapt the system to the speed of the terminal being used, and also sets certain terminal parameters (see termios(3)) to conform with the user's login procedure.

COMMAND ARGUMENTS
The tty device used by getty is determined by the port argument. Getty uses the string /dev/port as the name of the device to attach itself to. The speed argument, if present, is used as a label to find an entry in the /etc/gettydefs file (see gettydefs(4)). This entry defines to getty the initial speed (baud rate) and tty settings, the login prompt to be used, the final speed and tty settings, and a pointer to another entry to try should the user indicate that the speed is not correct. This is indicated by sending a <break> character (actually sequence). Under certain conditions, a carriage-return will perform the same function. This is usually the case when getty is set to a higher speed than the modem or terminal. Getty scans the gettydefs file sequentially looking for a matching entry. If no speed was given or the entry cannot be found, the first entry in the /etc/gettydefs file is used as a default. In the event that the gettydefs file cannot be accessed, there is a compiled-in default entry that is used. The optional type argument is a string which identifies the type of terminal attached to the port. This type should be a valid terminal name listed in the termcap(7) database. Getty uses this value to determine how to clear the video display. It also sets the environment variable TERM to this value, which is exported thru login(1m) to the shell. If this argument is not present and getty was compiled with TTYTYPE enabled, then the terminal type is looked up in the tty type file, usually named /etc/ttytype and the corresponding type from there is used. The lined argument is a string describing the line discipline to use on the port. The default is LDISC0. The name of the defaults file can be changed by specifying -d defaults_file on the command line. If defaults_file begins with a slash, it is assumed to be a complete pathname of the defaults file to be used. Otherwise, it is assumed to be a regular filename, causing getty to use the pathname /etc/default/defaults_file. or /etc/conf.defaults_file if compiled with FSSTND compliance. Using -C connect_script on the command line (or using CONNECT=string in the defaults file) will cause getty to do a connection chat sequence. Specifying the -D debug_value switch on the command line (or using DEBUG=debug_value in the defaults file) will cause getty to log it's progress in the log file specified at compile time, or the syslog file, if none was specified. Using the -R switch on the command line (or using RINGBACK=YES in the defaults file) will cause getty to use ringback mode on this port. The switch -a Init_Device specifed on the command line (or using INITLINE=Init_device in the defaults file) will cause getty to open the init_device and do the INIT script and WAITCHAR on this device instead of the port specified on the command line. Unless getty is invoked with the -h flag (or HANGUP=NO is specified in the defaults file), it will force a hangup on the port by setting the speed to zero. Giving -r delay on the command line (or using WAITCHAR=YES and DELAY=delay in the defaults file) will cause getty to wait for a single character from the port, and then to wait delay seconds before continuing. If no delay is desired, use -r0. Entering an argument of -t timeout on the command line (or using TIMEOUT=number in the defaults file) will cause getty to exit (which init should then respawn), if the login is not completed within timeout seconds (after the login name is entered). This option behaves differently for getty and uugetty. If getty is used, the counting will start after single input from the user has been detected, whileas with uugetty, the counting will start immediately after login(1m) has been spawned, no matter the input from the user. Giving -w waitfor on the command line (or using WAITFOR=waitfor in the defaults file) will cause getty to wait for the specified string of characters from the port before continuing.

GENERAL OPERATION
As mentioned, getty displays the login prompt and then reads the user's login name. If a null character is received, it is assumed to be the result of the user pressing the <break> key or the carriage-return key to indicate the speed is wrong. This causes getty to locate the next speed in the series (defined in /etc/gettydefs).

The user's name is expected to be terminated by a new-line or carriage-return character. A carriage-return results in the system being set to map those to new-lines (see ioctl(2)).

The user's name is scanned to see if it contains only upper-case characters. If so, the system is set to map any future upper-case characters into lower-case. Note that on Linux, the shell /bin/sh does not process this correctly.

A check option is provided for testing the gettydefs file. When getty is invoked with the -cgettydefs option, it scans the named gettydefs file and prints out (to the standard output) the values it sees. If any parsing errors occur (due to errors in the syntax of the gettydefs file), they are reported.

DEFAULTS FILE
During its startup, getty looks for the file /etc/default/getty.port, (or, if it cannot find that file, then /etc/default/getty), and if found, reads the contents for lines of the form
NAME=value
This allows getty to have certain features configurable at runtime, without recompiling. The recognized NAME strings, and their corresponding values, follows:

SYSTEM=name
    Sets the nodename value (displayed by @S -- see PROMPT SUBSTITUTIONS) to name. The default is the nodename value returned by the uname(3) call.

VERSION=string
    Sets the value that is displayed by the @V parameter (see PROMPT SUBSTITUTIONS) to string. If string begins with a '/' character, it is assumed to be the full pathname of a text file, and @V is set to be the contents of the first line in that file (line has to be terminated by newline character or by end of file).
    The default is /proc/version.

LOGIN=name
    Sets the name of the login program to name. The default is /bin/login (see login(1m)). If used, name must be the full pathname of the program that getty will execute instead of /bin/login. Note that this program is called, as is /bin/login, the with the user's name as its only argument.

INIT=string
    If defined, string is an expect/send sequence that is used to initialize the port before getty attempts to use it. This string is in a form resembling that used in the L.sys file of uucp(1). For more details, see LINE INITIALIZATION. By default, no initialization is done.

ISSUE=string
    During startup, getty defaults to displaying, as an issue or login banner, the contents of the /etc/issue file. If ISSUE is defined to a string, that string is displayed instead. If string begins with a '/' character, it is assumed to be the full pathname of a file, and that file is used instead of /etc/issue.

CLEAR=value
    If value is NO, then getty will not attempt to clear the video screen before displaying the issue or login prompts. The default is to clear the screen.

HANGUP=value
    If value is NO, then getty will NOT hangup the port during its startup. This is analogus to giving the -h argument on the command line.

WAITCHAR=value
    If value is YES, then getty will wait for a single character from it's port before continuing. This is useful for modem connections where the modem has CD forced high at all times, to keep getty from endlessly chatting with the modem.

DELAY=seconds
    Used in conjunction with WAITCHAR, this adds a time delay of seconds after the character is accepted before allowing getty to continue. Both WAITCHAR and DELAY have the same effect as specifying -rdelay on the command line. If WAITCHAR is given without a DELAY, the result is equal to having said -r0 on the command line. The default is to not wait for a character.

TIMEOUT=number
    As with the -t timeout command line argument, tells getty to exit if no user name is accepted before the number of seconds elapse after the login prompt is displayed. With getty, the counting will start as soon as a single character has been entered by the user, whileas with uugetty, the counting will start immediately after the login prompt is displayed, no matter the input from the user.
    The default is to wait indefinitely for the user name.

CONNECT=string
    If defined, string should be an expect/send sequence (like that for INIT) to direct getty in establishing the connection. String may be defined as DEFAULT, which will substitute the built-in string:
    CONNECT\s\A\r\n
    The \A escape marks the place where the digits showing the speed will be seen. See CONNECTION AND AUTOBAUDING for more details. The default is to not perform a connection chat sequence.

WAITFOR=string
    This parameter is similar to WAITCHAR, but defines a string of characters to be waited for. Getty will wait until string is received before issuing the login prompt. This parameter is best used when combined with CONNECT, as in this example:
    WAITFOR=RING
    CONNECT="" ATA\r CONNECT\s\A
    This would cause getty to wait for the string RING, then expect nothing, send ATA followed by a carriage-return, and then wait for a string such as CONNECT 2400, in which case, getty would set itself to 2400 baud. The default is not to wait for any string of characters.

ALTLOCK=port
    Uugetty uses this parameter to lock an alternate device, in addition to the one it is attached to. This is for those systems that have two different device names that refer to the same physical port; e.g. /dev/tty1A vs. /dev/tty1a, where one uses modem control and the other doesn't. See the section on UUGETTY for more details. The default is to have no alternate lockfile.

ALTLINE=port
    Getty uses this parameter to specify a different device to use for handling modem initialization. If the WAITFOR option is being used, WAITFOR will be done on this port also. This is necessary for systems that exercise locking between two ports.

RINGBACK=value
    If value is YES ringback callin is enabled. This is used in conjunction with WAITFOR and CONNECT to negotiate incoming calls. The default action is to connect only if the line rings one to three times, is hung up, and is called back within 60 seconds of the first call. MINRBTIME and MAXRBTIME specify the minimum and maximum time for the second call. INTERRING specifies the maximum time between two successive rings in the same call. MINRINGS and MAXRINGS specify the minimum and maximum number of rings for the first call.

SCHED=range1 range2 range3 ...
    Getty uses this line to schedule times to allow logins. Each range has the form DOW:HR:MIN-DOW:HR:MIN. DOW is the day of the week. 0 = Sunday, 1 = Monday, ... 6 = Saturday. HR is the hour, and MIN is the minute. If the current time falls into one of these ranges, the INIT sequence (if any) is sent and getty continues to run until the off time. Otherwise, the OFF sequence is sent, and getty sleeps until the on time.

OFF=string
    This line is identical to the INIT line, except it is only sent when the port is scheduled to be OFF.

FIDO=string
    This line specifies the path to the FidoNet mailer (usually ifcico). Undefined by default. When setting up a FidoNet mailer, you should also set EMSI to yes. When an incoming FidoNet call is received, the string tsync or yoohoo is passed to the FidoNet mailer as the only command line option if two TSYNC or two YOOHOO sequences are received. If EMSI is set to yes, the entire EMSI string (starting with the first asterisk, and up to but not including the final carraige return) is passed as the only command line option.

EMSI=value
    If set to yes, scan the input for FidoNet EMSI sequences.

PROMPT SUBSTITUTIONS
When getty is displaying the issue or login banner (ususally /etc/issue), or the login-prompt, it recognizes several escape (quoted) characters. When one of these quoted characters is found, its value is substituted in the output produced by getty. Recognized escape characters are:

\\  Backslash (\).

\b  Backspace (^H).

\c  Placed at the end of a string, this prevents a new-line from being displayed after the string.

\f  Formfeed (^L).

\n  New-line (^J).

\r  Carriage-return (^M).

\s  A single space (' ').

\t  Horizontal tab (^I).

\nnn
    Outputs the ASCII character whose decimal value is nnn. If nnn begins with 0, the value is taken to be in octal. If it begins with 0x, the value is taken to be in hexidecimal.

In addition, a single backslash at the end of a line causes the immediately following new-line to be ignored, allowing continuation lines.

Also, certain @char parameters are recognized. Those parameters, and the value that is substituted for them are:

@B  The current (evaluated at the time the @B is seen) baud rate.

@D  The current date, in MM/DD/YY .

@F  The Fully Qualified Domain Name (FQDN) of the system.

@L  The port (serial line) to which getty is attached.

@M  The architecture identifier of the machine ("i386", for example).

@O  The Operating System name of the system ("Linux", for example).

@R  The operating system release identifier of the system ("2.4.5", for example).

@S  The system node name.

@T  The current time, in HH:MM:SS (24-hour) .

@U  The number of currently signed-on users. This is a count of the number of entries in the /etc/utmp file that have a non-null ut_name field.

@V  The value of VERSION, as given in the defaults file.

@u  The value "1 user" or "<n> users", where <n> is the number of currently signed-on users. <n> is computed like "@U", above.

To display a single '@' character, use either '\@' or '@@'.

LINE INITIALIZATION
One of the greatest benefits (in the author's opinion, at least) is the ability of getty to initialize its port before use. This will most likely be done on ports with modems, not terminals, although initializing terminals is not out of the question.

Port initialization is performed just after the port is opened and prior to handling the WAITCHAR and/or WAITFOR options. Initialization is accomplished by placing an
INIT=string
line in the defaults file. String is a series of one or more fields in the form
expect [ send [ expect [ send ] ] ... ]
This resembles the expect/send sequences used in the UUCP L.sys file, with the following exception: A carriage return is NOT appended automatically to sequences that are 'sent.' If you want a carriage-return sent, you must explicitly show it, with '\r'.

Getty supports subfields in the expect field of the form
expect[-send-expect]...
as with UUCP. All the escape characters (those beginning with a '\' character) listed in the PROMPT SUBSTITUTIONS section are valid in the send and expect fields. In addition, the following escape characters are recognized:

\p  Inserts a 1-second delay.

\d  Inserts a 2-second delay.

\K  Sends a .25-second Break.

\Tnnn
    Modifies the default timeout (usually 30 seconds) to the value indicated by nnn. The value nnn may be decimal, octal, or hexidecimal; see the usage of \nnn in PROMPT SUBSTITUTIONS.

Note that for these additional escape characters, no actual character is sent.

CONNECTION AND AUTOBAUDING
Getty will perform a chat sequence establish a proper connection. The best use of this feature is to look for the CONNECT message sent by a modem and set the port speed to the number given in that message (e.g. CONNECT 2400). Note that for modern modems, it makes much more sense to leave the serial port at a fixed baud (normally the highest supported by the modem), and have the modem data speed (i.e., the speed over the phone line) vary. That way, you are always assured of the maxumum transfer rate. (Because, the modems will connect at the highest common baud rate, subject to phone line quality; if the serial port is faster, then the flow control will regulate the data flow between the modems.)

The structure of the connect chat script is exactly the same as that for the INIT script (see LINE INITIALIZATION), with the following addition:

\A  Marks the spot where the baud rate will be seen. This mark will match any and all digits 0-9 at that location in the script, and set it's speed to that value, if possible.

Autobauding, therefore, is enabled by placing the \A mark in the chat script. For example, the definition:
CONNECT=CONNECT\s\A
would match the string CONNECT 1200 and cause getty to set it's baud rate to 1200, using the following steps:

1.  Having matched the value 1200, getty will attempt to find an entry with the label 1200 in the gettydefs file. If a matching gettydefs entry is found, those values are used. If there is no match, then

2.  The gettydefs values currently in use are modified to use the matched speed (e.g. 1200). However, if the matched speed is invalid, then

3.  Getty logs a warning message and resumes normal operation. This allows the practice of toggling through linked entries in the gettydefs file to behave as expected.

UUGETTY
Uugetty has identical behavior to getty, except that uugetty is designed to create and use the lock files maintained by the UUCP family (uucp(1), cu(1) and others). This prevents two or more processes from having conficting use of a tty port.
Uugetty also differs from getty by handling the -t parameter and TIMEOUT option.

When uugetty starts up, if it sees a lock file for the port it intends to use, it will use the pid in the lock file to see if there is an active process holding the lock. If not, uugetty will remove the lock file and continue. If a valid process is found, uugetty will sleep until that process releases the lock and then it will exit, forcing init(1m) to spawn a new uugetty. Once no conflicting process is found, uugetty grabs the port by creating the lock file itself before issuing the login prompt. This prevents other processes from using the port.

Uugetty will normally only lock the name of the port it is running on. On systems where there are two device names referring to the same port (as is the case where one device uses modem control while the other doesn't), place a line of the form
ALTLOCK=port
line in the defaults file. For instance, if uugetty is on /dev/tty1a, and you want to have it lock /dev/tty1A also, use the line ALTLOCK=tty1A in the defaults file. Note that on Linux (after kernel 2.0.0 or so), the use of the non-modem port "cuax" is discouraged. Uugetty is set up to work with only the modem-control "ttySx" port, by exact use of permissions and ownership of the port (owned by user UUCP), in conjunction with suid. Other programs wishing to share a modem port with uugetty should work well if they also are owned by uucp and have the suid bit set on their executable (plus whatever additional permissions issues need resolving).

Note that uugetty will work not only with modems, but also with a direct serial connection between two machines. This would allow a fairly secure file transfer channel between two machines. I have acheived throughput in excess of 115200 baud between two systems with a short serial cable (10 feet or so).

While waiting for carrier detect, Uugetty will check for lockfiles every 30 seconds. If lockfiles are found, uugetty will exit, and init will respawn another getty. This allows the modem to be reinitialized after another process has used the modem.

FILES

/etc/default/getty[.port]
    Contains the runtime configuration. Note that uugetty uses /etc/default/uugetty[.port].

/etc/gettydefs
    Contains speed and tty settings to be used by getty.

/etc/ttytype
    Contains TERM value to be passed to the shell (if not present on the command line), associated by port ID.

/etc/issue
    The default issue (or login banner), if any.

/bin/login
    The default login program called after the user's name is entered.

SEE ALSO
init(1m), login(1m), uucp(1), ioctl(2), uname(3), gettydefs(5), issue(5), utmp(5), termios(3)

AUTHORS
Getty_ps in its current magical form:
Christine Jamison  <getty-info@nwmagic.net>
Original getty_ps:
Paul Sutcliffe, Jr.  <paul@devon.lns.pa.us>
UUCP: ...!rutgers!devon!paul
Autobauding routines adapted from code submitted by
Mark Keating <...!utzoo!censor!markk>
And numerous patches and assistance supplied by various helpful people!