Adding upstream version 2.33.1.upstream/2.33.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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/.