diff options
Diffstat (limited to 'term-utils/agetty.8')
| -rw-r--r-- | term-utils/agetty.8 | 504 |
1 files changed, 504 insertions, 0 deletions
diff --git a/term-utils/agetty.8 b/term-utils/agetty.8 new file mode 100644 index 0000000..1ef9387 --- /dev/null +++ b/term-utils/agetty.8 @@ -0,0 +1,504 @@ +.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): + +.ie n .RS 0 +.el .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/. |