1AGETTY(8)                    System Administration                   AGETTY(8)
2
3
4

NAME

6       agetty - alternative Linux getty
7

SYNOPSIS

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

DESCRIPTION

12       agetty opens a tty port, prompts for a login name and invokes the
13       /bin/login command. It is normally invoked by init(8).
14
15       agetty has several non-standard features that are useful for hardwired
16       and for dial-in lines:
17
18       •   Adapts the tty settings to parity bits and to erase, kill,
19           end-of-line and uppercase characters when it reads a login name.
20           The program can handle 7-bit characters with even, odd, none or
21           space parity, and 8-bit characters with no parity. The following
22           special characters are recognized: Control-U (kill); DEL and
23           backspace (erase); carriage return and line feed (end of line). See
24           also the --erase-chars and --kill-chars options.
25
26       •   Optionally deduces the baud rate from the CONNECT messages produced
27           by Hayes(tm)-compatible modems.
28
29       •   Optionally does not hang up when it is given an already opened line
30           (useful for call-back applications).
31
32       •   Optionally does not display the contents of the /etc/issue file.
33
34       •   Optionally displays an alternative issue files or directories
35           instead of /etc/issue or /etc/issue.d.
36
37       •   Optionally does not ask for a login name.
38
39       •   Optionally invokes a non-standard login program instead of
40           /bin/login.
41
42       •   Optionally turns on hardware flow control.
43
44       •   Optionally forces the line to be local with no need for carrier
45           detect.
46
47       This program does not use the /etc/gettydefs (System V) or
48       /etc/gettytab (SunOS 4) files.
49

ARGUMENTS

51       port
52           A path name relative to the /dev directory. If a "-" is specified,
53           agetty assumes that its standard input is already connected to a
54           tty port and that a connection to a remote user has already been
55           established.
56
57           Under System V, a "-" port argument should be preceded by a "--".
58
59       baud_rate,...
60           A comma-separated list of one or more baud rates. Each time agetty
61           receives a BREAK character it advances through the list, which is
62           treated as if it were circular.
63
64           Baud rates should be specified in descending order, so that the
65           null character (Ctrl-@) can also be used for baud-rate switching.
66
67           This argument is optional and unnecessary for virtual terminals.
68
69           The default for serial terminals is keep the current baud rate (see
70           --keep-baud) and if unsuccessful then default to '9600'.
71
72       term
73           The value to be used for the TERM environment variable. This
74           overrides whatever init(1) may have set, and is inherited by login
75           and the shell.
76
77           The default is 'vt100', or 'linux' for Linux on a virtual terminal,
78           or 'hurd' for GNU Hurd on a virtual terminal.
79

OPTIONS

81       -8, --8bits
82           Assume that the tty is 8-bit clean, hence disable parity detection.
83
84       -a, --autologin username
85           Automatically log in the specified user without asking for a
86           username or password. Using this option causes an -f username
87           option and argument to be added to the /bin/login command line. See
88           --login-options, which can be used to modify this option’s
89           behavior.
90
91           Note that --autologin may affect the way in which getty initializes
92           the serial line, because on auto-login agetty does not read from
93           the line and it has no opportunity optimize the line setting.
94
95       -c, --noreset
96           Do not reset terminal cflags (control modes). See termios(3) for
97           more details.
98
99       -E, --remote
100           Typically the login(1) command is given a remote hostname when
101           called by something such as telnetd(8). This option allows agetty
102           to pass what it is using for a hostname to login(1) for use in
103           utmp(5). See --host, login(1), and utmp(5).
104
105           If the --host fakehost option is given, then an -h fakehost option
106           and argument are added to the /bin/login command line.
107
108           If the --nohostname option is given, then an -H option is added to
109           the /bin/login command line.
110
111           See --login-options.
112
113       -f, --issue-file path
114           Specifies a ":" delimited list of files and directories to be
115           displayed instead of /etc/issue (or other). All specified files and
116           directories are displayed, missing or empty files are silently
117           ignored. If the specified path is a directory then display all
118           files with .issue file extension in version-sort order from the
119           directory. This allows custom messages to be displayed on different
120           terminals. The --noissue option will override this option.
121
122       --show-issue
123           Display the current issue file (or other) on the current terminal
124           and exit. Use this option to review the current setting, it is not
125           designed for any other purpose. Note that output may use some
126           default or incomplete information as proper output depends on
127           terminal and agetty command line.
128
129       -h, --flow-control
130           Enable hardware (RTS/CTS) flow control. It is left up to the
131           application to disable software (XON/XOFF) flow protocol where
132           appropriate.
133
134       -H, --host fakehost
135           Write the specified fakehost into the utmp file. Normally, no login
136           host is given, since agetty is used for local hardwired connections
137           and consoles. However, this option can be useful for identifying
138           terminal concentrators and the like.
139
140       -i, --noissue
141           Do not display the contents of /etc/issue (or other) before writing
142           the login prompt. Terminals or communications hardware may become
143           confused when receiving lots of text at the wrong baud rate;
144           dial-up scripts may fail if the login prompt is preceded by too
145           much text.
146
147       -I, --init-string initstring
148           Set an initial string to be sent to the tty or modem before sending
149           anything else. This may be used to initialize a modem.
150           Non-printable characters may be sent by writing their octal code
151           preceded by a backslash (\). For example, to send a linefeed
152           character (ASCII 10, octal 012), write \12.
153
154       -J, --noclear
155           Do not clear the screen before prompting for the login name. By
156           default the screen is cleared.
157
158       -l, --login-program login_program
159           Invoke the specified login_program instead of /bin/login. This
160           allows the use of a non-standard login program. Such a program
161           could, for example, ask for a dial-up password or use a different
162           password file. See --login-options.
163
164       -L, --local-line[=mode]
165           Control the CLOCAL line flag. The optional mode argument is auto,
166           always or never. If the mode argument is omitted, then the default
167           is always. If the --local-line option is not given at all, then the
168           default is auto.
169
170           always
171               Forces the line to be a local line with no need for carrier
172               detect. This can be useful when you have a locally attached
173               terminal where the serial line does not set the carrier-detect
174               signal.
175
176           never
177               Explicitly clears the CLOCAL flag from the line setting and the
178               carrier-detect signal is expected on the line.
179
180           auto
181               The agetty default. Does not modify the CLOCAL setting and
182               follows the setting enabled by the kernel.
183
184       -m, --extract-baud
185           Try to extract the baud rate from the CONNECT status message
186           produced by Hayes(tm)-compatible modems. These status messages are
187           of the form: "<junk><speed><junk>". agetty assumes that the modem
188           emits its status message at the same speed as specified with (the
189           first) baud_rate value on the command line.
190
191           Since the --extract-baud feature may fail on heavily-loaded
192           systems, you still should enable BREAK processing by enumerating
193           all expected baud rates on the command line.
194
195       --list-speeds
196           Display supported baud rates. These are determined at compilation
197           time.
198
199       -n, --skip-login
200           Do not prompt the user for a login name. This can be used in
201           connection with the --login-program option to invoke a non-standard
202           login process such as a BBS system. Note that with the --skip-login
203           option, agetty gets no input from the user who logs in and
204           therefore will not be able to figure out parity, character size,
205           and newline processing of the connection. It defaults to space
206           parity, 7 bit characters, and ASCII CR (13) end-of-line character.
207           Beware that the program that agetty starts (usually /bin/login) is
208           run as root.
209
210       -N, --nonewline
211           Do not print a newline before writing out /etc/issue.
212
213       -o, --login-options login_options
214           Options and arguments that are passed to login(1). Where \u is
215           replaced by the login name. For example:
216
217           --login-options '-h darkstar -- \u'
218
219           See --autologin, --login-program and --remote.
220
221           Please read the SECURITY NOTICE below before using this option.
222
223       -p, --login-pause
224           Wait for any key before dropping to the login prompt. Can be
225           combined with --autologin to save memory by lazily spawning shells.
226
227       -r, --chroot directory
228           Change root to the specified directory.
229
230       -R, --hangup
231           Call vhangup(2) to do a virtual hangup of the specified terminal.
232
233       -s, --keep-baud
234           Try to keep the existing baud rate. The baud rates from the command
235           line are used when agetty receives a BREAK character. If another
236           baud rates specified then the original baud rate is also saved to
237           the end of the wanted baud rates list. This can be used to return
238           to the original baud rate after unexpected BREAKs.
239
240       -t, --timeout timeout
241           Terminate if no user name could be read within timeout seconds. Use
242           of this option with hardwired terminal lines is not recommended.
243
244       -U, --detect-case
245           Turn on support for detecting an uppercase-only terminal. This
246           setting will detect a login name containing only capitals as
247           indicating an uppercase-only terminal and turn on some
248           upper-to-lower case conversions. Note that this has no support for
249           any Unicode characters.
250
251       -w, --wait-cr
252           Wait for the user or the modem to send a carriage-return or a
253           linefeed character before sending the /etc/issue file (or others)
254           and the login prompt. This is useful with the --init-string option.
255
256       --nohints
257           Do not print hints about Num, Caps and Scroll Locks.
258
259       --nohostname
260           By default the hostname will be printed. With this option enabled,
261           no hostname at all will be shown.
262
263       --long-hostname
264           By default the hostname is only printed until the first dot. With
265           this option enabled, the fully qualified hostname by
266           gethostname(3P) or (if not found) by getaddrinfo(3) is shown.
267
268       --erase-chars string
269           This option specifies additional characters that should be
270           interpreted as a backspace ("ignore the previous character") when
271           the user types the login name. The default additional 'erase' has
272           been '#', but since util-linux 2.23 no additional erase characters
273           are enabled by default.
274
275       --kill-chars string
276           This option specifies additional characters that should be
277           interpreted as a kill ("ignore all previous characters") when the
278           user types the login name. The default additional 'kill' has been
279           '@', but since util-linux 2.23 no additional kill characters are
280           enabled by default.
281
282       --chdir directory
283           Change directory before the login.
284
285       --delay number
286           Sleep seconds before open tty.
287
288       --nice number
289           Run login with this priority.
290
291       --reload
292           Ask all running agetty instances to reload and update their
293           displayed prompts, if the user has not yet commenced logging in.
294           After doing so the command will exit. This feature might be
295           unsupported on systems without Linux inotify(7).
296
297       -h, --help
298           Display help text and exit.
299
300       -V, --version
301           Print version and exit.
302

EXAMPLE

304       This section shows examples for the process field of an entry in the
305       /etc/inittab file. You’ll have to prepend appropriate values for the
306       other fields. See inittab(5) for more details.
307
308       For a hardwired line or a console tty:
309
310          /sbin/agetty 9600 ttyS1
311
312       For a directly connected terminal without proper carrier-detect wiring
313       (try this if your terminal just sleeps instead of giving you a
314       password: prompt):
315
316          /sbin/agetty --local-line 9600 ttyS1 vt100
317
318       For an old-style dial-in line with a 9600/2400/1200 baud modem:
319
320          /sbin/agetty --extract-baud --timeout 60 ttyS1 9600,2400,1200
321
322       For a Hayes modem with a fixed 115200 bps interface to the machine (the
323       example init string turns off modem echo and result codes, makes
324       modem/computer DCD track modem/modem DCD, makes a DTR drop cause a
325       disconnection, and turns on auto-answer after 1 ring):
326
327          /sbin/agetty --wait-cr --init-string 'ATE0Q1&D2&C1S0=1\015'
328          115200 ttyS1
329

SECURITY NOTICE

331       If you use the --login-program and --login-options options, be aware
332       that a malicious user may try to enter lognames with embedded options,
333       which then get passed to the used login program. agetty does check for
334       a leading "-" and makes sure the logname gets passed as one parameter
335       (so embedded spaces will not create yet another parameter), but
336       depending on how the login binary parses the command line that might
337       not be sufficient. Check that the used login program cannot be abused
338       this way.
339
340       Some programs use "--" to indicate that the rest of the command line
341       should not be interpreted as options. Use this feature if available by
342       passing "--" before the username gets passed by \u.
343

ISSUE FILES

345       The default issue file is /etc/issue. If the file exists, then agetty
346       also checks for /etc/issue.d directory. The directory is optional
347       extension to the default issue file and content of the directory is
348       printed after /etc/issue content. If the /etc/issue does not exist,
349       then the directory is ignored. All files with .issue extension from the
350       directory are printed in version-sort order. The directory can be used
351       to maintain 3rd-party messages independently on the primary system
352       /etc/issue file.
353
354       Since version 2.35 additional locations for issue file and directory
355       are supported. If the default /etc/issue does not exist, then agetty
356       checks for /run/issue and /run/issue.d, thereafter for /usr/lib/issue
357       and /usr/lib/issue.d. The directory /etc is expected for host specific
358       configuration, /run is expected for generated stuff and /usr/lib for
359       static distribution maintained configuration.
360
361       The default path maybe overridden by --issue-file option. In this case
362       specified path has to be file or directory and all the default issue
363       file and directory locations are ignored.
364
365       The issue file feature can be completely disabled by --noissue option.
366
367       It is possible to review the current issue file by agetty --show-issue
368       on the current terminal.
369
370       The issue files may contain certain escape codes to display the system
371       name, date, time et cetera. All escape codes consist of a backslash (\)
372       immediately followed by one of the characters listed below.
373
374       4 or 4{interface}
375           Insert the IPv4 address of the specified network interface (for
376           example: \4{eth0}). If the interface argument is not specified,
377           then select the first fully configured (UP, non-LOCALBACK, RUNNING)
378           interface. If no configured interface is found, fall back to the IP
379           address of the machine’s hostname.
380
381       6 or 6{interface}
382           The same as \4 but for IPv6.
383
384       b
385           Insert the baudrate of the current line.
386
387       d
388           Insert the current date.
389
390       e or e{name}
391           Translate the human-readable name to an escape sequence and insert
392           it (for example: \e{red}Alert text.\e{reset}). If the name argument
393           is not specified, then insert \033. The currently supported names
394           are: black, blink, blue, bold, brown, cyan, darkgray, gray, green,
395           halfbright, lightblue, lightcyan, lightgray, lightgreen,
396           lightmagenta, lightred, magenta, red, reset, reverse, yellow and
397           white. All unknown names are silently ignored.
398
399       s
400           Insert the system name (the name of the operating system). Same as
401           'uname -s'. See also the \S escape code.
402
403       S or S{VARIABLE}
404           Insert the VARIABLE data from /etc/os-release. If this file does
405           not exist then fall back to /usr/lib/os-release. If the VARIABLE
406           argument is not specified, then use PRETTY_NAME from the file or
407           the system name (see \s). This escape code can be used to keep
408           /etc/issue distribution and release independent. Note that
409           \S{ANSI_COLOR} is converted to the real terminal escape sequence.
410
411       l
412           Insert the name of the current tty line.
413
414       m
415           Insert the architecture identifier of the machine. Same as uname
416           -m.
417
418       n
419           Insert the nodename of the machine, also known as the hostname.
420           Same as uname -n.
421
422       o
423           Insert the NIS domainname of the machine. Same as hostname -d.
424
425       O
426           Insert the DNS domainname of the machine.
427
428       r
429           Insert the release number of the OS. Same as uname -r.
430
431       t
432           Insert the current time.
433
434       u
435           Insert the number of current users logged in.
436
437       U
438           Insert the string "1 user" or "<n> users" where <n> is the number
439           of current users logged in.
440
441       v
442           Insert the version of the OS, that is, the build-date and such.
443
444       An example. On my system, the following /etc/issue file:
445
446           This is \n.\o (\s \m \r) \t
447
448       displays as:
449
450           This is thingol.orcan.dk (Linux i386 1.1.9) 18:29:30
451

FILES

453       /var/run/utmp
454           the system status file.
455
456       /etc/issue
457           printed before the login prompt.
458
459       /etc/os-release /usr/lib/os-release
460           operating system identification data.
461
462       /dev/console
463           problem reports (if syslog(3) is not used).
464
465       /etc/inittab
466           init(8) configuration file for SysV-style init daemon.
467

BUGS

469       The baud-rate detection feature (the --extract-baud option) requires
470       that agetty be scheduled soon enough after completion of a dial-in call
471       (within 30 ms with modems that talk at 2400 baud). For robustness,
472       always use the --extract-baud option in combination with a multiple
473       baud rate command-line argument, so that BREAK processing is enabled.
474
475       The text in the /etc/issue file (or other) and the login prompt are
476       always output with 7-bit characters and space parity.
477
478       The baud-rate detection feature (the --extract-baud option) requires
479       that the modem emits its status message after raising the DCD line.
480

DIAGNOSTICS

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

AUTHORS

489       Werner Fink <werner@suse.de>, Karel Zak <kzak@redhat.com>
490
491       The original agetty for serial terminals was written by W.Z. Venema
492       <wietse@wzv.win.tue.nl> and ported to Linux by Peter Orbaek
493       <poe@daimi.aau.dk>.
494

REPORTING BUGS

496       For bug reports, use the issue tracker at
497       https://github.com/util-linux/util-linux/issues.
498

AVAILABILITY

500       The agetty command is part of the util-linux package which can be
501       downloaded from Linux Kernel Archive
502       <https://www.kernel.org/pub/linux/utils/util-linux/>.
503
504
505
506util-linux 2.38.1                 2022-08-04                         AGETTY(8)
Impressum