path: root/riemann.fmi.uni-sofia.bg/ngetty/ngetty.man

NGETTY(8)                                               NGETTY(8)


NAME
       ngetty - daemon for virtual console terminals

SYNOPSIS
       ngetty [ tty1 | vc/1 | 1 ] [ /dev/tty2 | vc/2 | 2 ] ...
       ngetty-helper /dev/ttyX [ login ]
       ngetty-argv :options:child:[name]:args [user [tty]]


DESCRIPTION
       ngetty  is  a daemon that starts login sessions on virtual
       console terminals, on demand.  It opens the  virtual  con-
       sole  terminals  specified  by the tty...  arguments, dis-
       plays a /etc/issue message, prints  the  login  prompt  on
       each  terminal  and  waits for user name.  On user action,
       ngetty executes login(1) in a new process with the  termi-
       nal the user is typing in as the controlling terminal.

       login(1)  then  prompts  for  a password to login with the
       system and finally, if the login  succeeds,  executes  the
       user's login shell.

       When  the user logs out, ngetty restarts the corresponding
       virtual console terminal.


       Actually almost the whole work is done by a  ngetty-helper
       program.   It  makes /var/run/utmp, /var/log/wtmp records,
       prints /etc/issue, hostname, login prompt, waits for  user
       name.  ngetty invokes the ngetty-helper by need.

HISTORY
       The  traditional  way  to enable logins on virtual console
       terminals is to start a bunch of  getty(8)  programs,  one
       for  each virtual console terminal, from init(8).  As most
       users rarely login on virtual console terminals  nowadays,
       preferring  graphical logins instead, it seems wasteful to
       have all those getty(8) processes doing nothing but  wast-
       ing  memory.   Alternatively, ngetty manages logins on any
       number of virtual console terminals from a single,  light,
       process.

INVOCATION
       ngetty  does  not  use  stdin, stdout or stderr and closes
       them.

       When running ngetty in the background, remember to  disas-
       sociate it from the current controlling terminal by making
       it the process group leader of a new session, e.g.:

           setsid ngetty tty...  &
           ngetty-argv :-D:-S:-e:--:/sbin/ngetty::1:2:3:4

       To start ngetty from init(8), add something like  this  to
       /etc/inittab:

              ng:2345:respawn:/sbin/ngetty tty1 tty2 ... tty6

       If  ngetty-argv  is  available use it to start ngetty from
       /etc/inittab.  See the example bellow.

DIAGNOSTICS
       If ngetty can not open one of the virtual  console  termi-
       nals  specified  in  the  tty...   arguments,  most likely
       because that tty device node does not exist,  no  greeting
       message will be displayed on that terminal, obviously, and
       ngetty will simply go on, ignoring the offending terminal.
       Create  the missing tty device and send SIGCHLD to ngetty.
       Then it will reopen  the  new  tty.   Instead  of  sending
       SIGCHLD  you  can  login  and  logout on some working tty.
       This also forces ngetty to reopen the new tty.


       ngetty uses ngetty-helper program.   It's  path  is  hard-
       coded  in  ngetty.  Never remove ngetty-helper program nor
       move it to other location.

       If,  on  user  action,  ngetty-helper  can   not   execute
       login(1),  in all likelihood because the compiled-in LOGIN
       path does not match your system's  login(1)  path,  ngetty
       restarts the terminal and redisplays the greeting message.

       In any case, ngetty does not output error messages.



OPTIONS
       It's possible to set different options  for  ngetty-helper
       program  in  file  /etc/ngetty/Conf.   If the option begin
       with "=" it's applied for all tty.  If it start with a tty
       name it's applied only on current tty.  Examples:

              # options format:
              # [ttyX]=option[=value]
              #=debug
              =environ=,TERM=linux
              tty3=long-hostname
              tty1=clear=\033c
              =newline=
              =timeout=180
              tty1=timeout=60
              tty1=delay=1

       For  security  reasons  ngetty-helper  evaluate  the  file
       /etc/ngetty/Conf only if it has mode:

              -rw-------    root   root   /etc/ngetty/Conf

       ngetty-helper recognizes the following options which might
       be embedded in the /etc/ngetty/Conf file:

       # tty5=login-prog=/bin/login.test
              If  a line starts with #, space or tab it is a com-
              ment.

       debug  If debug is set ngetty-helper write on terminal all
              successfully applied options.  Set this on the fist
              line of /etc/ngetty/Conf file.

       date-string
              Escape \d (current day) in /etc/issue as:
              Fri Jun 01 2007.  Default is: 2007-06-01.

       days=string
              Abbreviation for week days (21 bytes).  Default is:
              =days=SunMonTueWedThuFriSat

       months=string
              Abbreviation for months (36 bytes).  Default is:
              =months=JanFebMarAprMayJunJulAugSepOctNovDec

       tz=string
              Change  the  timezone offset.  If the string starts
              with slash it's the name of tzfile.  The string  is
              positive  number  if the local time zone is east of
              the Prime Meridian and  negative  if  it  is  west.
              Default is /etc/localtime.  Examples:
              =tz=-18000        -0500
              =tz=7200          +0200
              =tz=/etc/localtime
              =tz=AUTO

       echo-off
              Turn  the echo off just before starting /bin/login.
              It's similar to stty -echo.

       newline=string
              Print this string before  writing  out  /etc/issue.
              (default is \012).  Example:
              tty3=newline=\012I am \l\012

       clear=string
              Clear  the  screen  before  prompting for the login
              name with the string (default is \033c).  Examples:
              tty1=clear=
              tty3=clear=\033[H\033[J

       noclear-first=/etc/ngetty/.noclear
              Do  not  clear  the screen before prompting for the
              login name the first time after reboot.  Example:
              tty1=noclear-first=/etc/ngetty/.noclear.tty1

       nohangup
              Do not call vhangup() to disable  writing  to  this
              tty by other applications.

       long-hostname
              By  default  the hostname is only printed until the
              first dot.  With this option enabled, the full text
              from gethostname() is shown.

       nousername
              Do  not  ask  for user name.  Exec login(1) immedi-
              ately.  Example:
              =nousername
              =login-prompt= Press ENTER to activate \l

       deny=,black,list,users...
              Disable login process for some  users.   The  first
              char after "deny=" is split char.  Example:
              tty1=deny=,root,nobody,guest

       allow=,white,list,users...
              Enable login process only for the users.  The first
              char after "allow=" is split char.  Example:
              =clear=
              =allow=,root,operator

       print=an:CM:PY:04:69
              Accept only these chars in user name.   Default  is
              to  accept  only ",-._ 0-9 a-z A-Z".  It's possible
              to insert here the output of
              printf 'tty3=print=az:AZ:\ABC\XYZ:__'
              Here ABC and XYZ are octal numbers.  Examples:
              tty1=print=az:AZ
              tty2=print=az:AZ:__:,.:09

       issue-file=/etc/issue
              Change the issue file.   Disable  printing  of  the
              issue file with:
              =issue-file=

       login-prog=/bin/login
              Change   the  login  app.   It's  possible  to  use
              fgetty's /bin/login1 application with:
              =echo-off
              =login-prog=/bin/login1

       login-buffer=string
              Read login name over the string.  Default string is
              40 bytes long.  Example:
              =login-buffer=12345678901234567

       login-prompt=\n login:
              Change the login prompt string.  Example:
              =login-prompt=\033[1;33m\l\033[0;39m  \n login:

       nice=10
              Change the priority by calling nice().

       delay=5
              Sleep  this  many  seconds before printing the file
              /etc/issue.

       timeout=180
              Wait at most this many seconds for user name.

       chdir=/home
              Change into this directory before calling the login
              prog.

       chroot=/chroot
              Call chroot() with this directory name.

       autologin-name=username
              Log  the  specified  user  automatically in without
              asking for a login name and password.  Check the -f
              option from /bin/login for this.  Example:
              tty1=autologin-name=maria

       autologin-first=/etc/ngetty/.autologin
              Log  in  automatically  only  the  first time after
              reboot without asking for a login  name  and  pass-
              word.  Example:
              tty1=autologin-name=maria
              tty1=autologin-first=/etc/ngetty/.autologin

       environ=,TERM=linux
              Replace  the  environ.  The first char after "envi-
              ron=" is split char.  Examples:
              =environ=,TERM=vt100,PATH=/bin:/usr/bin,HOME=/
              tty3=environ=,TERM=linux,TTY=/dev/tty3

       sh-A=line
              Exec this line  before  printing  /etc/issue.   The
              line  is executed using /bin/sh -c line.  It's good
              idea to use the full paths here.  Example:
              tty4=sh-A=exec /bin/ps e -u root
              tty4=delay=8

       sh-B=line
              Similar to option sh-A.  This  is  executed  before
              asking for username.

       login-argv=any_string
              Ngetty starts login application with options
              login -- XYZ      # default
              login -f XYZ      # if autologin-name=XYZ
              With  this option it's possible to start login appl
              with any_string instead of --  or  -f.   Using  the
              program ngetty-argv(8) one can start arbitrary pro-
              gram with different arguments.  Two very  dangerous
              examples are (never try them):
              tty4=login-prog=/sbin/ngetty-argv
              tty5=login-prog=/sbin/ngetty-argv
              tty4=login-argv=,/bin/login,,-f,%U
              tty5=login-argv=:-C:/bin/bash:-bash


WARNING
       If  ngetty-helper  finds  stdout  or  stderr open it exits
       immediately with error 100.  Ngetty invokes it  correctly.
       See also the program test-helper.c in source package.

       Do  not  edit the file /etc/ngetty/Conf directly.  Put the
       configurations in /etc/ngetty/Conf.sed  (the  same  syntax
       and permissions as /etc/ngetty/Conf) and after editing it,
       execute:

              cd /etc/ngetty && ./setup

       The  script  /etc/ngetty/setup  removes  comments,  merges
       lines  ending  with  a  backslash  and  expands the string
       =tz=AUTO   to   numeric   number.    Then    it    updates
       /etc/ngetty/Conf.


SIGNALS
       If  ngetty receives SIGTERM it kill all child's PID (first
       with SIGTERM and then with SIGKILL) and exit  immediately.
       It  does  not  change UID, GID and mode of the controlling
       tty devices.  It does not catch the other signals.   Send-
       ing  SIGCHLD  to  ngetty  forces it to reread his internal
       cache tables and to restart failed tty devices.


ISSUE ESCAPES
       ngetty-helper recognizes the following  escapes  sequences
       which  might  be  embedded after  login-prompt=, newline=,
       clear= or in the /etc/issue file:

       \d     insert current day (localtime),

       \l     insert line on which ngetty is running,

       \m     inserts machine architecture (uname -m),

       \n     inserts machine's network node hostname (uname -n),

       \o     inserts domain name,

       \r     inserts operating system release (uname -r),

       \t     insert current time (localtime),

       \s     inserts operating system name,

       \u     insert  the  number  of  users  which are currently
              logged in,

       \U     insert the  string  "1 user" or "<n> users",  where
              <n> is the number of users currently logged  in,

       \v     inserts operating system version (uname -v).

       \XYZ   inserts a letter with octal code XYZ.


EXAMPLE
       "Linux eos i386 #1 Tue Mar 19 21:54:09 MET 1996"  was pro-
       duced by putting "\s \n \m \v" into /etc/issue.


NGETTY-ARGV
       The program  ngetty-argv(8)  splits  argv[1]  on  strings,
       expands  %U  and %T to username and tty and then start the
       the application.  The first char  after  "login-argv="  is
       split char.  In the examples above every user logs on tty4
       without password and tty5 is always root.   To  understand
       better how ngetty-argv works try as non-root:

       ngetty-argv ':/bin/echo:echo:%U: on %T' usr tty3
       ngetty-argv ':/bin/sleep:-hacker:39:I am %U on %T' 123 X


       One can put also options for ngetty-argv at the beginning.

              --         last option

              -u503      setuid to 503

              -g230      setgid to 230

              -a120      exec alarm(120) before starting child

              -s10       sleep 10 secs before starting child

              -d/X/YZ    chdir(/X/YZ)  before starting child

              -r/A/BC    chroot(/A/BC) before starting child

              -D         start the child in background and exit

              -N -C      NOTTY | SCTTY controlling tty

              -S         like setsid(8)

              -e,HOME=/,TERM=linux     same as environ= above

              -p/path/to/pid.file      write the child pid here

       One possible example for /etc/ngetty/Conf is:
           tty9=clear=
           tty9=issue-file=
           tty9=login-prompt=\n  \d \t  qmail-qread:
           tty9=login-prog=/sbin/ngetty-argv
           tty9=login-argv=:-u106:-g503:-d/var/qmail:--
             :./bin/qmail-qread:qread

       Another example is setting the TTY environ automatically:
           =login-prog=/sbin/ngetty-argv
           =login-argv=:-e,TTY=/dev/%T,TERM=linux:--
             :/bin/login:login-%T:--:%U

       I recommend using ngetty-argv  in /etc/inittab also.   Put
       as  last  argument  runlevel  string.   Then  ps will show
       ngetty-2345 instead of ngetty.  Next start tty1  ...  tty6
       on runlevels 2345.
           ng:2345:respawn:/sbin/ngetty-argv
             .-e.-S.-d/.-s1.--./sbin/%U.%U-%T.1.2.3.4.5.6
             ngetty 2345

       On a terminal (in scripts) start ngetty with
           ngetty-argv .-N.-S.-e./sbin/%U.%U.8.9.10 ngetty
           ngetty-argv .-D.-S.-e./sbin/%U.%U.8.9.10 ngetty

       This  program  is a hack written for ngetty-helper.  There
       is no additional code in ngetty-helper and  it's  possible
       to  start  a  program  with any args.  It is like a filter
       between ngetty-helper and login application.  One can easy
       modify it without touching ngetty-helper.  It's similar to
       DJB well known argv0(1) and setuidgid(8).  You  can  write
       own such programs and use them instead of ngetty-argv.

FILES
       /etc/ngetty/Conf        ngetty-helper configuration file
       /etc/ngetty/Conf.sed    private setup file
       /etc/ngetty/setup       updates Conf.sed -> Conf
       /etc/issue              printed before the login prompt
       /var/run/utmp           the system status file
       /var/log/wtmp           the system logging file
       /etc/inittab            init(8) configuration file


SEE ALSO
       getty(8) fgetty(8) mingetty(8)
       login(1) nlogin(1) argv0(1) setuidgid(8) stty(1)
       http://sites.google.com/site/anbadeol/logind

AUTHOR
       Nikola Vladov
       http://riemann.fmi.uni-sofia.bg/ngetty/

COPYRIGHT
       Copyright 2007,2008,2010 Nikola Vladov

       This  program  is  free  software; you can redistribute it
       and/or modify it under the terms of the GNU General Public
       License  as  published  by  the  Free Software Foundation;
       either version 2 of the License, or (at your  option)  any
       later version.

       This  program  is  distributed in the hope that it will be
       useful, but WITHOUT ANY WARRANTY; without even the implied
       warranty  of  MERCHANTABILITY  or FITNESS FOR A PARTICULAR
       PURPOSE.  See the GNU  General  Public  License  for  more
       details.