1 .TH AGETTY 8 "February 2016" "util-linux" "System Administration"
3 agetty \- alternative Linux getty
8 .IR port " [" baud_rate "...] [" term ]
13 \fBagetty\fP opens a tty port, prompts for a login name and invokes
14 the /bin/login command. It is normally invoked by \fBinit\fP(8).
16 \fBagetty\fP has several \fInon-standard\fP features that are useful
17 for hardwired and for dial-in lines:
19 Adapts the tty settings to parity bits and to erase, kill,
20 end-of-line and uppercase characters when it reads a login name.
21 The program can handle 7-bit characters with even, odd, none or space
22 parity, and 8-bit characters with no parity. The following special
23 characters are recognized: Control-U (kill); DEL and
24 backspace (erase); carriage return and line feed (end of line).
25 See also the \fB\-\-erase\-chars\fP and \fB\-\-kill\-chars\fP options.
27 Optionally deduces the baud rate from the CONNECT messages produced by
28 Hayes(tm)-compatible modems.
30 Optionally does not hang up when it is given an already opened line
31 (useful for call-back applications).
33 Optionally does not display the contents of the \fI/etc/issue\fP file.
35 Optionally displays an alternative issue file or directory instead of \fI/etc/issue\fP or \fI/etc/issue.d\fP.
37 Optionally does not ask for a login name.
39 Optionally invokes a non-standard login program instead of
42 Optionally turns on hardware flow control.
44 Optionally forces the line to be local with no need for carrier detect.
46 This program does not use the \fI/etc/gettydefs\fP (System V) or
47 \fI/etc/gettytab\fP (SunOS 4) files.
55 A path name relative to the \fI/dev\fP directory. If a "\-" is
56 specified, \fBagetty\fP assumes that its standard input is
57 already connected to a tty port and that a connection to a
58 remote user has already been established.
60 Under System V, a "\-" \fIport\fP argument should be preceded
64 A comma-separated list of one or more baud rates. Each time
65 \fBagetty\fP receives a BREAK character it advances through
66 the list, which is treated as if it were circular.
68 Baud rates should be specified in descending order, so that the
69 null character (Ctrl\-@) can also be used for baud-rate switching.
71 This argument is optional and unnecessary for \fBvirtual terminals\fP.
73 The default for \fBserial terminals\fP is keep the current baud rate
74 (see \fB\-\-keep\-baud\fP) and if unsuccessful then default to '9600'.
77 The value to be used for the TERM environment variable. This overrides
78 whatever init(8) may have set, and is inherited by login and the shell.
80 The default is 'vt100', or 'linux' for Linux on a virtual terminal,
81 or 'hurd' for GNU Hurd on a virtual terminal.
89 Assume that the tty is 8-bit clean, hence disable parity detection.
91 \-a, \-\-autologin \fIusername\fP
92 Automatically log in the specified user without asking for a username or password.
93 Using this option causes an \fB\-f \fIusername\fR option and argument to be
94 added to the \fB/bin/login\fP command line. See \fB\-\-login\-options\fR, which
95 can be used to modify this option's behavior.
97 Note that \fB\-\-autologin\fP may affect the way how agetty initializes the
98 serial line, because on auto-login agetty does not read from the line and it
99 has no opportunity optimize the line setting.
102 Do not reset terminal cflags (control modes). See \fBtermios\fP(3) for more
106 Typically the \fBlogin\fP(1) command is given a remote hostname when
107 called by something such as \fBtelnetd\fP(8). This option allows \fBagetty\fP
108 to pass what it is using for a hostname to \fBlogin\fP(1) for use
109 in \fButmp\fP(5). See \fB\-\-host\fP, \fBlogin\fP(1), and \fButmp\fP(5).
111 If the \fB\-\-host\fP \fIfakehost\fP option is given, then an \fB\-h\fP
112 \fIfakehost\fP option and argument are added to the \fB/bin/login\fP
115 If the \fB\-\-nohostname\fR option is given, then an \fB\-H\fP option
116 is added to the \fB/bin/login\fP command line.
118 See \fB\-\-login\-options\fR.
120 \-f, \-\-issue\-file \fIfile|directory\fP
121 Display the contents of \fIfile\fP instead of \fI/etc/issue\fP. If the
122 specified path is a \fIdirectory\fP then displays all files with .issue file
123 extension in version-sort order from the directory. This allows custom
124 messages to be displayed on different terminals. The
125 \-\-noissue option will override this option.
127 \-h, \-\-flow\-control
128 Enable hardware (RTS/CTS) flow control. It is left up to the
129 application to disable software (XON/XOFF) flow protocol where
132 \-H, \-\-host \fIfakehost\fP
133 Write the specified \fIfakehost\fP into the utmp file. Normally,
134 no login host is given, since \fBagetty\fP is used for local hardwired
135 connections and consoles. However, this option can be useful for
136 identifying terminal concentrators and the like.
139 Do not display the contents of \fI/etc/issue\fP (or other) before writing the
140 login prompt. Terminals or communications hardware may become confused
141 when receiving lots of text at the wrong baud rate; dial-up scripts
142 may fail if the login prompt is preceded by too much text.
144 \-I, \-\-init\-string \fIinitstring\fP
145 Set an initial string to be sent to the tty or modem before sending
146 anything else. This may be used to initialize a modem. Non-printable
147 characters may be sent by writing their octal code preceded by a
148 backslash (\\). For example, to send a linefeed character (ASCII 10,
149 octal 012), write \\012.
152 Do not clear the screen before prompting for the login name.
153 By default the screen is cleared.
155 \-l, \-\-login\-program \fIlogin_program\fP
156 Invoke the specified \fIlogin_program\fP instead of /bin/login. This allows
157 the use of a non-standard login program. Such a program could, for example,
158 ask for a dial-up password or use a different password file. See
159 \fB\-\-login\-options\fP.
161 \-L, \-\-local\-line[=\fImode\fP]
162 Control the CLOCAL line flag. The optional \fImode\fP argument is 'auto', 'always' or 'never'.
163 If the \fImode\fP argument is omitted, then the default is 'always'. If the
164 \-\-local\-line option is not given at all, then the default is 'auto'.
170 Forces the line to be a local line with no need for carrier detect. This
171 can be useful when you have a locally attached terminal where the serial
172 line does not set the carrier-detect signal.
175 Explicitly clears the CLOCAL flag from the line setting and the
176 carrier-detect signal is expected on the line.
179 The \fBagetty\fR default. Does not modify the CLOCAL setting and follows
180 the setting enabled by the kernel.
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
187 messages are of the form: "<junk><speed><junk>".
188 \fBagetty\fP assumes that the modem emits its status message at
189 the same speed as specified with (the first) \fIbaud_rate\fP value
192 Since the \fB\-\-extract\-baud\fP feature may fail on heavily-loaded
193 systems, you still should enable BREAK processing by enumerating all
194 expected baud rates on the command line.
197 Display supported baud rates. These are determined at compilation time.
200 Do not prompt the user for a login name. This can be used in connection
201 with the \fB\-\-login\-program\fP option to invoke a non-standard login
202 process such as a BBS system. Note that with the \fB\-\-skip\-login\fR
203 option, \fBagetty\fR gets no input from the user who logs in and therefore
204 will not be able to figure out parity, character size, and newline
205 processing of the connection. It defaults to space parity, 7 bit
206 characters, and ASCII CR (13) end-of-line character. Beware that the
207 program that \fBagetty\fR starts (usually /bin/login) is run as root.
210 Do not print a newline before writing out /etc/issue.
212 \-o, \-\-login\-options "\fIlogin_options\fP"
213 Options and arguments that are passed to \fBlogin\fP(1). Where \\u is
214 replaced by the login name. For example:
217 .B "\-\-login\-options '-h darkstar -- \\\u'"
219 See \fB\-\-autologin\fR, \fB\-\-login\-program\fR and \fB\-\-remote\fR.
221 Please read the SECURITY NOTICE below before using this option.
224 \-p, \-\-login\-pause
225 Wait for any key before dropping to the login prompt. Can be combined
226 with \fB\-\-autologin\fP to save memory by lazily spawning shells.
228 \-r, \-\-chroot \fIdirectory\fP
229 Change root to the specified directory.
232 Call vhangup() to do a virtual hangup of the specified terminal.
235 Try to keep the existing baud rate. The baud rates from
236 the command line are used when agetty receives a BREAK character.
238 \-t, \-\-timeout \fItimeout\fP
239 Terminate if no user name could be read within \fItimeout\fP seconds.
240 Use of this option with hardwired terminal lines is not recommended.
242 \-U, \-\-detect\-case
243 Turn on support for detecting an uppercase-only terminal. This setting
244 will detect a login name containing only capitals as indicating an
245 uppercase-only terminal and turn on some upper-to-lower case conversions.
246 Note that this has no support for any Unicode characters.
249 Wait for the user or the modem to send a carriage-return or a
250 linefeed character before sending the \fI/etc/issue\fP file (or others)
251 and the login prompt. This is useful with the \fB\-\-init\-string\fP
255 Do not print hints about Num, Caps and Scroll Locks.
258 By default the hostname will be printed. With this option enabled,
259 no hostname at all will be shown.
262 By default the hostname is only printed until the first dot. With
263 this option enabled, the fully qualified hostname by \fBgethostname\fR(3P)
264 or (if not found) by \fBgetaddrinfo\fR(3) is shown.
266 \-\-erase\-chars \fIstring\fP
267 This option specifies additional characters that should be interpreted as a
268 backspace ("ignore the previous character") when the user types the login name.
269 The default additional \'erase\' has been \'#\', but since util-linux 2.23
270 no additional erase characters are enabled by default.
272 \-\-kill\-chars \fIstring\fP
273 This option specifies additional characters that should be interpreted as a
274 kill ("ignore all previous characters") when the user types the login name.
275 The default additional \'kill\' has been \'@\', but since util-linux 2.23
276 no additional kill characters are enabled by default.
278 \-\-chdir \fIdirectory\fP
279 Change directory before the login.
281 \-\-delay \fInumber\fP
282 Sleep seconds before open tty.
284 \-\-nice \fInumber\fP
285 Run login with this priority.
288 Ask all running agetty instances to reload and update their displayed prompts,
289 if the user has not yet commenced logging in. After doing so the command will
290 exit. This feature might be unsupported on systems without Linux
294 Display version information and exit.
297 Display help text and exit.
300 This section shows examples for the process field of an entry in the
301 \fI/etc/inittab\fP file. You'll have to prepend appropriate values
302 for the other fields. See \fIinittab(5)\fP for more details.
304 For a hardwired line or a console tty:
307 .B /sbin/agetty\ 9600\ ttyS1
310 For a directly connected terminal without proper carrier-detect wiring
311 (try this if your terminal just sleeps instead of giving you a password:
315 .B /sbin/agetty\ \-\-local\-line\ 9600\ ttyS1\ vt100
318 For an old-style dial-in line with a 9600/2400/1200 baud modem:
321 .B /sbin/agetty\ \-\-extract\-baud\ \-\-timeout\ 60\ ttyS1\ 9600,2400,1200
324 For a Hayes modem with a fixed 115200 bps interface to the machine
325 (the example init string turns off modem echo and result codes, makes
326 modem/computer DCD track modem/modem DCD, makes a DTR drop cause a
327 disconnection, and turns on auto-answer after 1 ring):
331 .B /sbin/agetty\ \-\-wait\-cr\ \-\-init\-string\ 'ATE0Q1&D2&C1S0=1\\015'\ 115200\ ttyS1
335 If you use the \fB\-\-login\-program\fP and \fB\-\-login\-options\fP options,
336 be aware that a malicious user may try to enter lognames with embedded options,
337 which then get passed to the used login program. Agetty does check
338 for a leading "\-" and makes sure the logname gets passed as one parameter
339 (so embedded spaces will not create yet another parameter), but depending
340 on how the login binary parses the command line that might not be sufficient.
341 Check that the used login program cannot be abused this way.
343 Some programs use "\-\-" to indicate that the rest of the commandline should
344 not be interpreted as options. Use this feature if available by passing "\-\-"
345 before the username gets passed by \\u.
348 The default issue file is \fI/etc/issue\fP. If the file exists then agetty also
349 checks for \fI/etc/issue.d\fP directory. The directory is optional extension to
350 the default issue file and content of the directory is printed after
351 \fI/etc/issue\fP content. If the \fI/etc/issue\fP does not exist than the
352 directory is ignored. All files with .issue extension from the directory are
353 printed in version-sort order. The directory allow to maintain 3rd-party
354 messages independently on the primary system \fI/etc/issue\fP file.
356 The default path maybe overridden by \fB\-\-issue\-file\fP option. In this case
357 specified path has to be file or directory and the default \fI/etc/issue\fP as
358 well as \fI/etc/issue.d\fP are ignored.
360 The issue files may contain certain escape codes to display the system name, date, time
361 etcetera. All escape codes consist of a backslash (\\) immediately
362 followed by one of the characters listed below.
365 4 or 4{\fIinterface\fR}
366 Insert the IPv4 address of the specified network interface (for example: \\4{eth0}).
367 If the \fIinterface\fR argument is not specified, then select the first fully
368 configured (UP, non-LOCALBACK, RUNNING) interface. If not any configured
369 interface is found, fall back to the IP address of the machine's hostname.
371 6 or 6{\fIinterface\fR}
372 The same as \\4 but for IPv6.
375 Insert the baudrate of the current line.
378 Insert the current date.
381 Translate the human-readable \fIname\fP to an escape sequence and insert it
382 (for example: \\e{red}Alert text.\\e{reset}). If the \fIname\fR argument is
383 not specified, then insert \\033. The currently supported names are: black,
384 blink, blue, bold, brown, cyan,
385 darkgray, gray, green, halfbright, lightblue, lightcyan, lightgray, lightgreen,
386 lightmagenta, lightred, magenta, red, reset, reverse, and yellow. All unknown
387 names are silently ignored.
390 Insert the system name (the name of the operating system). Same as 'uname \-s'.
391 See also the \\S escape code.
394 Insert the VARIABLE data from \fI/etc/os-release\fP. If this file does not exist
395 then fall back to \fI/usr/lib/os-release\fP. If the VARIABLE argument is not
396 specified, then use PRETTY_NAME from the file or the system name (see \\s).
397 This escape code allows to keep \fI/etc/issue\fP distribution and release
398 independent. Note that \\S{ANSI_COLOR} is converted to the real terminal
402 Insert the name of the current tty line.
405 Insert the architecture identifier of the machine. Same as 'uname \-m'.
408 Insert the nodename of the machine, also known as the hostname. Same as 'uname \-n'.
411 Insert the NIS domainname of the machine. Same as 'hostname \-d'.
414 Insert the DNS domainname of the machine.
417 Insert the release number of the OS. Same as 'uname \-r'.
420 Insert the current time.
423 Insert the number of current users logged in.
426 Insert the string "1 user" or "<n> users" where <n> is the number of current
430 Insert the version of the OS, that is, the build-date and such.
432 An example. On my system, the following \fI/etc/issue\fP file:
437 This is \\n.\\o (\\s \\m \\r) \\t
445 This is thingol.orcan.dk (Linux i386 1.1.9) 18:29:30
453 the system status file.
456 printed before the login prompt.
458 .I /etc/os-release /usr/lib/os-release
459 operating system identification data.
462 problem reports (if syslog(3) is not used).
465 \fIinit\fP(8) configuration file for SysV-style init daemon.
469 The baud-rate detection feature (the \fB\-\-extract\-baud\fP option) requires that
470 \fBagetty\fP be scheduled soon enough after completion of a dial-in
471 call (within 30 ms with modems that talk at 2400 baud). For robustness,
472 always use the \fB\-\-extract\-baud\fP option in combination with a multiple baud
473 rate command-line argument, so that BREAK processing is enabled.
475 The text in the \fI/etc/issue\fP file (or other) and the login prompt
476 are always output with 7-bit characters and space parity.
478 The baud-rate detection feature (the \fB\-\-extract\-baud\fP option) requires that
479 the modem emits its status message \fIafter\fP raising the DCD line.
483 Depending on how the program was configured, all diagnostics are
484 written to the console device or reported via the \fBsyslog\fR(3) facility.
485 Error messages are produced if the \fIport\fP argument does not
486 specify a terminal device; if there is no utmp entry for the
487 current process (System V only); and so on.
499 for serial terminals was written by W.Z. Venema <wietse@wzv.win.tue.nl>
500 and ported to Linux by Peter Orbaek <poe@daimi.aau.dk>.
503 The agetty command is part of the util-linux package and is available from
504 https://www.kernel.org/pub/linux/utils/util\-linux/.
OSDN Git Service
