1AGETTY(8)                    System Administration                   AGETTY(8)
2
3
4

NAME

6       agetty - alternative Linux getty
7
8

SYNOPSIS

10       agetty [options] port [baud_rate...] [term]
11
12

DESCRIPTION

14       agetty  opens  a  tty  port,  prompts  for a login name and invokes the
15       /bin/login command.  It is normally invoked by init(8).
16
17       agetty has several non-standard features that are useful for  hardwired
18       and for dial-in lines:
19
20       ·      Adapts  the tty settings to parity bits and to erase, kill, end-
21              of-line and uppercase characters when it  reads  a  login  name.
22              The  program can handle 7-bit characters with even, odd, none or
23              space parity, and 8-bit characters with no parity.  The  follow‐
24              ing special characters are recognized: Control-U (kill); DEL and
25              backspace (erase); carriage return and line feed (end of  line).
26              See also the --erase-chars and --kill-chars options.
27
28       ·      Optionally  deduces the baud rate from the CONNECT messages pro‐
29              duced by Hayes(tm)-compatible modems.
30
31       ·      Optionally does not hang up when it is given an  already  opened
32              line (useful for call-back applications).
33
34       ·      Optionally does not display the contents of the /etc/issue file.
35
36       ·      Optionally  displays  an  alternative  issue  file  or directory
37              instead of /etc/issue or /etc/issue.d.
38
39       ·      Optionally does not ask for a login name.
40
41       ·      Optionally invokes  a  non-standard  login  program  instead  of
42              /bin/login.
43
44       ·      Optionally turns on hardware flow control.
45
46       ·      Optionally  forces the line to be local with no need for carrier
47              detect.
48
49       This program does not use the /etc/gettydefs (System  V)  or  /etc/get‐
50       tytab (SunOS 4) files.
51

ARGUMENTS

53       port   A  path name relative to the /dev directory.  If a "-" is speci‐
54              fied, agetty assumes that its standard  input  is  already  con‐
55              nected  to a tty port and that a connection to a remote user has
56              already been established.
57
58              Under System V, a "-" port argument  should  be  preceded  by  a
59              "--".
60
61       baud_rate,...
62              A  comma-separated  list  of  one or more baud rates.  Each time
63              agetty receives a BREAK character it advances through the  list,
64              which is treated as if it were circular.
65
66              Baud  rates should be specified in descending order, so that the
67              null character (Ctrl-@) can also be used for  baud-rate  switch‐
68              ing.
69
70              This argument is optional and unnecessary for virtual terminals.
71
72              The  default  for serial terminals is keep the current baud rate
73              (see --keep-baud) and if unsuccessful then default to '9600'.
74
75       term   The value to be used for the TERM  environment  variable.   This
76              overrides  whatever  init(8)  may  have set, and is inherited by
77              login and the shell.
78
79              The default is 'vt100', or 'linux' for Linux on a virtual termi‐
80              nal, or 'hurd' for GNU Hurd on a virtual terminal.
81

OPTIONS

83       -8, --8bits
84              Assume  that the tty is 8-bit clean, hence disable parity detec‐
85              tion.
86
87       -a, --autologin username
88              Automatically log in the specified user  without  asking  for  a
89              username  or  password.  Using this option causes an -f username
90              option and argument to be added to the /bin/login command  line.
91              See  --login-options,  which can be used to modify this option's
92              behavior.
93
94              Note that --autologin may affect the way how agetty  initializes
95              the serial line, because on auto-login agetty does not read from
96              the line and it has no opportunity optimize the line setting.
97
98       -c, --noreset
99              Do not reset terminal cflags (control  modes).   See  termios(3)
100              for more details.
101
102       -E, --remote
103              Typically  the  login(1) command is given a remote hostname when
104              called by something such  as  telnetd(8).   This  option  allows
105              agetty  to  pass what it is using for a hostname to login(1) for
106              use in utmp(5).  See --host, login(1), and utmp(5).
107
108              If the --host fakehost option is  given,  then  an  -h  fakehost
109              option and argument are added to the /bin/login command line.
110
111              If  the --nohostname option is given, then an -H option is added
112              to the /bin/login command line.
113
114              See --login-options.
115
116       -f, --issue-file file|directory
117              Display the contents of file instead of /etc/issue  (or  other).
118              If  the  specified  path  is a directory then displays all files
119              with .issue file extension in version-sort order from the direc‐
120              tory.   This allows custom messages to be displayed on different
121              terminals.  The --noissue option will override this option.
122
123       --show-issue
124              Display the current issue file (or other) on the current  termi‐
125              nal and exit.  Use this option to review the current setting, it
126              is not designed for any other purpose.  Note that output may use
127              some  default or incomplete information as proper output depends
128              on terminal and agetty command line.
129
130       -h, --flow-control
131              Enable hardware (RTS/CTS) flow control.  It is left  up  to  the
132              application  to  disable software (XON/XOFF) flow protocol where
133              appropriate.
134
135       -H, --host fakehost
136              Write the specified fakehost into the utmp file.   Normally,  no
137              login  host  is  given, since agetty is used for local hardwired
138              connections and consoles.  However, this option  can  be  useful
139              for identifying terminal concentrators and the like.
140
141       -i, --noissue
142              Do  not  display  the  contents  of /etc/issue (or other) before
143              writing the login prompt.  Terminals or communications  hardware
144              may  become  confused  when  receiving lots of text at the wrong
145              baud rate; dial-up scripts may fail if the login prompt is  pre‐
146              ceded by too much text.
147
148       -I, --init-string initstring
149              Set  an  initial  string  to  be sent to the tty or modem before
150              sending anything else.  This may be used to initialize a  modem.
151              Non-printable characters may be sent by writing their octal code
152              preceded by a backslash (\).  For example, to  send  a  linefeed
153              character (ASCII 10, octal 012), write \012.
154
155       -J, --noclear
156              Do not clear the screen before prompting for the login name.  By
157              default the screen is cleared.
158
159       -l, --login-program login_program
160              Invoke the specified login_program instead of /bin/login.   This
161              allows  the use of a non-standard login program.  Such a program
162              could, for example, ask for a dial-up password or use a  differ‐
163              ent password file. See --login-options.
164
165       -L, --local-line[=mode]
166              Control  the  CLOCAL  line  flag.  The optional mode argument is
167              'auto', 'always' or 'never'.  If the mode argument  is  omitted,
168              then the default is 'always'.  If the --local-line option is not
169              given at all, then the default is 'auto'.
170
171              always Forces the line to be a local line with no need for  car‐
172                     rier  detect.  This can be useful when you have a locally
173                     attached terminal where the serial line does not set  the
174                     carrier-detect signal.
175
176              never  Explicitly  clears  the CLOCAL flag from the line setting
177                     and the carrier-detect signal is expected on the line.
178
179              auto   The agetty default.  Does not modify the  CLOCAL  setting
180                     and follows the setting enabled by the kernel.
181
182       -m, --extract-baud
183              Try  to  extract  the  baud rate from the CONNECT status message
184              produced by Hayes(tm)-compatible modems.  These status  messages
185              are of the form: "<junk><speed><junk>".  agetty assumes that the
186              modem emits its status message at the same  speed  as  specified
187              with (the first) baud_rate value on the command line.
188
189              Since the --extract-baud feature may fail on heavily-loaded sys‐
190              tems, you still should enable BREAK  processing  by  enumerating
191              all expected baud rates on the command line.
192
193       --list-speeds
194              Display  supported baud rates.  These are determined at compila‐
195              tion time.
196
197       -n, --skip-login
198              Do not prompt the user for a login name.  This can  be  used  in
199              connection with the --login-program option to invoke a non-stan‐
200              dard login process such as a BBS system.   Note  that  with  the
201              --skip-login option, agetty gets no input from the user who logs
202              in and therefore will not be able to figure out parity,  charac‐
203              ter size, and newline processing of the connection.  It defaults
204              to space parity, 7 bit characters, and ASCII CR (13) end-of-line
205              character.   Beware that the program that agetty starts (usually
206              /bin/login) is run as root.
207
208       -N, --nonewline
209              Do not print a newline before writing out /etc/issue.
210
211       -o, --login-options "login_options"
212              Options  and arguments that  are passed to login(1). Where \u is
213              replaced by the login name. For example:
214
215                  --login-options '-h darkstar -- \u'
216
217              See --autologin, --login-program and --remote.
218
219              Please read the SECURITY NOTICE below before using this option.
220
221       -p, --login-pause
222              Wait  for  any  key before dropping to the login prompt.  Can be
223              combined with --autologin to  save  memory  by  lazily  spawning
224              shells.
225
226       -r, --chroot directory
227              Change root to the specified directory.
228
229       -R, --hangup
230              Call vhangup() to do a virtual hangup of the specified terminal.
231
232       -s, --keep-baud
233              Try  to  keep  the  existing baud rate.  The baud rates from the
234              command line are used when agetty receives a BREAK character.
235
236       -t, --timeout timeout
237              Terminate if no user name could be read within timeout  seconds.
238              Use  of  this option with hardwired terminal lines is not recom‐
239              mended.
240
241       -U, --detect-case
242              Turn on support for detecting an uppercase-only terminal.   This
243              setting  will  detect  a  login name containing only capitals as
244              indicating an uppercase-only terminal and turn on some upper-to-
245              lower  case  conversions.  Note that this has no support for any
246              Unicode characters.
247
248       -w, --wait-cr
249              Wait for the user or the modem to send a  carriage-return  or  a
250              linefeed  character  before sending the /etc/issue file (or oth‐
251              ers)  and  the  login  prompt.   This   is   useful   with   the
252              --init-string option.
253
254       --nohints
255              Do not print hints about Num, Caps and Scroll Locks.
256
257       --nohostname
258              By  default  the  hostname  will  be  printed.  With this option
259              enabled, no hostname at all will be shown.
260
261       --long-hostname
262              By default the hostname is only printed  until  the  first  dot.
263              With  this option enabled, the fully qualified hostname by geth‐
264              ostname(3P) or (if not found) by getaddrinfo(3) is shown.
265
266       --erase-chars string
267              This option  specifies  additional  characters  that  should  be
268              interpreted  as  a  backspace  ("ignore the previous character")
269              when the user types the  login  name.   The  default  additional
270              ´erase´  has  been  ´#´, but since util-linux 2.23 no additional
271              erase characters are enabled by default.
272
273       --kill-chars string
274              This option  specifies  additional  characters  that  should  be
275              interpreted  as  a  kill ("ignore all previous characters") when
276              the user types the login name.  The  default  additional  ´kill´
277              has been ´@´, but since util-linux 2.23 no additional kill char‐
278              acters are enabled by default.
279
280       --chdir directory
281              Change directory before the login.
282
283       --delay number
284              Sleep seconds before open tty.
285
286       --nice number
287              Run login with this priority.
288
289       --reload
290              Ask all running agetty instances to reload and update their dis‐
291              played  prompts,  if  the user has not yet commenced logging in.
292              After doing so the command will exit.   This  feature  might  be
293              unsupported on systems without Linux inotify(7).
294
295       --version
296              Display version information and exit.
297
298       --help Display help text and exit.
299

EXAMPLES

301       This  section  shows  examples for the process field of an entry in the
302       /etc/inittab file.  You'll have to prepend appropriate values  for  the
303       other fields.  See inittab(5) for more details.
304
305       For a hardwired line or a console tty:
306
307              /sbin/agetty 9600 ttyS1
308
309       For  a directly connected terminal without proper carrier-detect wiring
310       (try this if your terminal just sleeps instead of giving  you  a  pass‐
311       word: prompt):
312
313              /sbin/agetty --local-line 9600 ttyS1 vt100
314
315       For an old-style dial-in line with a 9600/2400/1200 baud modem:
316
317              /sbin/agetty --extract-baud --timeout 60 ttyS1 9600,2400,1200
318
319       For a Hayes modem with a fixed 115200 bps interface to the machine (the
320       example init string turns  off  modem  echo  and  result  codes,  makes
321       modem/computer DCD track modem/modem DCD, makes a DTR drop cause a dis‐
322       connection, and turns on auto-answer after 1 ring):
323
324       /sbin/agetty --wait-cr --init-string 'ATE0Q1&D2&C1S0=1 15' 115200 ttyS1
325
326

SECURITY NOTICE

328       If you use the --login-program and --login-options  options,  be  aware
329       that  a malicious user may try to enter lognames with embedded options,
330       which then get passed to the used login program.  Agetty does check for
331       a  leading  "-" and makes sure the logname gets passed as one parameter
332       (so embedded spaces will not create yet another parameter), but depend‐
333       ing  on  how the login binary parses the command line that might not be
334       sufficient.  Check that the used login program cannot  be  abused  this
335       way.
336
337       Some   programs  use "--" to indicate that the rest of the command line
338       should not be interpreted as options.  Use this feature if available by
339       passing "--" before the username gets passed by \u.
340
341

ISSUE FILES

343       The  default  issue  file is /etc/issue. If the file exists then agetty
344       also checks for  /etc/issue.d  directory.  The  directory  is  optional
345       extension  to  the  default  issue file and content of the directory is
346       printed after /etc/issue content. If the /etc/issue does not exist than
347       the  directory  is  ignored.  All  files with .issue extension from the
348       directory are printed in version-sort order.  The  directory  allow  to
349       maintain   3rd-party  messages  independently  on  the  primary  system
350       /etc/issue file.
351
352       Since version 2.35 additional locations for issue  file  and  directory
353       are  supported.  If  the  default /etc/issue does not exist than agetty
354       checks for /run/issue and /run/issue.d, thereafter  for  /usr/lib/issue
355       and /usr/lib/issue.d.  The directory /etc is expected for host specific
356       configuration, /run is expected for generated stuff  and  /usr/lib  for
357       static distribution maintained configuration.
358
359       The  default path maybe overridden by --issue-file option. In this case
360       specified path has to be file or directory and all  the  default  issue
361       file and directory locations are ignored.
362
363       The  issue  file feature is possible to completely disable by --noissue
364       option.
365
366       It is possible to review the current issue file by agetty  --show-issue
367       on the current terminal.
368
369       The  issue files may contain certain escape codes to display the system
370       name, date, time etcetera.  All escape codes consist of a backslash (\)
371       immediately followed by one of the characters listed below.
372
373
374       4 or 4{interface}
375              Insert  the IPv4 address of the specified network interface (for
376              example: \4{eth0}).  If the interface argument is not specified,
377              then  select the first fully configured (UP, non-LOCALBACK, RUN‐
378              NING) interface.  If not any configured interface is found, fall
379              back to the IP address of the machine's hostname.
380
381       6 or 6{interface}
382              The same as \4 but for IPv6.
383
384       b      Insert the baudrate of the current line.
385
386       d      Insert the current date.
387
388       e or e{name}
389              Translate  the  human-readable  name  to  an escape sequence and
390              insert it (for example: \e{red}Alert  text.\e{reset}).   If  the
391              name argument is not specified, then insert \033.  The currently
392              supported names are: black,  blink,  blue,  bold,  brown,  cyan,
393              darkgray,   gray,   green,   halfbright,  lightblue,  lightcyan,
394              lightgray, lightgreen,  lightmagenta,  lightred,  magenta,  red,
395              reset,  reverse,  and  yellow.   All  unknown names are silently
396              ignored.
397
398       s      Insert the system name (the name of the operating system).  Same
399              as 'uname -s'.  See also the \S escape code.
400
401       S or S{VARIABLE}
402              Insert  the  VARIABLE  data  from /etc/os-release.  If this file
403              does not exist then fall back to  /usr/lib/os-release.   If  the
404              VARIABLE  argument  is  not specified, then use PRETTY_NAME from
405              the file or the system name (see \s).  This escape  code  allows
406              to  keep  /etc/issue distribution and release independent.  Note
407              that \S{ANSI_COLOR} is converted to  the  real  terminal  escape
408              sequence.
409
410       l      Insert the name of the current tty line.
411
412       m      Insert  the  architecture  identifier  of  the machine.  Same as
413              'uname -m'.
414
415       n      Insert the nodename of the machine, also known as the  hostname.
416              Same as 'uname -n'.
417
418       o      Insert  the  NIS  domainname  of the machine.  Same as 'hostname
419              -d'.
420
421       O      Insert the DNS domainname of the machine.
422
423       r      Insert the release number of the OS.  Same as 'uname -r'.
424
425       t      Insert the current time.
426
427       u      Insert the number of current users logged in.
428
429       U      Insert the string "1 user" or "<n> users" where <n> is the  num‐
430              ber of current users logged in.
431
432       v      Insert the version of the OS, that is, the build-date and such.
433
434       An example.  On my system, the following /etc/issue file:
435
436              This is \n.\o (\s \m \r) \t
437
438       displays as:
439
440              This is thingol.orcan.dk (Linux i386 1.1.9) 18:29:30
441
442

FILES

444       /var/run/utmp
445              the system status file.
446
447       /etc/issue
448              printed before the login prompt.
449
450       /etc/os-release /usr/lib/os-release
451              operating system identification data.
452
453       /dev/console
454              problem reports (if syslog(3) is not used).
455
456       /etc/inittab
457              init(8) configuration file for SysV-style init daemon.
458

BUGS

460       The  baud-rate  detection  feature (the --extract-baud option) requires
461       that agetty be scheduled soon enough after completion of a dial-in call
462       (within  30  ms  with  modems that talk at 2400 baud).  For robustness,
463       always use the --extract-baud option in  combination  with  a  multiple
464       baud rate command-line argument, so that BREAK processing is enabled.
465
466       The  text  in  the  /etc/issue file (or other) and the login prompt are
467       always output with 7-bit characters and space parity.
468
469       The baud-rate detection feature (the  --extract-baud  option)  requires
470       that the modem emits its status message after raising the DCD line.
471

DIAGNOSTICS

473       Depending  on how the program was configured, all diagnostics are writ‐
474       ten to the console device  or  reported  via  the  syslog(3)  facility.
475       Error  messages  are  produced  if the port argument does not specify a
476       terminal device; if there is no utmp  entry  for  the  current  process
477       (System V only); and so on.
478

AUTHORS

480       Werner Fink ⟨werner@suse.de⟩
481       Karel Zak ⟨kzak@redhat.com⟩
482
483       The  original  agetty  for  serial terminals was written by W.Z. Venema
484       <wietse@wzv.win.tue.nl>  and  ported   to   Linux   by   Peter   Orbaek
485       <poe@daimi.aau.dk>.
486
487

AVAILABILITY

489       The  agetty  command is part of the util-linux package and is available
490       from https://www.kernel.org/pub/linux/utils/util-linux/.
491
492
493
494util-linux                       February 2016                       AGETTY(8)
Impressum