raw/man5/utmp.5

   1 .\" Copyright (c) 1993 Michael Haardt (michael@cantor.informatik.rwth-aachen.de), Fri Apr  2 11:32:09 MET DST 1993
   2 .\"
   3 .\" This is free documentation; you can redistribute it and/or
   4 .\" modify it under the terms of the GNU General Public License as
   5 .\" published by the Free Software Foundation; either version 2 of
   6 .\" the License, or (at your option) any later version.
   7 .\"
   8 .\" The GNU General Public License's references to "object code"
   9 .\" and "executables" are to be interpreted as the output of any
  10 .\" document formatting or typesetting system, including
  11 .\" intermediate and printed output.
  12 .\"
  13 .\" This manual is distributed in the hope that it will be useful,
  14 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 .\" GNU General Public License for more details.
  17 .\"
  18 .\" You should have received a copy of the GNU General Public
  19 .\" License along with this manual; if not, write to the Free
  20 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
  21 .\" USA.
  22 .\"
  23 .\" Modified Sun Jul 25 10:44:50 1993 by Rik Faith (faith@cs.unc.edu)
  24 .\" Modified Thu Feb 26 16:08:49 MET 1995 by Michael Haardt
  25 .\" Modified Sat Jul 20 14:39:03 MET DST 1996 by Michael Haardt
  26 .\" Modified Wed Jul  2 20:20:53 ART 1997 by Nicol?s Lichtmaier <nick@debian.org>
  27 .TH UTMP 5 1997-07-02 "" "File formats"
  28 .SH NAME
  29 utmp, wtmp \- login records
  30 .SH SYNOPSIS
  31 #include <utmp.h>
  32 .SH DESCRIPTION
  33 The
  34 .I utmp
  35 file allows one to discover information about who is currently using the
  36 system.  There may be more users currently using the system, because not
  37 all programs use utmp logging.
  38 .PP
  39 .B Warning:
  40 .I utmp
  41 must not be writable, because many system programs (foolishly)
  42 depend on its integrity.  You risk faked system logfiles and
  43 modifications of system files if you leave
  44 .I utmp
  45 writable to any user.
  46 .PP
  47 The file is a sequence of entries with the following structure declared
  48 in the include file (note that this is only one of several definitions
  49 around; details depend on the version of libc):
  50 .RS
  51 .nf
  52 .sp
  53 .ta 3i
  54 #define UT_UNKNOWN      0
  55 #define RUN_LVL         1
  56 #define BOOT_TIME       2
  57 #define NEW_TIME        3
  58 #define OLD_TIME        4
  59 #define INIT_PROCESS    5
  60 #define LOGIN_PROCESS   6
  61 #define USER_PROCESS    7
  62 #define DEAD_PROCESS    8
  63 #define ACCOUNTING      9
  64
  65 #define UT_LINESIZE     12
  66 #define UT_NAMESIZE     32
  67 #define UT_HOSTSIZE     256
  68
  69 struct exit_status {
  70   short int e_termination;      /* process termination status.  */
  71   short int e_exit;     /* process exit status.  */
  72 };
  73
  74 struct utmp {
  75   short ut_type;        /* type of login */
  76   pid_t ut_pid; /* pid of login process */
  77   char ut_line[UT_LINESIZE];    /* device name of tty \- "/dev/" */
  78   char ut_id[4];        /* init id or abbrev. ttyname */
  79   char ut_user[UT_NAMESIZE];    /* user name */
  80   char ut_host[UT_HOSTSIZE];    /* hostname for remote login */
  81   struct exit_status ut_exit;   /* The exit status of a process
  82            marked as DEAD_PROCESS. */
  83   long ut_session;      /* session ID, used for windowing*/
  84   struct timeval ut_tv; /* time entry was made.  */
  85   int32_t ut_addr_v6[4];        /* IP address of remote host.  */
  86   char pad[20]; /* Reserved for future use.  */
  87 };
  88
  89 /* Backwards compatibility hacks.  */
  90 #define ut_name ut_user
  91 #ifndef _NO_UT_TIME
  92 #define ut_time ut_tv.tv_sec
  93 #endif
  94 #define ut_xtime ut_tv.tv_sec
  95 #define ut_addr ut_addr_v6[0]
  96 .sp
  97 .fi
  98 .RE
  99 This structure gives the name of the special file associated with the
 100 user's terminal, the user's login name, and the time of login in the form
 101 of
 102 .BR time (2).
 103 String fields are terminated by \fB'\e0'\fP if they are shorter than the size
 104 of the field.
 105 .PP
 106 The first entries ever created result from
 107 .BR init (8)
 108 processing
 109 .BR inittab (5).
 110 Before an entry is processed, though,
 111 .BR init (8)
 112 cleans up utmp by setting \fIut_type\fP to \fBDEAD_PROCESS\fP, clearing
 113 \fIut_user\fP, \fIut_host\fP, and \fIut_time\fP with null bytes for each
 114 record which \fIut_type\fP is not \fBDEAD_PROCESS\fP or \fBRUN_LVL\fP
 115 and where no process with PID \fIut_pid\fP exists.  If no empty record
 116 with the needed \fIut_id\fP can be found, init creates a new one.  It
 117 sets \fIut_id\fP from the inittab, \fIut_pid\fP and \fIut_time\fP to the
 118 current values, and \fIut_type\fP to \fBINIT_PROCESS\fP.
 119 .PP
 120 .BR getty (8)
 121 locates the entry by the pid, changes \fIut_type\fP to
 122 \fBLOGIN_PROCESS\fP, changes \fIut_time\fP, sets \fIut_line\fP, and waits
 123 for connection to be established.
 124 .BR login (8),
 125 after a user has been
 126 authenticated, changes \fIut_type\fP to \fBUSER_PROCESS\fP, changes
 127 \fIut_time\fP, and sets \fIut_host\fP and \fIut_addr\fP.  Depending on
 128 .BR getty (8)
 129 and
 130 .BR login (8),
 131 records may be located by
 132 \fIut_line\fP instead of the preferable \fIut_pid\fP.
 133 .PP
 134 When
 135 .BR init (8)
 136 finds that a process has exited, it locates its utmp
 137 entry by \fIut_pid\fP, sets \fIut_type\fP to \fBDEAD_PROCESS\fP, and
 138 clears \fIut_user\fP, \fIut_host\fP and \fIut_time\fP with null bytes.
 139 .PP
 140 .BR xterm (1)
 141 and other terminal emulators directly create a
 142 \fBUSER_PROCESS\fP record and generate the \fIut_id\fP by using the last
 143 two letters of \fI/dev/ttyp\fP\fI%c\fP or by using \fIp\fP\fI%d\fP for
 144 \fI/dev/pts/\fP\fI%d\fP.  If they find a \fBDEAD_PROCESS\fP for this id,
 145 they recycle it, otherwise they create a new entry.  If they can, they
 146 will mark it as \fBDEAD_PROCESS\fP on exiting and it is advised that
 147 they null \fIut_line\fP, \fIut_time\fP, \fIut_user\fP, and \fIut_host\fP
 148 as well.
 149 .PP
 150 \fIxdm\fP(8) should not create a utmp record, because there is no
 151 assigned terminal.  Letting it create one will result in errors, such
 152 as 'finger: cannot stat /dev/machine.dom'.  It should create wtmp entries,
 153 though, just like
 154 .BR ftpd (8)
 155 does.
 156 .PP
 157 .BR telnetd (8)
 158 sets up a \fBLOGIN_PROCESS\fP entry and leaves the rest to
 159 .BR login (8)
 160 as usual.  After the telnet session ends,
 161 .BR telnetd (8)
 162 cleans up utmp in the described way.
 163 .PP
 164 The \fIwtmp\fP file records all logins and logouts.  Its format is
 165 exactly like \fIutmp\fP except that a null user name indicates a logout
 166 on the associated terminal.  Furthermore, the terminal name \fB~\fP
 167 with user name \fBshutdown\fP or \fBreboot\fP indicates a system
 168 shutdown or reboot and the pair of terminal names \fB|\fP/\fB}\fP
 169 logs the old/new system time when
 170 .BR date (1)
 171 changes it.  \fIwtmp\fP is maintained by
 172 .BR login (1),
 173 .BR init (1),
 174 and some versions of
 175 .BR getty (1).
 176 Neither of these programs creates the file, so if it is
 177 removed, record-keeping is turned off.
 178 .SH FILES
 179 /var/run/utmp
 180 .br
 181 /var/log/wtmp
 182 .SH "CONFORMING TO"
 183 Linux utmp entries conform neither to v7/BSD nor to SYSV; they are a
 184 mix of the two.  v7/BSD has fewer fields; most importantly it lacks
 185 \fIut_type\fP, which causes native v7/BSD-like programs to display (for
 186 example) dead or login entries.  Further, there is no configuration file
 187 which allocates slots to sessions.  BSD does so because it lacks
 188 \fIut_id\fP fields.  In Linux (as in SYSV), the \fIut_id\fP field of a
 189 record will never change once it has been set, which reserves that slot
 190 without needing a configuration file.  Clearing \fIut_id\fP may result
 191 in race conditions leading to corrupted utmp entries and and potential
 192 security holes.  Clearing the above mentioned fields by filling them
 193 with null bytes is not required by SYSV semantics, but it allows to run
 194 many programs which assume BSD semantics and which do not modify utmp.
 195 Linux uses the BSD conventions for line contents, as documented above.
 196 .PP
 197 SYSV only uses the type field to mark them and logs informative messages
 198 such as e.g.\& \fB"new time"\fP in the line field. \fBUT_UNKNOWN\fP seems
 199 to be a Linux invention.
 200 SYSV has no \fIut_host\fP or \fIut_addr_v6\fP fields.
 201 .PP
 202 Unlike various other
 203 systems, where utmp logging can be disabled by removing the file, utmp
 204 must always exist on Linux.  If you want to disable \fIwho\fP(1) then
 205 do not make utmp world readable.
 206 .PP
 207 Note that the utmp struct from libc5 has changed in libc6. Because of this,
 208 binaries using the old libc5 struct will corrupt
 209 .IR /var/run/utmp " and/or " /var/log/wtmp .
 210 Debian systems include a patched libc5 which uses the new utmp format.
 211 The problem still exists with wtmp since it's accessed directly in
 212 libc5.
 213 .SH RESTRICTIONS
 214 The file format is machine dependent, so it is recommended that it be
 215 processed only on the machine architecture where it was created.
 216 .SH BUGS
 217 This manpage is based on the libc5 one, things may work differently now.
 218 .SH "SEE ALSO"
 219 .BR ac (1),
 220 .BR date (1),
 221 .BR getutent (3),
 222 .BR init (8),
 223 .BR last (1),
 224 .BR login (1),
 225 .BR updwtmp (3),
 226 .BR who (1)