GETTY(1m)GETTY(1m)NAMEgetty - 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 con‐
nect 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 par‐
ity;
2 Allows a multiple-use port for inbound and/or outbound connec‐
tions - 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 run‐
time values (/etc/conf.getty if compiled with FSSTND option). The val‐
ues 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 func‐
tion. This is usually the case when getty is set to a higher speed
than the modem or terminal. Getty scans the gettydefs file sequen‐
tially 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 INIT‐
LINE=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 continu‐
ing. If no delay is desired, use -r0.
Entering an argument of -t timeout on the command line (or using TIME‐
OUT=number in the defaults file) will cause getty to exit (which init
should then respawn), if the login is not completed within timeout sec‐
onds (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 car‐
riage-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 char‐
acters. If so, the system is set to map any future upper-case charac‐
ters 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 corre‐
sponding values, follows:
SYSTEM=name
Sets the nodename value (displayed by @S -- see PROMPT SUBSTITU‐
TIONS) 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 path‐
name 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 ini‐
tialization 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 path‐
name 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 com‐
mand 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 connec‐
tions 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 sec‐
onds after the character is accepted before allowing getty to
continue. Both WAITCHAR and DELAY have the same effect as speci‐
fying -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 addi‐
tion to the one it is attached to. This is for those systems
that have two different device names that refer to the same phys‐
ical 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 nec‐
essary for systems that exercise locking between two ports.
RINGBACK=value
If value is YES ringback callin is enabled. This is used in con‐
junction 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 maxi‐
mum 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 con‐
tinues 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 charac‐
ters 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 immedi‐
ately 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 initializ‐
ing 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 auto‐
matically 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 hex‐
idecimal; 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 sup‐
ported 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 high‐
est 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 addi‐
tion:
\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 0
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 getty‐
defs 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 TIME‐
OUT 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 ALT‐
LOCK=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 ALSOinit(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!
Release 2.1.0 12-Sep-02 GETTY(1m)
