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.
262 --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 --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 --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 --chdir directory
283 Change directory before the login.
284 --delay number
286 Sleep seconds before open tty.
287 --nice number
289 Run login with this priority.
290 --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 -h, --help
298 Display help text and exit.
299 -V, --version
301 Print version and exit.
302
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 For a hardwired line or a console tty:
309 /sbin/agetty 9600 ttyS1
311 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 /sbin/agetty --local-line 9600 ttyS1 vt100
317 For an old-style dial-in line with a 9600/2400/1200 baud modem:
319 /sbin/agetty --extract-baud --timeout 60 ttyS1 9600,2400,1200
321 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 /sbin/agetty --wait-cr --init-string 'ATE0Q1&D2&C1S0=1\015'
328 115200 ttyS1
329
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 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
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 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 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 The issue file feature can be completely disabled by --noissue option.
366 It is possible to review the current issue file by agetty --show-issue
368 on the current terminal.
369 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 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 6 or 6{interface}
382 The same as \4 but for IPv6.
383 b
385 Insert the baudrate of the current line.
386 d
388 Insert the current date.
389 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 s
400 Insert the system name (the name of the operating system). Same as
401 'uname -s'. See also the \S escape code.
402 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 l
412 Insert the name of the current tty line.
413 m
415 Insert the architecture identifier of the machine. Same as uname
416 -m.
417 n
419 Insert the nodename of the machine, also known as the hostname.
420 Same as uname -n.
421 o
423 Insert the NIS domainname of the machine. Same as hostname -d.
424 O
426 Insert the DNS domainname of the machine.
427 r
429 Insert the release number of the OS. Same as uname -r.
430 t
432 Insert the current time.
433 u
435 Insert the number of current users logged in.
436 U
438 Insert the string "1 user" or "<n> users" where <n> is the number
439 of current users logged in.
440 v
442 Insert the version of the OS, that is, the build-date and such.
443 An example. On my system, the following /etc/issue file:
445 This is \n.\o (\s \m \r) \t
447 displays as:
449 This is thingol.orcan.dk (Linux i386 1.1.9) 18:29:30
451
453 /var/run/utmp
454 the system status file.
455 /etc/issue
457 printed before the login prompt.
458 /etc/os-release /usr/lib/os-release
460 operating system identification data.
461 /dev/console
463 problem reports (if syslog(3) is not used).
464 /etc/inittab
466 init(8) configuration file for SysV-style init daemon.
467
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 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 The baud-rate detection feature (the --extract-baud option) requires
479 that the modem emits its status message after raising the DCD line.
480
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
489 Werner Fink <werner@suse.de>, Karel Zak <kzak@redhat.com>
490 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
496 For bug reports, use the issue tracker at
497 https://github.com/util-linux/util-linux/issues.
498
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/>.
503util-linux 2.38.1 2022-08-04 AGETTY(8)