- The new login code explained
- ============================
-
- This code attempts to provide a common interface to login recording
- (utmp and friends) and last login time retrieval.
-
- Its primary means of achieving this is to use 'struct logininfo', a
- union of all the useful fields in the various different types of
- system login record structures one finds on UNIX variants.
-
- We depend on autoconf to define which recording methods are to be
- used, and which fields are contained in the relevant data structures
- on the local system. Many C preprocessor symbols affect which code
- gets compiled here.
-
- The code is designed to make it easy to modify a particular
- recording method, without affecting other methods nor requiring so
- many nested conditional compilation blocks as were commonplace in
- the old code.
-
- For login recording, we try to use the local system's libraries as
- these are clearly most likely to work correctly. For utmp systems
- this usually means login() and logout() or setutent() etc., probably
- in libutil, along with logwtmp() etc. On these systems, we fall back
- to writing the files directly if we have to, though this method
- requires very thorough testing so we do not corrupt local auditing
- information. These files and their access methods are very system
- specific indeed.
-
- For utmpx systems, the corresponding library functions are
- setutxent() etc. To the author's knowledge, all utmpx systems have
- these library functions and so no direct write is attempted. If such
- a system exists and needs support, direct analogues of the [uw]tmp
- code should suffice.
-
- Retrieving the time of last login ('lastlog') is in some ways even
- more problemmatic than login recording. Some systems provide a
- simple table of all users which we seek based on uid and retrieve a
- relatively standard structure. Others record the same information in
- a directory with a separate file, and others don't record the
- information separately at all. For systems in the latter category,
- we look backwards in the wtmp or wtmpx file for the last login entry
- for our user. Naturally this is slower and on busy systems could
- incur a significant performance penalty.
-
- Calling the new code
- --------------------
-
- In OpenSSH all login recording and retrieval is performed in
- login.c. Here you'll find working examples. Also, in the logintest.c
- program there are more examples.
-
- Internal handler calling method
- -------------------------------
-
- When a call is made to login_login() or login_logout(), both
- routines set a struct logininfo flag defining which action (log in,
- or log out) is to be taken. They both then call login_write(), which
- calls whichever of the many structure-specific handlers autoconf
- selects for the local system.
-
- The handlers themselves handle system data structure specifics. Both
- struct utmp and struct utmpx have utility functions (see
- construct_utmp*()) to try to make it simpler to add extra systems
- that introduce new features to either structure.
-
- While it may seem terribly wasteful to replicate so much similar
- code for each method, experience has shown that maintaining code to
- write both struct utmp and utmpx in one function, whilst maintaining
- support for all systems whether they have library support or not, is
- a difficult and time-consuming task.
-
- Lastlog support proceeds similarly. Functions login_get_lastlog()
- (and its OpenSSH-tuned friend login_get_lastlog_time()) call
- getlast_entry(), which tries one of three methods to find the last
- login time. It uses local system lastlog support if it can,
- otherwise it tries wtmp or wtmpx before giving up and returning 0,
- meaning "tilt".
-
- Maintenance
- -----------
-
- In many cases it's possible to tweak autoconf to select the correct
- methods for a particular platform, either by improving the detection
- code (best), or by presetting DISABLE_<method> or CONF_<method>_FILE
- symbols for the platform.
-
- Use logintest to check which symbols are defined before modifying
- configure.ac and loginrec.c. (You have to build logintest yourself
- with 'make logintest' as it's not built by default.)
-
- Otherwise, patches to the specific method(s) are very helpful!
-
-*/
-
-/**
- ** TODO:
- ** homegrown ttyslot()
- ** test, test, test
- **
- ** Platform status:
- ** ----------------
- **
- ** Known good:
- ** Linux (Redhat 6.2, Debian)
- ** Solaris
- ** HP-UX 10.20 (gcc only)
- ** IRIX
- ** NeXT - M68k/HPPA/Sparc (4.2/3.3)
- **
- ** Testing required: Please send reports!
- ** NetBSD
- ** HP-UX 11
- ** AIX
- **
- ** Platforms with known problems:
- ** Some variants of Slackware Linux
- **
- **/
+ * The new login code explained
+ * ============================
+ *
+ * This code attempts to provide a common interface to login recording
+ * (utmp and friends) and last login time retrieval.
+ *
+ * Its primary means of achieving this is to use 'struct logininfo', a
+ * union of all the useful fields in the various different types of
+ * system login record structures one finds on UNIX variants.
+ *
+ * We depend on autoconf to define which recording methods are to be
+ * used, and which fields are contained in the relevant data structures
+ * on the local system. Many C preprocessor symbols affect which code
+ * gets compiled here.
+ *
+ * The code is designed to make it easy to modify a particular
+ * recording method, without affecting other methods nor requiring so
+ * many nested conditional compilation blocks as were commonplace in
+ * the old code.
+ *
+ * For login recording, we try to use the local system's libraries as
+ * these are clearly most likely to work correctly. For utmp systems
+ * this usually means login() and logout() or setutent() etc., probably
+ * in libutil, along with logwtmp() etc. On these systems, we fall back
+ * to writing the files directly if we have to, though this method
+ * requires very thorough testing so we do not corrupt local auditing
+ * information. These files and their access methods are very system
+ * specific indeed.
+ *
+ * For utmpx systems, the corresponding library functions are
+ * setutxent() etc. To the author's knowledge, all utmpx systems have
+ * these library functions and so no direct write is attempted. If such
+ * a system exists and needs support, direct analogues of the [uw]tmp
+ * code should suffice.
+ *
+ * Retrieving the time of last login ('lastlog') is in some ways even
+ * more problemmatic than login recording. Some systems provide a
+ * simple table of all users which we seek based on uid and retrieve a
+ * relatively standard structure. Others record the same information in
+ * a directory with a separate file, and others don't record the
+ * information separately at all. For systems in the latter category,
+ * we look backwards in the wtmp or wtmpx file for the last login entry
+ * for our user. Naturally this is slower and on busy systems could
+ * incur a significant performance penalty.
+ *
+ * Calling the new code
+ * --------------------
+ *
+ * In OpenSSH all login recording and retrieval is performed in
+ * login.c. Here you'll find working examples. Also, in the logintest.c
+ * program there are more examples.
+ *
+ * Internal handler calling method
+ * -------------------------------
+ *
+ * When a call is made to login_login() or login_logout(), both
+ * routines set a struct logininfo flag defining which action (log in,
+ * or log out) is to be taken. They both then call login_write(), which
+ * calls whichever of the many structure-specific handlers autoconf
+ * selects for the local system.
+ *
+ * The handlers themselves handle system data structure specifics. Both
+ * struct utmp and struct utmpx have utility functions (see
+ * construct_utmp*()) to try to make it simpler to add extra systems
+ * that introduce new features to either structure.
+ *
+ * While it may seem terribly wasteful to replicate so much similar
+ * code for each method, experience has shown that maintaining code to
+ * write both struct utmp and utmpx in one function, whilst maintaining
+ * support for all systems whether they have library support or not, is
+ * a difficult and time-consuming task.
+ *
+ * Lastlog support proceeds similarly. Functions login_get_lastlog()
+ * (and its OpenSSH-tuned friend login_get_lastlog_time()) call
+ * getlast_entry(), which tries one of three methods to find the last
+ * login time. It uses local system lastlog support if it can,
+ * otherwise it tries wtmp or wtmpx before giving up and returning 0,
+ * meaning "tilt".
+ *
+ * Maintenance
+ * -----------
+ *
+ * In many cases it's possible to tweak autoconf to select the correct
+ * methods for a particular platform, either by improving the detection
+ * code (best), or by presetting DISABLE_<method> or CONF_<method>_FILE
+ * symbols for the platform.
+ *
+ * Use logintest to check which symbols are defined before modifying
+ * configure.ac and loginrec.c. (You have to build logintest yourself
+ * with 'make logintest' as it's not built by default.)
+ *
+ * Otherwise, patches to the specific method(s) are very helpful!
+ */