| .TH AGETTY 8 "February 2016" "util-linux" "System Administration" |
| .SH NAME |
| agetty \- alternative Linux getty |
| |
| .SH SYNOPSIS |
| .B agetty |
| [options] |
| .IR port " [" baud_rate "...] [" term ] |
| |
| .SH DESCRIPTION |
| .ad |
| .fi |
| \fBagetty\fP opens a tty port, prompts for a login name and invokes |
| the /bin/login command. It is normally invoked by \fBinit\fP(8). |
| |
| \fBagetty\fP has several \fInon-standard\fP features that are useful |
| for hardwired and for dial-in lines: |
| .IP \(bu |
| Adapts the tty settings to parity bits and to erase, kill, |
| end-of-line and uppercase characters when it reads a login name. |
| The program can handle 7-bit characters with even, odd, none or space |
| parity, and 8-bit characters with no parity. The following special |
| characters are recognized: Control-U (kill); DEL and |
| backspace (erase); carriage return and line feed (end of line). |
| See also the \fB\-\-erase\-chars\fP and \fB\-\-kill\-chars\fP options. |
| .IP \(bu |
| Optionally deduces the baud rate from the CONNECT messages produced by |
| Hayes(tm)-compatible modems. |
| .IP \(bu |
| Optionally does not hang up when it is given an already opened line |
| (useful for call-back applications). |
| .IP \(bu |
| Optionally does not display the contents of the \fI/etc/issue\fP file. |
| .IP \(bu |
| Optionally displays an alternative issue file or directory instead of \fI/etc/issue\fP or \fI/etc/issue.d\fP. |
| .IP \(bu |
| Optionally does not ask for a login name. |
| .IP \(bu |
| Optionally invokes a non-standard login program instead of |
| \fI/bin/login\fP. |
| .IP \(bu |
| Optionally turns on hardware flow control. |
| .IP \(bu |
| Optionally forces the line to be local with no need for carrier detect. |
| .PP |
| This program does not use the \fI/etc/gettydefs\fP (System V) or |
| \fI/etc/gettytab\fP (SunOS 4) files. |
| .SH ARGUMENTS |
| .na |
| .nf |
| .fi |
| .ad |
| .TP |
| .I port |
| A path name relative to the \fI/dev\fP directory. If a "\-" is |
| specified, \fBagetty\fP assumes that its standard input is |
| already connected to a tty port and that a connection to a |
| remote user has already been established. |
| .sp |
| Under System V, a "\-" \fIport\fP argument should be preceded |
| by a "\-\-". |
| .TP |
| .IR baud_rate ,... |
| A comma-separated list of one or more baud rates. Each time |
| \fBagetty\fP receives a BREAK character it advances through |
| the list, which is treated as if it were circular. |
| .sp |
| Baud rates should be specified in descending order, so that the |
| null character (Ctrl\-@) can also be used for baud-rate switching. |
| .sp |
| This argument is optional and unnecessary for \fBvirtual terminals\fP. |
| .sp |
| The default for \fBserial terminals\fP is keep the current baud rate |
| (see \fB\-\-keep\-baud\fP) and if unsuccessful then default to '9600'. |
| .TP |
| .I term |
| The value to be used for the TERM environment variable. This overrides |
| whatever init(8) may have set, and is inherited by login and the shell. |
| .sp |
| The default is 'vt100', or 'linux' for Linux on a virtual terminal, |
| or 'hurd' for GNU Hurd on a virtual terminal. |
| .SH OPTIONS |
| .na |
| .nf |
| .fi |
| .ad |
| .TP |
| \-8, \-\-8bits |
| Assume that the tty is 8-bit clean, hence disable parity detection. |
| .TP |
| \-a, \-\-autologin \fIusername\fP |
| Automatically log in the specified user without asking for a username or password. |
| Using this option causes an \fB\-f \fIusername\fR option and argument to be |
| added to the \fB/bin/login\fP command line. See \fB\-\-login\-options\fR, which |
| can be used to modify this option's behavior. |
| |
| Note that \fB\-\-autologin\fP may affect the way how agetty initializes the |
| serial line, because on auto-login agetty does not read from the line and it |
| has no opportunity optimize the line setting. |
| .TP |
| \-c, \-\-noreset |
| Do not reset terminal cflags (control modes). See \fBtermios\fP(3) for more |
| details. |
| .TP |
| \-E, \-\-remote |
| Typically the \fBlogin\fP(1) command is given a remote hostname when |
| called by something such as \fBtelnetd\fP(8). This option allows \fBagetty\fP |
| to pass what it is using for a hostname to \fBlogin\fP(1) for use |
| in \fButmp\fP(5). See \fB\-\-host\fP, \fBlogin\fP(1), and \fButmp\fP(5). |
| .IP |
| If the \fB\-\-host\fP \fIfakehost\fP option is given, then an \fB\-h\fP |
| \fIfakehost\fP option and argument are added to the \fB/bin/login\fP |
| command line. |
| .IP |
| If the \fB\-\-nohostname\fR option is given, then an \fB\-H\fP option |
| is added to the \fB/bin/login\fP command line. |
| .IP |
| See \fB\-\-login\-options\fR. |
| .TP |
| \-f, \-\-issue\-file \fIfile|directory\fP |
| Display the contents of \fIfile\fP instead of \fI/etc/issue\fP. If the |
| specified path is a \fIdirectory\fP then displays all files with .issue file |
| extension in version-sort order from the directory. This allows custom |
| messages to be displayed on different terminals. The |
| \-\-noissue option will override this option. |
| .TP |
| \-h, \-\-flow\-control |
| Enable hardware (RTS/CTS) flow control. It is left up to the |
| application to disable software (XON/XOFF) flow protocol where |
| appropriate. |
| .TP |
| \-H, \-\-host \fIfakehost\fP |
| Write the specified \fIfakehost\fP into the utmp file. Normally, |
| no login host is given, since \fBagetty\fP is used for local hardwired |
| connections and consoles. However, this option can be useful for |
| identifying terminal concentrators and the like. |
| .TP |
| \-i, \-\-noissue |
| Do not display the contents of \fI/etc/issue\fP (or other) before writing the |
| login prompt. Terminals or communications hardware may become confused |
| when receiving lots of text at the wrong baud rate; dial-up scripts |
| may fail if the login prompt is preceded by too much text. |
| .TP |
| \-I, \-\-init\-string \fIinitstring\fP |
| Set an initial string to be sent to the tty or modem before sending |
| anything else. This may be used to initialize a modem. Non-printable |
| characters may be sent by writing their octal code preceded by a |
| backslash (\\). For example, to send a linefeed character (ASCII 10, |
| octal 012), write \\012. |
| .TP |
| \-J, \-\-noclear |
| Do not clear the screen before prompting for the login name. |
| By default the screen is cleared. |
| .TP |
| \-l, \-\-login\-program \fIlogin_program\fP |
| Invoke the specified \fIlogin_program\fP instead of /bin/login. This allows |
| the use of a non-standard login program. Such a program could, for example, |
| ask for a dial-up password or use a different password file. See |
| \fB\-\-login\-options\fP. |
| .TP |
| \-L, \-\-local\-line[=\fImode\fP] |
| Control the CLOCAL line flag. The optional \fImode\fP argument is 'auto', 'always' or 'never'. |
| If the \fImode\fP argument is omitted, then the default is 'always'. If the |
| \-\-local\-line option is not given at all, then the default is 'auto'. |
| .PP |
| .RS |
| .PD 1 |
| .TP |
| \fIalways\fR |
| Forces the line to be a local line with no need for carrier detect. This |
| can be useful when you have a locally attached terminal where the serial |
| line does not set the carrier-detect signal. |
| .TP |
| \fInever\fR |
| Explicitly clears the CLOCAL flag from the line setting and the |
| carrier-detect signal is expected on the line. |
| .TP |
| \fIauto\fR |
| The \fBagetty\fR default. Does not modify the CLOCAL setting and follows |
| the setting enabled by the kernel. |
| .PD |
| .RE |
| .TP |
| \-m, \-\-extract\-baud |
| Try to extract the baud rate from the CONNECT status message |
| produced by Hayes(tm)\-compatible modems. These status |
| messages are of the form: "<junk><speed><junk>". |
| \fBagetty\fP assumes that the modem emits its status message at |
| the same speed as specified with (the first) \fIbaud_rate\fP value |
| on the command line. |
| .sp |
| Since the \fB\-\-extract\-baud\fP feature may fail on heavily-loaded |
| systems, you still should enable BREAK processing by enumerating all |
| expected baud rates on the command line. |
| .TP |
| \-\-list\-speeds |
| Display supported baud rates. These are determined at compilation time. |
| .TP |
| \-n, \-\-skip\-login |
| Do not prompt the user for a login name. This can be used in connection |
| with the \fB\-\-login\-program\fP option to invoke a non-standard login |
| process such as a BBS system. Note that with the \fB\-\-skip\-login\fR |
| option, \fBagetty\fR gets no input from the user who logs in and therefore |
| will not be able to figure out parity, character size, and newline |
| processing of the connection. It defaults to space parity, 7 bit |
| characters, and ASCII CR (13) end-of-line character. Beware that the |
| program that \fBagetty\fR starts (usually /bin/login) is run as root. |
| .TP |
| \-N, \-\-nonewline |
| Do not print a newline before writing out /etc/issue. |
| .TP |
| \-o, \-\-login\-options "\fIlogin_options\fP" |
| Options and arguments that are passed to \fBlogin\fP(1). Where \\u is |
| replaced by the login name. For example: |
| .RS |
| .IP "" 4 |
| .B "\-\-login\-options '-h darkstar -- \\\u'" |
| .PP |
| See \fB\-\-autologin\fR, \fB\-\-login\-program\fR and \fB\-\-remote\fR. |
| .PP |
| Please read the SECURITY NOTICE below before using this option. |
| .RE |
| .TP |
| \-p, \-\-login\-pause |
| Wait for any key before dropping to the login prompt. Can be combined |
| with \fB\-\-autologin\fP to save memory by lazily spawning shells. |
| .TP |
| \-r, \-\-chroot \fIdirectory\fP |
| Change root to the specified directory. |
| .TP |
| \-R, \-\-hangup |
| Call vhangup() to do a virtual hangup of the specified terminal. |
| .TP |
| \-s, \-\-keep\-baud |
| Try to keep the existing baud rate. The baud rates from |
| the command line are used when agetty receives a BREAK character. |
| .TP |
| \-t, \-\-timeout \fItimeout\fP |
| Terminate if no user name could be read within \fItimeout\fP seconds. |
| Use of this option with hardwired terminal lines is not recommended. |
| .TP |
| \-U, \-\-detect\-case |
| Turn on support for detecting an uppercase-only terminal. This setting |
| will detect a login name containing only capitals as indicating an |
| uppercase-only terminal and turn on some upper-to-lower case conversions. |
| Note that this has no support for any Unicode characters. |
| .TP |
| \-w, \-\-wait\-cr |
| Wait for the user or the modem to send a carriage-return or a |
| linefeed character before sending the \fI/etc/issue\fP file (or others) |
| and the login prompt. This is useful with the \fB\-\-init\-string\fP |
| option. |
| .TP |
| \-\-nohints |
| Do not print hints about Num, Caps and Scroll Locks. |
| .TP |
| \-\-nohostname |
| By default the hostname will be printed. With this option enabled, |
| no hostname at all will be shown. |
| .TP |
| \-\-long\-hostname |
| By default the hostname is only printed until the first dot. With |
| this option enabled, the fully qualified hostname by \fBgethostname\fR(3P) |
| or (if not found) by \fBgetaddrinfo\fR(3) is shown. |
| .TP |
| \-\-erase\-chars \fIstring\fP |
| This option specifies additional characters that should be interpreted as a |
| backspace ("ignore the previous character") when the user types the login name. |
| The default additional \'erase\' has been \'#\', but since util-linux 2.23 |
| no additional erase characters are enabled by default. |
| .TP |
| \-\-kill\-chars \fIstring\fP |
| This option specifies additional characters that should be interpreted as a |
| kill ("ignore all previous characters") when the user types the login name. |
| The default additional \'kill\' has been \'@\', but since util-linux 2.23 |
| no additional kill characters are enabled by default. |
| .TP |
| \-\-chdir \fIdirectory\fP |
| Change directory before the login. |
| .TP |
| \-\-delay \fInumber\fP |
| Sleep seconds before open tty. |
| .TP |
| \-\-nice \fInumber\fP |
| Run login with this priority. |
| .TP |
| \-\-reload |
| Ask all running agetty instances to reload and update their displayed prompts, |
| if the user has not yet commenced logging in. After doing so the command will |
| exit. This feature might be unsupported on systems without Linux |
| .BR inotify (7). |
| .TP |
| \-\-version |
| Display version information and exit. |
| .TP |
| \-\-help |
| Display help text and exit. |
| .PP |
| .SH EXAMPLES |
| This section shows examples for the process field of an entry in the |
| \fI/etc/inittab\fP file. You'll have to prepend appropriate values |
| for the other fields. See \fIinittab(5)\fP for more details. |
| |
| For a hardwired line or a console tty: |
| |
| .RS |
| .B /sbin/agetty\ 9600\ ttyS1 |
| .RE |
| |
| For a directly connected terminal without proper carrier-detect wiring |
| (try this if your terminal just sleeps instead of giving you a password: |
| prompt): |
| |
| .RS |
| .B /sbin/agetty\ \-\-local\-line\ 9600\ ttyS1\ vt100 |
| .RE |
| |
| For an old-style dial-in line with a 9600/2400/1200 baud modem: |
| |
| .RS |
| .B /sbin/agetty\ \-\-extract\-baud\ \-\-timeout\ 60\ ttyS1\ 9600,2400,1200 |
| .RE |
| |
| 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): |
| |
| .RS |
| .B /sbin/agetty\ \-\-wait\-cr\ \-\-init\-string\ 'ATE0Q1&D2&C1S0=1\\015'\ 115200\ ttyS1 |
| .RE |
| |
| .SH SECURITY NOTICE |
| If you use the \fB\-\-login\-program\fP and \fB\-\-login\-options\fP 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. |
| .PP |
| Some programs use "\-\-" to indicate that the rest of the commandline should |
| not be interpreted as options. Use this feature if available by passing "\-\-" |
| before the username gets passed by \\u. |
| |
| .SH ISSUE FILES |
| The default issue file is \fI/etc/issue\fP. If the file exists then agetty also |
| checks for \fI/etc/issue.d\fP directory. The directory is optional extension to |
| the default issue file and content of the directory is printed after |
| \fI/etc/issue\fP content. If the \fI/etc/issue\fP does not exist than the |
| directory is ignored. All files with .issue extension from the directory are |
| printed in version-sort order. The directory allow to maintain 3rd-party |
| messages independently on the primary system \fI/etc/issue\fP file. |
| |
| The default path maybe overridden by \fB\-\-issue\-file\fP option. In this case |
| specified path has to be file or directory and the default \fI/etc/issue\fP as |
| well as \fI/etc/issue.d\fP are ignored. |
| |
| The issue files may contain certain escape codes to display the system name, date, time |
| etcetera. All escape codes consist of a backslash (\\) immediately |
| followed by one of the characters listed below. |
| |
| .TP |
| 4 or 4{\fIinterface\fR} |
| Insert the IPv4 address of the specified network interface (for example: \\4{eth0}). |
| If the \fIinterface\fR argument is not specified, then select the first fully |
| configured (UP, non-LOCALBACK, RUNNING) interface. If not any configured |
| interface is found, fall back to the IP address of the machine's hostname. |
| .TP |
| 6 or 6{\fIinterface\fR} |
| The same as \\4 but for IPv6. |
| .TP |
| b |
| Insert the baudrate of the current line. |
| .TP |
| d |
| Insert the current date. |
| .TP |
| e or e{\fIname\fR} |
| Translate the human-readable \fIname\fP to an escape sequence and insert it |
| (for example: \\e{red}Alert text.\\e{reset}). If the \fIname\fR argument is |
| not specified, then insert \\033. The currently supported names are: black, |
| blink, blue, bold, brown, cyan, |
| darkgray, gray, green, halfbright, lightblue, lightcyan, lightgray, lightgreen, |
| lightmagenta, lightred, magenta, red, reset, reverse, and yellow. All unknown |
| names are silently ignored. |
| .TP |
| s |
| Insert the system name (the name of the operating system). Same as 'uname \-s'. |
| See also the \\S escape code. |
| .TP |
| S or S{VARIABLE} |
| Insert the VARIABLE data from \fI/etc/os-release\fP. If this file does not exist |
| then fall back to \fI/usr/lib/os-release\fP. If the VARIABLE argument is not |
| specified, then use PRETTY_NAME from the file or the system name (see \\s). |
| This escape code allows to keep \fI/etc/issue\fP distribution and release |
| independent. Note that \\S{ANSI_COLOR} is converted to the real terminal |
| escape sequence. |
| .TP |
| l |
| Insert the name of the current tty line. |
| .TP |
| m |
| Insert the architecture identifier of the machine. Same as 'uname \-m'. |
| .TP |
| n |
| Insert the nodename of the machine, also known as the hostname. Same as 'uname \-n'. |
| .TP |
| o |
| Insert the NIS domainname of the machine. Same as 'hostname \-d'. |
| .TP |
| O |
| Insert the DNS domainname of the machine. |
| .TP |
| r |
| Insert the release number of the OS. Same as 'uname \-r'. |
| .TP |
| t |
| Insert the current time. |
| .TP |
| u |
| Insert the number of current users logged in. |
| .TP |
| U |
| Insert the string "1 user" or "<n> users" where <n> is the number of current |
| users logged in. |
| .TP |
| v |
| Insert the version of the OS, that is, the build-date and such. |
| .PP |
| An example. On my system, the following \fI/etc/issue\fP file: |
| .sp |
| .na |
| .RS |
| .nf |
| This is \\n.\\o (\\s \\m \\r) \\t |
| .fi |
| .RE |
| .PP |
| displays as: |
| .sp |
| .RS |
| .nf |
| This is thingol.orcan.dk (Linux i386 1.1.9) 18:29:30 |
| .fi |
| .RE |
| |
| .SH FILES |
| .na |
| .TP |
| .I /var/run/utmp |
| the system status file. |
| .TP |
| .I /etc/issue |
| printed before the login prompt. |
| .TP |
| .I /etc/os-release /usr/lib/os-release |
| operating system identification data. |
| .TP |
| .I /dev/console |
| problem reports (if syslog(3) is not used). |
| .TP |
| .I /etc/inittab |
| \fIinit\fP(8) configuration file for SysV-style init daemon. |
| .SH BUGS |
| .ad |
| .fi |
| The baud-rate detection feature (the \fB\-\-extract\-baud\fP option) requires that |
| \fBagetty\fP 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 \fB\-\-extract\-baud\fP option in combination with a multiple baud |
| rate command-line argument, so that BREAK processing is enabled. |
| |
| The text in the \fI/etc/issue\fP file (or other) and the login prompt |
| are always output with 7-bit characters and space parity. |
| |
| The baud-rate detection feature (the \fB\-\-extract\-baud\fP option) requires that |
| the modem emits its status message \fIafter\fP raising the DCD line. |
| .SH DIAGNOSTICS |
| .ad |
| .fi |
| Depending on how the program was configured, all diagnostics are |
| written to the console device or reported via the \fBsyslog\fR(3) facility. |
| Error messages are produced if the \fIport\fP argument does not |
| specify a terminal device; if there is no utmp entry for the |
| current process (System V only); and so on. |
| .SH AUTHORS |
| .UR werner@suse.de |
| Werner Fink |
| .UE |
| .br |
| .UR kzak@redhat.com |
| Karel Zak |
| .UE |
| .sp |
| The original |
| .B agetty |
| for serial terminals was written by W.Z. Venema <wietse@wzv.win.tue.nl> |
| and ported to Linux by Peter Orbaek <poe@daimi.aau.dk>. |
| |
| .SH AVAILABILITY |
| The agetty command is part of the util-linux package and is available from |
| https://www.kernel.org/pub/linux/utils/util\-linux/. |