manual/util-linux/original/man8/agetty.8

   1 .TH AGETTY 8
   2 .SH NAME
   3 agetty \- alternative Linux getty
   4
   5 .SH SYNOPSIS
   6 .BR "agetty " [\-ihLmnw]
   7 .RI "[-f " issue_file ]
   8 .RI "[-l " login_program ]
   9 .RI "[-I " init ]
  10 .RI "[-t " timeout ]
  11 .RI "[-H " login_host ]
  12 .I port
  13 .I baud_rate,...
  14 .RI [ term ]
  15 .br
  16 .BR "agetty " [\-ihLmnw]
  17 .RI "[-f " issue_file ]
  18 .RI "[-l " login_program ]
  19 .RI "[-I " init ]
  20 .RI "[-t " timeout ]
  21 .RI "[-H " login_host ]
  22 .I baud_rate,...
  23 .I port
  24 .RI [ term ]
  25
  26 .SH DESCRIPTION
  27 .ad
  28 .fi
  29 \fBagetty\fP opens a tty port, prompts for a login name and invokes
  30 the /bin/login command. It is normally invoked by \fIinit(8)\fP.
  31
  32 \fBagetty\fP has several \fInon-standard\fP features that are useful
  33 for hard-wired and for dial-in lines:
  34 .IP o
  35 Adapts the tty settings to parity bits and to erase, kill,
  36 end-of-line and uppercase characters when it reads a login name.
  37 The program can handle 7-bit characters with even, odd, none or space
  38 parity, and 8-bit characters with no parity. The following special
  39 characters are recognized: @ and Control-U (kill); #, DEL and
  40 back space (erase); carriage return and line feed (end of line).
  41 .IP o
  42 Optionally deduces the baud rate from the CONNECT messages produced by
  43 Hayes(tm)-compatible modems.
  44 .IP o
  45 Optionally does not hang up when it is given an already opened line
  46 (useful for call-back applications).
  47 .IP o
  48 Optionally does not display the contents of the \fI/etc/issue\fP file.
  49 .IP o
  50 Optionally displays an alternative issue file instead of \fI/etc/issue\fP.
  51 .IP o
  52 Optionally does not ask for a login name.
  53 .IP o
  54 Optionally invokes a non-standard login program instead of
  55 \fI/bin/login\fP.
  56 .IP o
  57 Optionally turns on hard-ware flow control
  58 .IP o
  59 Optionally forces the line to be local with no need for carrier detect.
  60 .PP
  61 This program does not use the \fI/etc/gettydefs\fP (System V) or
  62 \fI/etc/gettytab\fP (SunOS 4) files.
  63 .SH ARGUMENTS
  64 .na
  65 .nf
  66 .fi
  67 .ad
  68 .TP
  69 port
  70 A path name relative to the \fI/dev\fP directory. If a "-" is
  71 specified, \fBagetty\fP assumes that its standard input is
  72 already connected to a tty port and that a connection to a
  73 remote user has already been established.
  74 .sp
  75 Under System V, a "-" \fIport\fP argument should be preceded
  76 by a "--".
  77 .TP
  78 baud_rate,...
  79 A comma-separated list of one or more baud rates. Each time
  80 \fBagetty\fP receives a BREAK character it advances through
  81 the list, which is treated as if it were circular.
  82 .sp
  83 Baud rates should be specified in descending order, so that the
  84 null character (Ctrl-@) can also be used for baud rate switching.
  85 .TP
  86 term
  87 The value to be used for the TERM environment variable. This overrides
  88 whatever init(8) may have set, and is inherited by login and the shell.
  89 .SH OPTIONS
  90 .na
  91 .nf
  92 .fi
  93 .ad
  94 .TP
  95 \-h
  96 Enable hardware (RTS/CTS) flow control. It is left up to the
  97 application to disable software (XON/XOFF) flow protocol where
  98 appropriate.
  99 .TP
 100 \-i
 101 Do not display the contents of \fI/etc/issue\fP (or other) before writing the
 102 login prompt. Terminals or communications hardware may become confused
 103 when receiving lots of text at the wrong baud rate; dial-up scripts
 104 may fail if the login prompt is preceded by too much text.
 105 .TP
 106 \-f \fIissue_file\fP
 107 Display the contents of \fIissue_file\fP instead of \fI/etc/issue\fP.
 108 This allows custom messages to be displayed on different terminals.
 109 The \-i option will override this option.
 110 .TP
 111 \-I \fIinitstring\fP
 112 Set an initial string to be sent to the tty or modem before sending
 113 anything else. This may be used to initialize a modem.  Non printable
 114 characters may be sent by writing their octal code preceded by a
 115 backslash (\\). For example to send a linefeed character (ASCII 10,
 116 octal 012) write \\012.
 117 .PP
 118 .TP
 119 \-l \fIlogin_program\fP
 120 Invoke the specified \fIlogin_program\fP instead of /bin/login.
 121 This allows the use of a non-standard login program (for example,
 122 one that asks for a dial-up password or that uses a different
 123 password file).
 124 .TP
 125 \-H \fIlogin_host\fP
 126 Write the specified \fIlogin_host\fP into the utmp file. (Normally,
 127 no login host is given, since \fBagetty\fP is used for local hardwired
 128 connections and consoles. However, this option can be useful for
 129 identifying terminal concentrators and the like.
 130 .TP
 131 \-m
 132 Try to extract the baud rate the CONNECT status message
 133 produced by Hayes(tm)\-compatible modems. These status
 134 messages are of the form: "<junk><speed><junk>".
 135 \fBagetty\fP assumes that the modem emits its status message at
 136 the same speed as specified with (the first) \fIbaud_rate\fP value
 137 on the command line.
 138 .sp
 139 Since the \fI\-m\fP feature may fail on heavily-loaded systems,
 140 you still should enable BREAK processing by enumerating all
 141 expected baud rates on the command line.
 142 .TP
 143 \-n
 144 Do not prompt the user for a login name. This can be used in
 145 connection with \-l option to invoke a non-standard login process such
 146 as a BBS system. Note that with the \-n option, \fBagetty\fR gets no input from
 147 user who logs in and therefore won't be able to figure out parity,
 148 character size, and newline processing of the connection. It defaults to
 149 space parity, 7 bit characters, and ASCII CR (13) end-of-line character.
 150 Beware that the program that \fBagetty\fR starts (usually /bin/login)
 151 is run as root.
 152 .TP
 153 \-t \fItimeout\fP
 154 Terminate if no user name could be read within \fItimeout\fP
 155 seconds. This option should probably not be used with hard-wired
 156 lines.
 157 .TP
 158 \-L
 159 Force the line to be a local line with no need for carrier detect. This can
 160 be useful when you have a locally attached terminal where the serial line
 161 does not set the carrier detect signal.
 162 .TP
 163 \-w
 164 Wait for the user or the modem to send a carriage-return or a
 165 linefeed character before sending the \fI/etc/issue\fP (or other) file
 166 and the login prompt. Very useful in connection with the \-I option.
 167 .PP
 168 .SH EXAMPLES
 169 This section shows examples for the process field of an entry in the
 170 \fI/etc/inittab\fP file.  You'll have to prepend appropriate values
 171 for the other fields.  See \fIinittab(5)\fP for more details.
 172
 173 For a hard-wired line or a console tty:
 174 .ti +5
 175 /sbin/agetty 9600 ttyS1
 176
 177 For a directly connected terminal without proper carriage detect wiring:
 178 (try this if your terminal just sleeps instead of giving you a password:
 179 prompt.)
 180 .ti +5
 181 /sbin/agetty \-L 9600 ttyS1 vt100
 182
 183 For a old style dial-in line with a 9600/2400/1200 baud modem:
 184 .ti +5
 185 /sbin/agetty \-mt60 ttyS1 9600,2400,1200
 186
 187 For a Hayes modem with a fixed 115200 bps interface to the machine:
 188 (the example init string turns off modem echo and result codes, makes
 189 modem/computer DCD track modem/modem DCD, makes a DTR drop cause a
 190 dis-connection and turn on auto-answer after 1 ring.)
 191 .ti +5
 192 /sbin/agetty \-w \-I 'ATE0Q1&D2&C1S0=1\\015' 115200 ttyS1
 193
 194 .SH ISSUE ESCAPES
 195 The issue-file (\fI/etc/issue\fP or the file set with the \-f option)
 196 may contain certain escape codes to display the system name, date and
 197 time etc. All escape codes consist of a backslash (\\) immediately
 198 followed by one of the letters explained below.
 199
 200 .TP
 201 b
 202 Insert the baudrate of the current line.
 203 .TP
 204 d
 205 Insert the current date.
 206 .TP
 207 s
 208 Insert the system name, the name of the operating system.
 209 .TP
 210 l
 211 Insert the name of the current tty line.
 212 .TP
 213 m
 214 Insert the architecture identifier of the machine, eg. i486
 215 .TP
 216 n
 217 Insert the nodename of the machine, also known as the hostname.
 218 .TP
 219 o
 220 Insert the domainname of the machine.
 221 .TP
 222 r
 223 Insert the release number of the OS, eg. 1.1.9.
 224 .TP
 225 t
 226 Insert the current time.
 227 .TP
 228 u
 229 Insert the number of current users logged in.
 230 .TP
 231 U
 232 Insert the string "1 user" or "<n> users" where <n> is the number of current
 233 users logged in.
 234 .TP
 235 v
 236 Insert the version of the OS, eg. the build-date etc.
 237 .TP
 238 Example: On my system, the following \fI/etc/issue\fP file:
 239
 240 .na
 241 .nf
 242 .ti +.5
 243 This is \\n.\\o (\\s \\m \\r) \\t
 244 .TP
 245 displays as
 246
 247 .ti +.5
 248 This is thingol.orcan.dk (Linux i386 1.1.9) 18:29:30
 249
 250 .fi
 251
 252 .SH FILES
 253 .na
 254 .nf
 255 /var/run/utmp, the system status file.
 256 /etc/issue, printed before the login prompt.
 257 /dev/console, problem reports (if syslog(3) is not used).
 258 /etc/inittab, \fIinit\fP(8) configuration file.
 259 .SH BUGS
 260 .ad
 261 .fi
 262 The baud-rate detection feature (the \fI-m\fP option) requires that
 263 \fBagetty\fP be scheduled soon enough after completion of a dial-in
 264 call (within 30 ms with modems that talk at 2400 baud). For robustness,
 265 always use the \fI\-m\fP option in combination with a multiple baud
 266 rate command-line argument, so that BREAK processing is enabled.
 267
 268 The text in the \fI/etc/issue\fP file (or other) and the login prompt
 269 are always output with 7-bit characters and space parity.
 270
 271 The baud-rate detection feature (the \fI-m\fP option) requires that
 272 the modem emits its status message \fIafter\fP raising the DCD line.
 273 .SH DIAGNOSTICS
 274 .ad
 275 .fi
 276 Depending on how the program was configured, all diagnostics are
 277 written to the console device or reported via the syslog(3) facility.
 278 Error messages are produced if the \fIport\fP argument does not
 279 specify a terminal device; if there is no utmp entry for the
 280 current process (System V only); and so on.
 281 .SH AUTHOR(S)
 282 .na
 283 .nf
 284 W.Z. Venema <wietse@wzv.win.tue.nl>
 285 Eindhoven University of Technology
 286 Department of Mathematics and Computer Science
 287 Den Dolech 2, P.O. Box 513, 5600 MB Eindhoven, The Netherlands
 288
 289 Peter Orbaek <poe@daimi.aau.dk>
 290 Linux port and more options. Still maintains the code.
 291
 292 Eric Rasmussen <ear@usfirst.org>
 293 Added \-f option to display custom login messages on different terminals.
 294
 295 .SH CREATION DATE
 296 .na
 297 .nf
 298 Sat Nov 25 22:51:05 MET 1989
 299 .SH LAST MODIFICATION
 300 .na
 301 .nf
 302 96/07/20