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

EXAMPLES

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

SECURITY NOTICE

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

ISSUE FILES

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

FILES

424       /var/run/utmp
425              the system status file.
426
427       /etc/issue
428              printed before the login prompt.
429
430       /etc/os-release /usr/lib/os-release
431              operating system identification data.
432
433       /dev/console
434              problem reports (if syslog(3) is not used).
435
436       /etc/inittab
437              init(8) configuration file for SysV-style init daemon.
438

BUGS

440       The baud-rate detection feature (the  --extract-baud  option)  requires
441       that agetty be scheduled soon enough after completion of a dial-in call
442       (within 30 ms with modems that talk at  2400  baud).   For  robustness,
443       always  use  the  --extract-baud  option in combination with a multiple
444       baud rate command-line argument, so that BREAK processing is enabled.
445
446       The text in the /etc/issue file (or other) and  the  login  prompt  are
447       always output with 7-bit characters and space parity.
448
449       The  baud-rate  detection  feature (the --extract-baud option) requires
450       that the modem emits its status message after raising the DCD line.
451

DIAGNOSTICS

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

AUTHORS

460       Werner Fink ⟨werner@suse.de⟩
461       Karel Zak ⟨kzak@redhat.com⟩
462
463       The original agetty for serial terminals was  written  by  W.Z.  Venema
464       <wietse@wzv.win.tue.nl>   and   ported   to   Linux   by  Peter  Orbaek
465       <poe@daimi.aau.dk>.
466
467

AVAILABILITY

469       The agetty command is part of the util-linux package and  is  available
470       from https://www.kernel.org/pub/linux/utils/util-linux/.
471
472
473
474util-linux                       February 2016                       AGETTY(8)
Impressum