agetty(8)

—

SYNOPSIS

agetty [options] port [baud_rate...] [term]

DESCRIPTION

agetty opens a tty port, prompts for a login name and invokes the /bin/login command. It is normally invoked by init(8).

agetty has several non-standard features that are useful for hardwired and for dial-in lines:

This program does not use the /etc/gettydefs (System V) or /etc/gettytab (SunOS 4) files.

ARGUMENTS

port

Under System V, a "-" port argument should be preceded by a "--".

baud_rate,...

Baud rates should be specified in descending order, so that the null character (Ctrl-@) can also be used for baud-rate switching.

This argument is optional and unnecessary for virtual terminals.

The default for serial terminals is keep the current baud rate (see --keep-baud) and if unsuccessful then default to '9600'.

term

The default is 'vt100', or 'linux' for Linux on a virtual terminal, or 'hurd' for GNU Hurd on a virtual terminal.

OPTIONS

-8, --8bits

-a, --autologinusername

Note that --autologin may affect the way in which getty initializes the serial line, because on auto-login agetty does not read from the line and it has no opportunity optimize the line setting.

-c, --noreset

-E, --remote

If the --hostfakehost option is given, then an -hfakehost option and argument are added to the /bin/login command line.

If the --nohostname option is given, then an -H option is added to the /bin/login command line.

See --login-options.

-f, --issue-filepath

--show-issue

-h, --flow-control

-H, --hostfakehost

-i, --noissue

-I, --init-stringinitstring

-J, --noclear

-l, --login-programlogin_program

-L, --local-line[=mode]

always

never

auto

-m, --extract-baud

Since the --extract-baud feature may fail on heavily-loaded systems, you still should enable BREAK processing by enumerating all expected baud rates on the command line.

--list-speeds

-n, --skip-login

-N, --nonewline

-o, --login-optionslogin_options

--login-options '-h darkstar -- \u'

See --autologin, --login-program and --remote.

Please read the SECURITY NOTICE below before using this option.

-p, --login-pause

-r, --chrootdirectory

-R, --hangup

-s, --keep-baud

-t, --timeouttimeout

-U, --detect-case

-w, --wait-cr

--nohints

--nohostname

--long-hostname

--erase-charsstring

--kill-charsstring

--chdirdirectory

--delaynumber

--nicenumber

--reload

-h, --help

-V, --version

CONFIG FILE ITEMS

agetty reads the /etc/login.defs configuration file (see login.defs(5)). Note that the configuration file could be distributed with another package (usually shadow-utils). The following configuration items are relevant for agetty:

LOGIN_PLAIN_PROMPT (boolean)

EXAMPLE

This section shows examples for the process field of an entry in the /etc/inittab file. You’ll have to prepend appropriate values for the other fields. See inittab(5) for more details.

For a hardwired line or a console tty:

/sbin/agetty 9600 ttyS1

For a directly connected terminal without proper carrier-detect wiring (try this if your terminal just sleeps instead of giving you a password: prompt):

/sbin/agetty --local-line 9600 ttyS1 vt100

For an old-style dial-in line with a 9600/2400/1200 baud modem:

/sbin/agetty --extract-baud --timeout 60 ttyS1 9600,2400,1200

For a Hayes modem with a fixed 115200 bps interface to the machine (the example init string turns off modem echo and result codes, makes modem/computer DCD track modem/modem DCD, makes a DTR drop cause a disconnection, and turns on auto-answer after 1 ring):

/sbin/agetty --wait-cr --init-string 'ATE0Q1&D2&C1S0=1\015' 115200 ttyS1

SECURITY NOTICE

If you use the --login-program and --login-options options, be aware that a malicious user may try to enter lognames with embedded options, which then get passed to the used login program. agetty does check for a leading "-" and makes sure the logname gets passed as one parameter (so embedded spaces will not create yet another parameter), but depending on how the login binary parses the command line that might not be sufficient. Check that the used login program cannot be abused this way.

Some programs use "--" to indicate that the rest of the command line should not be interpreted as options. Use this feature if available by passing "--" before the username gets passed by \u.

ISSUE FILES

The default issue file is /etc/issue. If the file exists, then agetty also checks for /etc/issue.d directory. The directory is optional extension to the default issue file and content of the directory is printed after /etc/issue content. If the /etc/issue does not exist, then the directory is ignored. All files with .issue extension from the directory are printed in version-sort order. The directory can be used to maintain 3rd-party messages independently on the primary system /etc/issue file.

Since version 2.35, additional locations for the issue file and directory are supported. agetty checks for the files /run/issue and /run/issue.d, and then for /usr/lib/issue and /usr/lib/issue.d. The directory /etc is expected for host-specific configuration, /run is expected for generated content, and /usr/lib is used for static configuration maintained by the distribution.

Note that in versions 2.35 to 2.40, the additional locations were only read if the default /etc/issue file did not exist. However, since version 2.41, the additional locations are always read, regardless of the existence of the /etc/issue file. This change allows for the generation of issue files by default.

The default paths maybe completely overridden by --issue-file option. In this case specified path has to be file or directory and all the default issue file and directory locations are ignored.

The issue file feature can be completely disabled by --noissue option.

It is possible to review the current issue file by agetty --show-issue on the current terminal.

The issue files may contain certain escape codes to display the system name, date, time et cetera. All escape codes consist of a backslash (\) immediately followed by one of the characters listed below.

4 or 4{interface}

6 or 6{interface}

e or e{name}

S or S{VARIABLE}

An example. On my system, the following /etc/issue file:

bash

This is \n.\o (\s \m \r) \t

displays as:

bash

This is thingol.orcan.dk (Linux i386 1.1.9) 18:29:30

FILES

/var/run/utmp

/etc/issue

/etc/os-release /usr/lib/os-release

/dev/console

/etc/inittab

CREDENTIALS

agetty supports configuration via systemd credentials (see <https://systemd.io/CREDENTIALS/>). agetty reads the following systemd credentials:

agetty.autologin (string)

BUGS

The baud-rate detection feature (the --extract-baud option) requires that agetty be scheduled soon enough after completion of a dial-in call (within 30 ms with modems that talk at 2400 baud). For robustness, always use the --extract-baud option in combination with a multiple baud rate command-line argument, so that BREAK processing is enabled.

The text in the /etc/issue file (or other) and the login prompt are always output with 7-bit characters and space parity.

The baud-rate detection feature (the --extract-baud option) requires that the modem emits its status message after raising the DCD line.

DIAGNOSTICS

Depending on how the program was configured, all diagnostics are written to the console device or reported via the syslog(3) facility. Error messages are produced if the port argument does not specify a terminal device; if there is no utmp entry for the current process (System V only); and so on.

NAME