1AGETTY(8) System Administration AGETTY(8)
2
6 agetty - alternative Linux getty
7
9 agetty [options] port [baud_rate...] [term]
10
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 agetty has several non-standard features that are useful for hardwired
16 and for dial-in lines:
17 • 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 • Optionally deduces the baud rate from the CONNECT messages produced
27 by Hayes(tm)-compatible modems.
28 • Optionally does not hang up when it is given an already opened line
30 (useful for call-back applications).
31 • Optionally does not display the contents of the /etc/issue file.
33 • Optionally displays an alternative issue files or directories
35 instead of /etc/issue or /etc/issue.d.
36 • Optionally does not ask for a login name.
38 • Optionally invokes a non-standard login program instead of
40 /bin/login.
41 • Optionally turns on hardware flow control.
43 • Optionally forces the line to be local with no need for carrier
45 detect.
46 This program does not use the /etc/gettydefs (System V) or
48 /etc/gettytab (SunOS 4) files.
49
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 Under System V, a "-" port argument should be preceded by a "--".
58 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 Baud rates should be specified in descending order, so that the
65 null character (Ctrl-@) can also be used for baud-rate switching.
66 This argument is optional and unnecessary for virtual terminals.
68 The default for serial terminals is keep the current baud rate (see
70 --keep-baud) and if unsuccessful then default to '9600'.
71 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 The default is 'vt100', or 'linux' for Linux on a virtual terminal,
78 or 'hurd' for GNU Hurd on a virtual terminal.
79
81 -8, --8bits
82 Assume that the tty is 8-bit clean, hence disable parity detection.
83 -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 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 -c, --noreset
96 Do not reset terminal cflags (control modes). See termios(3) for
97 more details.
98 -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 If the --host fakehost option is given, then an -h fakehost option
106 and argument are added to the /bin/login command line.
107 If the --nohostname option is given, then an -H option is added to
109 the /bin/login command line.
110 See --login-options.
112 -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 --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 -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 -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 -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 -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 -J, --noclear
155 Do not clear the screen before prompting for the login name. By
156 default the screen is cleared.
157 -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 -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 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 never
177 Explicitly clears the CLOCAL flag from the line setting and the
178 carrier-detect signal is expected on the line.
179 auto
181 The agetty default. Does not modify the CLOCAL setting and
182 follows the setting enabled by the kernel.
183 -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 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 --list-speeds
196 Display supported baud rates. These are determined at compilation
197 time.
198 -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 -N, --nonewline
211 Do not print a newline before writing out /etc/issue.
212 -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 --login-options '-h darkstar -- \u'
218 See --autologin, --login-program and --remote.
220 Please read the SECURITY NOTICE below before using this option.
222 -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 -r, --chroot directory
228 Change root to the specified directory.
229 -R, --hangup
231 Call vhangup(2) to do a virtual hangup of the specified terminal.
232 -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 -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 -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 -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 --nohints
257 Do not print hints about Num, Caps and Scroll Locks.
258 --nohostname
260 By default the hostname will be printed. With this option enabled,
261 no hostname at all will be shown. This setting is also possible to
262 able by LOGIN_PLAIN_PROMPT option in the /etc/login.defs
263 configuration file (see below for more details).
264 --long-hostname
266 By default the hostname is only printed until the first dot. With
267 this option enabled, the fully qualified hostname by
268 gethostname(3P) or (if not found) by getaddrinfo(3) is shown.
269 --erase-chars string
271 This option specifies additional characters that should be
272 interpreted as a backspace ("ignore the previous character") when
273 the user types the login name. The default additional 'erase' has
274 been '#', but since util-linux 2.23 no additional erase characters
275 are enabled by default.
276 --kill-chars string
278 This option specifies additional characters that should be
279 interpreted as a kill ("ignore all previous characters") when the
280 user types the login name. The default additional 'kill' has been
281 '@', but since util-linux 2.23 no additional kill characters are
282 enabled by default.
283 --chdir directory
285 Change directory before the login.
286 --delay number
288 Sleep seconds before open tty.
289 --nice number
291 Run login with this priority.
292 --reload
294 Ask all running agetty instances to reload and update their
295 displayed prompts, if the user has not yet commenced logging in.
296 After doing so the command will exit. This feature might be
297 unsupported on systems without Linux inotify(7).
298 -h, --help
300 Display help text and exit.
301 -V, --version
303 Print version and exit.
304
306 agetty reads the /etc/login.defs configuration file (see
307 login.defs(5)). Note that the configuration file could be distributed
308 with another package (usually shadow-utils). The following
309 configuration items are relevant for agetty:
310 LOGIN_PLAIN_PROMPT (boolean)
312 Tell agetty that printing the hostname should be suppressed in the
313 login: prompt. This is an alternative to the --nohostname command
314 line option. The default value is no.
315
317 This section shows examples for the process field of an entry in the
318 /etc/inittab file. You’ll have to prepend appropriate values for the
319 other fields. See inittab(5) for more details.
320 For a hardwired line or a console tty:
322 /sbin/agetty 9600 ttyS1
324 For a directly connected terminal without proper carrier-detect wiring
326 (try this if your terminal just sleeps instead of giving you a
327 password: prompt):
328 /sbin/agetty --local-line 9600 ttyS1 vt100
330 For an old-style dial-in line with a 9600/2400/1200 baud modem:
332 /sbin/agetty --extract-baud --timeout 60 ttyS1 9600,2400,1200
334 For a Hayes modem with a fixed 115200 bps interface to the machine (the
336 example init string turns off modem echo and result codes, makes
337 modem/computer DCD track modem/modem DCD, makes a DTR drop cause a
338 disconnection, and turns on auto-answer after 1 ring):
339 /sbin/agetty --wait-cr --init-string 'ATE0Q1&D2&C1S0=1\015'
341 115200 ttyS1
342
344 If you use the --login-program and --login-options options, be aware
345 that a malicious user may try to enter lognames with embedded options,
346 which then get passed to the used login program. agetty does check for
347 a leading "-" and makes sure the logname gets passed as one parameter
348 (so embedded spaces will not create yet another parameter), but
349 depending on how the login binary parses the command line that might
350 not be sufficient. Check that the used login program cannot be abused
351 this way.
352 Some programs use "--" to indicate that the rest of the command line
354 should not be interpreted as options. Use this feature if available by
355 passing "--" before the username gets passed by \u.
356
358 The default issue file is /etc/issue. If the file exists, then agetty
359 also checks for /etc/issue.d directory. The directory is optional
360 extension to the default issue file and content of the directory is
361 printed after /etc/issue content. If the /etc/issue does not exist,
362 then the directory is ignored. All files with .issue extension from the
363 directory are printed in version-sort order. The directory can be used
364 to maintain 3rd-party messages independently on the primary system
365 /etc/issue file.
366 Since version 2.35 additional locations for issue file and directory
368 are supported. If the default /etc/issue does not exist, then agetty
369 checks for /run/issue and /run/issue.d, thereafter for /usr/lib/issue
370 and /usr/lib/issue.d. The directory /etc is expected for host specific
371 configuration, /run is expected for generated stuff and /usr/lib for
372 static distribution maintained configuration.
373 The default path maybe overridden by --issue-file option. In this case
375 specified path has to be file or directory and all the default issue
376 file and directory locations are ignored.
377 The issue file feature can be completely disabled by --noissue option.
379 It is possible to review the current issue file by agetty --show-issue
381 on the current terminal.
382 The issue files may contain certain escape codes to display the system
384 name, date, time et cetera. All escape codes consist of a backslash (\)
385 immediately followed by one of the characters listed below.
386 4 or 4{interface}
388 Insert the IPv4 address of the specified network interface (for
389 example: \4{eth0}). If the interface argument is not specified,
390 then select the first fully configured (UP, non-LOCALBACK, RUNNING)
391 interface. If no configured interface is found, fall back to the IP
392 address of the machine’s hostname.
393 6 or 6{interface}
395 The same as \4 but for IPv6.
396 b
398 Insert the baudrate of the current line.
399 d
401 Insert the current date.
402 e or e{name}
404 Translate the human-readable name to an escape sequence and insert
405 it (for example: \e{red}Alert text.\e{reset}). If the name argument
406 is not specified, then insert \033. The currently supported names
407 are: black, blink, blue, bold, brown, cyan, darkgray, gray, green,
408 halfbright, lightblue, lightcyan, lightgray, lightgreen,
409 lightmagenta, lightred, magenta, red, reset, reverse, yellow and
410 white. All unknown names are silently ignored.
411 s
413 Insert the system name (the name of the operating system). Same as
414 'uname -s'. See also the \S escape code.
415 S or S{VARIABLE}
417 Insert the VARIABLE data from /etc/os-release. If this file does
418 not exist then fall back to /usr/lib/os-release. If the VARIABLE
419 argument is not specified, then use PRETTY_NAME from the file or
420 the system name (see \s). This escape code can be used to keep
421 /etc/issue distribution and release independent. Note that
422 \S{ANSI_COLOR} is converted to the real terminal escape sequence.
423 l
425 Insert the name of the current tty line.
426 m
428 Insert the architecture identifier of the machine. Same as uname
429 -m.
430 n
432 Insert the nodename of the machine, also known as the hostname.
433 Same as uname -n.
434 o
436 Insert the NIS domainname of the machine. Same as hostname -d.
437 O
439 Insert the DNS domainname of the machine.
440 r
442 Insert the release number of the OS. Same as uname -r.
443 t
445 Insert the current time.
446 u
448 Insert the number of current users logged in.
449 U
451 Insert the string "1 user" or "<n> users" where <n> is the number
452 of current users logged in.
453 v
455 Insert the version of the OS, that is, the build-date and such.
456 An example. On my system, the following /etc/issue file:
458 This is \n.\o (\s \m \r) \t
460 displays as:
462 This is thingol.orcan.dk (Linux i386 1.1.9) 18:29:30
464
466 /var/run/utmp
467 the system status file.
468 /etc/issue
470 printed before the login prompt.
471 /etc/os-release /usr/lib/os-release
473 operating system identification data.
474 /dev/console
476 problem reports (if syslog(3) is not used).
477 /etc/inittab
479 init(8) configuration file for SysV-style init daemon.
480
482 The baud-rate detection feature (the --extract-baud option) requires
483 that agetty be scheduled soon enough after completion of a dial-in call
484 (within 30 ms with modems that talk at 2400 baud). For robustness,
485 always use the --extract-baud option in combination with a multiple
486 baud rate command-line argument, so that BREAK processing is enabled.
487 The text in the /etc/issue file (or other) and the login prompt are
489 always output with 7-bit characters and space parity.
490 The baud-rate detection feature (the --extract-baud option) requires
492 that the modem emits its status message after raising the DCD line.
493
495 Depending on how the program was configured, all diagnostics are
496 written to the console device or reported via the syslog(3) facility.
497 Error messages are produced if the port argument does not specify a
498 terminal device; if there is no utmp entry for the current process
499 (System V only); and so on.
500
502 Werner Fink <werner@suse.de>, Karel Zak <kzak@redhat.com>
503 The original agetty for serial terminals was written by W.Z. Venema
505 <wietse@wzv.win.tue.nl> and ported to Linux by Peter Orbaek
506 <poe@daimi.aau.dk>.
507
509 For bug reports, use the issue tracker at
510 https://github.com/util-linux/util-linux/issues.
511
513 The agetty command is part of the util-linux package which can be
514 downloaded from Linux Kernel Archive
515 <https://www.kernel.org/pub/linux/utils/util-linux/>.
516util-linux 2.39.2 2023-08-17 AGETTY(8)