Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help

     sudoers_timestamp -- Sudoers Time Stamp Format

     The sudoers plugin	uses per-user time stamp files for credential caching.
     Once a user has been authenticated, they may use sudo without a password
     for a short period	of time	(5 minutes unless overridden by	the
     timestamp_timeout option).	 By default, sudoers uses a separate record
     for each terminal,	which means that a user's login	sessions are authenti-
     cated separately.	The timestamp_type option can be used to select	the
     type of time stamp	record sudoers will use.

     A multi-record time stamp file format was introduced in sudo 1.8.10 that
     uses a single file	per user.  Previously, a separate file was used	for
     each user and terminal combination	unless tty-based time stamps were dis-
     abled.  The new format is extensible and records of multiple types	and
     versions may coexist within the same file.

     All records, regardless of	type or	version, begin with a 16-bit version
     number and	a 16-bit record	size.

     Time stamp	records	have the following structure:

     /*	Time stamp entry types */
     #define TS_GLOBAL		     0x01    /*	not restricted by tty or ppid */
     #define TS_TTY		     0x02    /*	restricted by tty */
     #define TS_PPID		     0x03    /*	restricted by ppid */
     #define TS_LOCKEXCL	     0x04    /*	special	lock record */

     /*	Time stamp flags */
     #define TS_DISABLED	     0x01    /*	entry disabled */
     #define TS_ANYUID		     0x02    /*	ignore uid, only valid in key */

     struct timestamp_entry {
	 unsigned short	version;     /*	version	number */
	 unsigned short	size;	     /*	entry size */
	 unsigned short	type;	     /*	TS_GLOBAL, TS_TTY, TS_PPID */
	 unsigned short	flags;	     /*	TS_DISABLED, TS_ANYUID */
	 uid_t auth_uid;	     /*	uid to authenticate as */
	 pid_t sid;		     /*	session	ID associated with tty/ppid */
	 struct	timespec start_time; /*	session/ppid start time	*/
	 struct	timespec ts;	     /*	time stamp (CLOCK_MONOTONIC) */
	 union {
	     dev_t ttydev;	     /*	tty device number */
	     pid_t ppid;	     /*	parent pid */
	 } u;

     The timestamp_entry struct	fields are as follows:

	   The version number of the timestamp_entry struct.  New entries are
	   created with	a version number of 2.	Records	with different version
	   numbers may coexist in the same file	but are	not inter-operable.

     size  The size of the record in bytes.

     type  The record type, currently TS_GLOBAL, TS_TTY, or TS_PPID.

	   Zero	or more	record flags which can be bit-wise ORed	together.
	   Supported flags are TS_DISABLED, for	records	disabled via sudo -k
	   and TS_ANYUID, which	is used	only when matching records.

	   The user-ID that was	used for authentication.  Depending on the
	   value of the	rootpw,	runaspw	and targetpw options, the user-ID may
	   be that of the invoking user, the root user,	the default runas user
	   or the target user.

     sid   The ID of the user's	terminal session, if present.  The session ID
	   is only used	when matching records of type TS_TTY.

	   The start time of the session leader	for records of type TS_TTY or
	   of the parent process for records of	type TS_PPID.  The start_time
	   is used to help prevent re-use of a time stamp record after a user
	   has logged out.  Not	all systems support a method to	easily re-
	   trieve a process's start time.  The start_time field	was added in
	   sudoers version 1.8.22 for the second revision of the timestamp_en-
	   try struct.

     ts	   The actual time stamp.  A monotonic time source (which does not
	   move	backward) is used if the system	supports it.  Where possible,
	   sudoers uses	a monotonic timer that increments even while the sys-
	   tem is suspended.  The value	of ts is updated each time a command
	   is run via sudo.  If	the difference between ts and the current time
	   is less than	the value of the timestamp_timeout option, no password
	   is required.

	   The device number of	the terminal associated	with the session for
	   records of type TS_TTY.

	   The ID of the parent	process	for records of type TS_PPID.

     In	sudoers	versions 1.8.10	through	1.8.14,	the entire time	stamp file was
     locked for	exclusive access when reading or writing to the	file.  Start-
     ing in sudoers 1.8.15, individual records are locked in the time stamp
     file instead of the entire	file and the lock is held for a	longer period
     of	time.  This scheme is described	below.

     The first record in the time stamp	file is	of type	TS_LOCKEXCL and	is
     used as a lock record to prevent more than	one sudo process from adding a
     new record	at the same time.  Once	the desired time stamp record has been
     located or	created	(and locked), the TS_LOCKEXCL record is	unlocked.  The
     lock on the individual time stamp record, however,	is held	until authen-
     tication is complete.  This allows	sudoers	to avoid prompting for a pass-
     word multiple times when it is used more than once	in a pipeline.

     Records of	type TS_GLOBAL cannot be locked	for a long period of time
     since doing so would interfere with other sudo processes.	Instead, a
     separate lock record is used to prevent multiple sudo processes using the
     same terminal (or parent process ID) from prompting for a password	as the
     same time.

     sudoers(5), sudo(8)

     Originally, sudo used a single zero-length	file per user and the file's
     modification time was used	as the time stamp.  Later versions of sudo
     added restrictions	on the ownership of the	time stamp files and directory
     as	well as	checks on the validity of the time stamp itself.  Notable
     changes were introduced in	the following sudo versions:

	   Support for tty-based time stamp file was added by appending	the
	   terminal name to the	time stamp file	name.

	   The time stamp file was replaced by a per-user directory which con-
	   tained any tty-based	time stamp files.

	   The target user name	was added to the time stamp file name when the
	   targetpw option was set.

	   Information about the terminal device was stored in tty-based time
	   stamp files for validity checks.  This included the terminal	device
	   numbers, inode number and, on systems where it was not updated when
	   the device was written to, the inode	change time.  This helped pre-
	   vent	re-use of the time stamp file after logout.

	   The terminal	session	ID was added to	tty-based time stamp files to
	   prevent re-use of the time stamp by the same	user in	a different
	   terminal session.  It also helped prevent re-use of the time	stamp
	   file	on systems where the terminal device's inode change time was
	   updated by writing.

	   A new, multi-record time stamp file format was introduced that uses
	   a single file per user.  The	terminal device's change time was not
	   included since most systems now update the change time after	a
	   write is performed as required by POSIX.

	   Individual records are locked in the	time stamp file	instead	of the
	   entire file and the lock is held until authentication is complete.

	   The start time of the terminal session leader or parent process is
	   now stored in non-global time stamp records.	 This prevents re-use
	   of the time stamp file after	logout in most cases.

	   Support was added for the kernel-based tty time stamps available in
	   OpenBSD which do not	use an on-disk time stamp file.

     Many people have worked on	sudo over the years; this version consists of
     code written primarily by:

	   Todd	C. Miller

     See the CONTRIBUTORS file in the sudo distribution
     ( for an exhaustive list of people
     who have contributed to sudo.

     If	you feel you have found	a bug in sudo, please submit a bug report at

     Limited free support is available via the sudo-users mailing list,	see to	subscribe or search
     the archives.

     sudo is provided "AS IS" and any express or implied warranties, includ-
     ing, but not limited to, the implied warranties of	merchantability	and
     fitness for a particular purpose are disclaimed.  See the LICENSE file
     distributed with sudo or for complete

Sudo 1.9.5p2		       October 20, 2019			  Sudo 1.9.5p2


Want to link to this manual page? Use this URL:

home | help