login/README.utmpd

   1 With the introduction of version 2 of the GNU C Library the format of
   2 the UTMP and WTMP files changed for some configurations (see Q&A `Why
   3 does getlogin() always return NULL on my Linux box?' of the FAQ).
   4 This version of the GNU C Library contains a solution for the problems
   5 this may cause, by providing an UTMP daemon `utmpd'.
   6
   7 Do I need it?
   8 =============
   9
  10 If your configuration is one of the following:
  11
  12                 i[3456]86-*-linux-gnu    Linux-2.0 on Intel
  13                 m68k-*-linux-gnu         Linux-2.0 on Motorola 680x0
  14
  15 you might need it, so please read on.  If it is not, please read the
  16 section titled `Programming' at the end of this text.
  17
  18 In principle, you only need the daemon if you want to keep using old
  19 programs linked against the previous version of the Linux C Library
  20 (libc5).  In addition you will need the daemon if you are running
  21 Linux on Intel, and you are planning to use iBCS (Intel Binary
  22 Compatibility Standard).  If you have no libc5 programs left on your
  23 system and you are not using iBCS, it is probably better not to
  24 install the daemon since it uses (a small amount of) memory and CPU
  25 time.  But apart from that it shouldn't hurt to install `utmpd', so
  26 when in doubt install it anyway.
  27
  28
  29 Installation
  30 ============
  31
  32 The installation process (`make install') already places the `utmpd'
  33 binary in $(sbindir).  The only thing you have to do is modifying your
  34 startup scripts to start the daemon.  Unfortunately this is a bit of a
  35 hassle, since the layout of these scripts is not standardized.  You
  36 should try to find the command that creates the file `/var/run/utmp'.
  37 This is usually done in a script named `/etc/rc', `/etc/init.d/boot'
  38 (Debian) or `/etc/rc.d/rc.S' (Slackware).  You could try:
  39
  40      grep utmp /etc/* /etc/init.d/* /etc/rc.d/*
  41
  42 to find the right script.  The creation of `/var/run/utmp' is usually
  43 done with a command like:
  44
  45      : > /var/run/utmp
  46
  47 or
  48
  49      cat /dev/null > /var/run/utmp
  50
  51 Now add a line before this command to create the file `/var/run/utmpx'
  52 e.g.
  53
  54      : > /var/run/utmpx
  55
  56 or
  57
  58      cat /dev/null > /var/run/utmpx
  59
  60 whatever you prefer, and after this command, add a line to start the
  61 daemon
  62
  63      utmpd
  64
  65 The entire fragment could look something like
  66
  67      # Clean up /var/run and create /var/run/utmp so that we can login.
  68      ( cd /var/run && find . ! -type d -exec rm -f -- {} \; )
  69      : > /var/run/utmpx
  70      : > /var/run/utmp
  71      utmpd
  72
  73 If the file `/var/log/wtmp' exists on your system, you will probably
  74 want to create the file `/var/log/wtmpx'.  Programs linked against the
  75 GNU C Library will now write to `/var/log/wtmpx', while programs
  76 linked against the old library will continue to write to
  77 `/var/log/wtmp'.  Of course this means that the information gets
  78 spread over two files.  We hope to provide a better solution in the
  79 future.
  80
  81 After a reboot, user accounting should be working again.  If not,
  82 please refer to the section titled `Troubleshooting' below before
  83 submitting a bug report.
  84
  85
  86 What is `utmpd' doing?
  87 ======================
  88
  89 After installation there will be two files that store the user
  90 accounting information: `/var/run/utmp' and `/var/run/utmpx'.  The
  91 file `/var/run/utmp' will be in the old format so libc5 programs will
  92 continue to work (even if they are broken and do not use the library
  93 functions to access the user accounting database).  And on Intel, you
  94 can safely link `/var/run/utmp' to `/etc/utmp' for iBCS programs.
  95 Programs linked against the new GNU C Library (glibc2) will contact
  96 the daemon for all user accounting database access.  The daemon will
  97 store its information in `/var/run/utmpx' and keeps this file in sync
  98 with `/var/run/utmp'.  Entries added to `/var/run/utmpx' will be
  99 converted to the old format and will be added to `/var/run/utmp' and
 100 vice versa.  This way both libc5 and glibc2 see the same information
 101 in the same fields of `struct utmp'. Of course libc5 programs see only
 102 part of the information that glibc2 programs see because not all
 103 members of the glibc2 `struct utmp' are present in the libc5 `struct
 104 utmp'.  For the same reason libc5 will see a truncated version of
 105 those fields where the length of the glibc2 field is larger than the
 106 corresponding libc5 field (ut_user, ut_line, ut_host).
 107
 108
 109 Troubleshooting
 110 ===============
 111
 112 If user accounting is not working on your system, e.g. programs like
 113 `who' or `logname' return rubbish, or you cannot login, make
 114 sure that:
 115
 116 *  The file `/var/run/utmpx' exists.
 117
 118 *  The file `/var/log/wtmpx' exists.
 119
 120 *  No program linked against the GNU C Library (libc6) is accessing
 121    `/var/run/utmp' directly (see the section on `Programming' below).
 122
 123 If that does not solve your problems, please use the `glibcbug' script
 124 to report the problem to <bugs@gnu.org>.
 125
 126 The `utmpd' daemon uses `syslogd' to report problems.  It uses the
 127 `daemon' facility and `warning' and `error' levels.  Alternatively you
 128 could use the following option to ease debugging:
 129
 130 `--debug'
 131     Use this option if you want the daemon to output its warnings and
 132     error messages to the terminal instead of sending them to the
 133     system logger (`syslogd').  When using this option the daemon does
 134     not auto-background itself.
 135
 136 To use this option you should first kill the daemon that is already
 137 running, and start a fresh one with the desired option:
 138
 139     kill `cat /var/run/utmpd.pid`
 140     utmpd --debug
 141
 142 Please include any warnings or error messages from `utmpd' in your
 143 bug reports.
 144
 145
 146 Programming
 147 ===========
 148
 149 In order for the `utmpd' approach to work it is essential that NO
 150 program EVER accesses the UTMP and WTMP files directly.  Instead, a
 151 program should use ONLY the available library functions:
 152
 153      * utmpname()       Select the database used (UTMP, WTMP, ...).
 154      * setutent()       Open the database.
 155      * getutent()       Read the next entry from the database.
 156      * getutid()        Search for the next entry with a specific ID.
 157      * getutline()      Search for the next entry for a specific line.
 158      * pututline()      Write an entry to the database.
 159      * endutent()       Close the database.
 160      * updwtmp()        Add an entry to a database (WTMP, ...).
 161
 162 For details, please refer to `The GNU C Library Reference Manual',
 163 which also contains information about some additional functions
 164 derived from BSD and XPG that may be of interest.  The command
 165
 166     info libc "User Accounting Database"
 167
 168 should point you at the right location.
 169
 170 If you encounter a program that reads from or, even worse, writes to
 171 the UTMP and WTMP files directly, please report this as a bug to the
 172 author of that program.  Note that the files referred to by the macros
 173 `_PATH_UTMP' and `_PATH_WTMP' might even disappear in the future, so
 174 please do not use these, except in a call to `utmpname()' or
 175 `updwtmp()', not even to check their existence.