summary refs log tree commit diff
path: root/login
diff options
context:
space:
mode:
Diffstat (limited to 'login')
-rw-r--r--login/Makefile2
-rw-r--r--login/README.utmpd174
-rw-r--r--login/programs/utmpd.c6
3 files changed, 178 insertions, 4 deletions
diff --git a/login/Makefile b/login/Makefile
index 407330707b..3842b2f4af 100644
--- a/login/Makefile
+++ b/login/Makefile
@@ -32,7 +32,7 @@ install-sbin = utmpd
 utmpd-routines := connection database error request xtmp
 extra-objs := $(utmpd-routines:=.o)
 
-distribute := utmp-private.h programs/xtmp.h programs/utmpd.h \
+distribute := utmp-private.h programs/xtmp.h programs/utmpd.h README.utmpd \
 	      programs/utmpd-private.h $(utmpd-routines:%=programs/%.c)
 
 subdir-dirs = programs
diff --git a/login/README.utmpd b/login/README.utmpd
new file mode 100644
index 0000000000..d70b3d8de2
--- /dev/null
+++ b/login/README.utmpd
@@ -0,0 +1,174 @@
+With the introduction of version 2 of the GNU C Library the format of
+the UTMP and WTMP files changed for some configurations (see Q&A 10 of
+the FAQ).  This version of the GNU C Library contains a solution for
+the problems this may cause, by providing an UTMP daemon `utmpd'.
+
+Do I need it?
+=============
+
+If your configuration is one of the following:
+
+                i[3456]86-*-linux-gnu    Linux-2.0 on Intel
+                m68k-*-linux-gnu         Linux-2.0 on Motorola 680x0
+
+you might need it, so please read on.  If it is not, please read the
+section titled `Programming' at the end of this text.
+
+In principle, you only need the daemon if you want to keep using old
+programs linked against the previous version of the Linux C Library
+(libc5).  In addition you will need the daemon if you are running
+Linux on Intel, and you are planning to use iBCS (Intel Binary
+Compatibility Standard).  If you have no libc5 programs left on your
+system and you are not using iBCS, it is probably better not to
+install the daemon since it uses (a small amount of) memory and CPU
+time.  But apart from that it shouldn't hurt to install `utmpd', so
+when in doubt install it anyway.
+
+
+Installation
+============
+
+The installation process (`make install') already places the `utmpd'
+binary in $(sbindir).  The only thing you have to do is modifying your
+startup scripts to start the daemon.  Unfortunately this is a bit of a
+hassle, since the layout of these scripts is not standardized.  You
+should try to find the command that creates the file `/var/run/utmp'.
+This is usually done in a script named `/etc/rc', `/etc/init.d/boot'
+(Debian) or `/etc/rc.d/rc.S' (Slackware).  You could try:
+
+     grep utmp /etc/* /etc/init.d/* /etc/rc.d/*
+
+to find the right script.  The creation of `/var/run/utmp' is usually
+done with a command like:
+
+     : > /var/run/utmp
+
+or
+
+     cat /dev/null > /var/run/utmp
+
+Now add a line before this command to create the file `/var/run/utmpx'
+e.g.
+
+     : > /var/run/utmpx
+
+or
+
+     cat /dev/null > /var/run/utmpx
+
+whatever you prefer, and after this command, add a line to start the
+daemon
+
+     utmpd
+
+The entire fragment could look something like
+
+     # Clean up /var/run and create /var/run/utmp so that we can login.
+     ( cd /var/run && find . ! -type d -exec rm -f -- {} \; )
+     : > /var/run/utmpx
+     : > /var/run/utmp
+     utmpd
+
+If the file `/var/log/wtmp' exists on your system, you will probably
+want to create the file `/var/log/wtmpx'.  Programs linked against the
+GNU C Library will now write to `/var/log/wtmpx', while programs
+linked against the old library will continue to write to
+`/var/log/wtmp'.  Of course this means that the information gets
+spread over two files.  We hope to provide a better solution in the
+future.
+
+After a reboot, user accounting should be working again.  If not,
+please refer to the section titled `Troubleshooting' below before
+submitting a bug report.
+
+
+What is `utmpd' doing?
+======================
+
+After installation there will be two files that store the user
+accounting information: `/var/run/utmp' and `/var/run/utmpx'.  The
+file `/var/run/utmp' will be in the old format so libc5 programs will
+continue to work (even if they are broken and do not use the library
+functions to access the user accounting database).  And on Intel, you
+can safely link `/var/run/utmp' to `/etc/utmp' for iBCS programs.
+Programs linked against the new GNU C Library (glibc2) will contact
+the daemon for all user accounting database access.  The daemon will
+store its information in `/var/run/utmpx' and keeps this file in sync
+with `/var/run/utmp'.  Entries added to `/var/run/utmpx' will be
+converted to the old format and will be added to `/var/run/utmp' and
+vice versa.  This way both libc5 and glibc2 see the same information
+in the same fields of `struct utmp'. Of course libc5 programs see only
+part of the information that glibc2 programs see because not all
+members of the glibc2 `struct utmp' are present in the libc5 `struct
+utmp'.  For the same reason libc5 will see a truncated version of
+those fields where the length of the glibc2 field is larger than the
+corresponding libc5 field (ut_user, ut_line, ut_host).
+
+
+Troubleshooting
+===============
+
+If user accounting is not working on your system, e.g. programs like
+`who' or `logname' return rubbish, or you cannot login, make
+sure that:
+
+*  The file `/var/run/utmpx' exists.
+
+*  The file `/var/log/wtmpx' exists.
+
+*  No program linked against the GNU C Library (libc6) is accessing
+   `/var/run/utmp' directly (see the section on `Programming' below).
+
+If that does not solve your problems, please use the `glibcbug' script
+to report the problem to <bugs@gnu.org>.
+
+The `utmpd' daemon uses `syslogd' to report problems.  It uses the
+`daemon' facility and `warning' and `error' levels.  Alternatively you
+could use the following option to ease debugging:
+
+`--debug'
+    Use this option if you want the daemon to output its warnings and
+    error messages to the terminal instead of sending them to the
+    system logger (`syslogd').  When using this option the daemon does
+    not auto-background itself.
+
+To use this option you should first kill the daemon that is already
+running, and start a fresh one with the desired option:
+
+    kill `cat /var/run/utmpd.pid`
+    utmpd --debug
+
+Please include any warnings or error messages from `utmpd' in your
+bug reports.
+
+
+Programming
+===========
+
+In order for the `utmpd' approach to work it is essential that NO
+program EVER accesses the UTMP and WTMP files directly.  Instead, a
+program should use ONLY the available library functions:
+
+     * utmpname()	Select the database used (UTMP, WTMP, ...).
+     * setutent()	Open the database.
+     * getutent()	Read the next entry from the database.
+     * getutid()	Search for the next entry with a specific ID.
+     * getutline()	Search for the next entry for a specific line.
+     * pututline()	Write an entry to the database.
+     * endutent()	Close the database.
+     * updwtmp()	Add an entry to a database (WTMP, ...).
+
+For details, please refer to `The GNU C Library Reference Manual',
+which also contains information about some additional functions
+derived from BSD and XPG that may be of interest.  The command
+
+    info libc "User Accounting Database"
+
+should point you at the right location.
+
+If you encounter a program that reads from or, even worse, writes to
+the UTMP and WTMP files directly, please report this as a bug to the
+author of that program.  Note that the files referred to by the macros
+`_PATH_UTMP' and `_PATH_WTMP' might even disappear in the future, so
+please do not use these, except in a call to `utmpname()' or
+`updwtmp()', not even to check their existence.
diff --git a/login/programs/utmpd.c b/login/programs/utmpd.c
index e0648ebb42..c2e9fe0a8b 100644
--- a/login/programs/utmpd.c
+++ b/login/programs/utmpd.c
@@ -144,7 +144,7 @@ warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n\
   /* Cleanup files created by a previous `bind'.  */
   unlink (_PATH_UTMPD_RO);
   unlink (_PATH_UTMPD_RW);
-  
+
   /* Open UTMP database.  */
   utmp_db = open_database (_PATH_UTMP "x", _PATH_UTMP);
   if (utmp_db == NULL)
@@ -205,7 +205,7 @@ Usage: %s [OPTION]...\n\
   -V, --version         output version information and exit\n"),
 	      program_invocation_name);
       fputs (_("\
-Report bugs using the `glibcbug' script to <bugs@gnu.ai.mit.edu>.\n"),
+Report bugs using the `glibcbug' script to <bugs@gnu.org>.\n"),
 	     stdout);
     }
 
@@ -252,7 +252,7 @@ make_socket (const char *name)
   size = (offsetof (struct sockaddr_un, sun_path)
 	  + strlen (addr.sun_path));
 
-  
+
   if (bind (sock, (struct sockaddr *) &addr, size) < 0)
     error (EXIT_FAILURE, errno, "%s", name);