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