diff options
Diffstat (limited to 'term-utils/agetty.8')
| -rw-r--r-- | term-utils/agetty.8 | 371 |
1 files changed, 371 insertions, 0 deletions
diff --git a/term-utils/agetty.8 b/term-utils/agetty.8 new file mode 100644 index 0000000..ebfdb96 --- /dev/null +++ b/term-utils/agetty.8 @@ -0,0 +1,371 @@ +.TH AGETTY 8 "May 2011" "util-linux" "System Administration" +.SH NAME +agetty \- alternative Linux getty + +.SH SYNOPSIS +.BR "agetty " [\-8chiLmnsUw] +.RI "[\-a " user ] +.RI "[\-f " issue_file ] +.RI "[\-H " login_host ] +.RI "[\-I " init ] +.RI "[\-l " login_program ] +.RI "[\-t " timeout ] +.I port +.I baud_rate,... +.RI [ 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 \fIinit(8)\fP. + +\fBagetty\fP has several \fInon-standard\fP features that are useful +for hard-wired and for dial-in lines: +.IP o +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: @ and Control-U (kill); #, DEL and +back space (erase); carriage return and line feed (end of line). +.IP o +Optionally deduces the baud rate from the CONNECT messages produced by +Hayes(tm)-compatible modems. +.IP o +Optionally does not hang up when it is given an already opened line +(useful for call-back applications). +.IP o +Optionally does not display the contents of the \fI/etc/issue\fP file. +.IP o +Optionally displays an alternative issue file instead of \fI/etc/issue\fP. +.IP o +Optionally does not ask for a login name. +.IP o +Optionally invokes a non-standard login program instead of +\fI/bin/login\fP. +.IP o +Optionally turns on hard-ware flow control +.IP o +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 +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 +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. +.TP +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. +.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 +Log the specified user automatically in without asking for a login name and +password. The \-f \fIusername\fP option is added to the \fB/bin/login\fP +command line by default. The \-\-login-options option changes this default +behaviour and then only \\u is replaced by the \fIusername\fP and no other +option is added to the login command line. +.TP +\-c, \-\-noreset +Don't reset terminal cflags (control modes). See \fItermios(3)\fP for more +details. +.TP +\-E, \-\-remote +If \-H \fIfakehost\fP option is given then \-r \fIfakehost\fP options is +added to the the \fB/bin/login\fP command line. +.TP +\-f, \-\-issue\-file \fIissue_file\fP +Display the contents of \fIissue_file\fP instead of \fI/etc/issue\fP. +This allows custom messages to be displayed on different terminals. +The \-i 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 \fIlogin_host\fP +Write the specified \fIlogin_host\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. +.PP +.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 (for example, +one that asks for a dial-up password or that uses a different +password file). +.TP +\-L, \-\-local\-line +Force 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 +\-m, \-\-extract\-baud +Try to extract the baud rate 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 \fI\-m\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 +\-n, \-\-skip\-login +Do not prompt the user for a login name. This can be used in +connection with \-l option to invoke a non-standard login process such +as a BBS system. Note that with the \-n option, \fBagetty\fR gets no input from +user who logs in and therefore won't 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 +\-o, \-\-login\-options \fI"login_options"\fP +Options that are passed to the login program. \\u is replaced +by the login name. The default \fB/bin/login\fP command line +is "/bin/login -- <username>". + +Please read the SECURITY NOTICE below if you want to use this. +.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, \-\-hangup +Do call vhangup() for a virtually 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. This option should probably not be used with hard-wired +lines. +.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 (or other) file +and the login prompt. Very useful in connection with the \-I option. +.TP +\-\-noclear +Do not clear the screen before prompting for the login name +(the screen is normally cleared). +.TP +\-\-nohints +Do not print hints about Num, Caps and Scroll Locks. +.TP +\-\-nonewline +Do not print a newline before writing out /etc/issue. +.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 full qualified hostname by gethostname() +or if not found by gethostbyname() is shown. +.TP +\-\-version +Output version information and exit. +.TP +\-\-help +Output help screen 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 hard-wired line or a console tty: +.ti +5 +/sbin/agetty 9600 ttyS1 + +For a directly connected terminal without proper carriage detect wiring: +(try this if your terminal just sleeps instead of giving you a password: +prompt.) +.ti +5 +/sbin/agetty \-L 9600 ttyS1 vt100 + +For a old style dial-in line with a 9600/2400/1200 baud modem: +.ti +5 +/sbin/agetty \-mt60 ttyS1 9600,2400,1200 + +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 +dis-connection and turn on auto-answer after 1 ring.) +.ti +5 +/sbin/agetty \-w \-I 'ATE0Q1&D2&C1S0=1\\015' 115200 ttyS1 + +.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 can not 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 ESCAPES +The issue-file (\fI/etc/issue\fP or the file set with the \-f option) +may contain certain escape codes to display the system name, date and +time etc. All escape codes consist of a backslash (\\) immediately +followed by one of the letters explained below. + +.TP +b +Insert the baudrate of the current line. +.TP +d +Insert the current date. +.TP +s +Insert the system name, the name of the operating system. Same as `uname \-s'. +.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, eg. the build-date etc. +.TP +Example: On my system, the following \fI/etc/issue\fP file: + +.na +.nf +.ti +.5 +This is \\n.\\o (\\s \\m \\r) \\t +.TP +displays as + +.ti +.5 +This is thingol.orcan.dk (Linux i386 1.1.9) 18:29:30 + +.fi + +.SH FILES +.na +.nf +/var/run/utmp, the system status file. +/etc/issue, printed before the login prompt. +/dev/console, problem reports (if syslog(3) is not used). +/etc/inittab, \fIinit\fP(8) configuration file. +.SH BUGS +.ad +.fi +The baud-rate detection feature (the \fI\-m\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 \fI\-m\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 \fI\-m\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 syslog(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 AUTHOR(S) +.na +.nf +W.Z. Venema <wietse@wzv.win.tue.nl> +Eindhoven University of Technology +Department of Mathematics and Computer Science +Den Dolech 2, P.O. Box 513, 5600 MB Eindhoven, The Netherlands + +Peter Orbaek <poe@daimi.aau.dk> +Linux port and more options. Still maintains the code. + +Eric Rasmussen <ear@usfirst.org> +Added \-f option to display custom login messages on different terminals. + +.SH AVAILABILITY +The agetty command is part of the util-linux package and is available from +ftp://ftp.kernel.org/pub/linux/utils/util\-linux/. |