|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | DESCRIPTION | LOCKING | SEE ALSO | HISTORY | AUTHORS | BUGS | SUPPORT | DISCLAIMER | COLOPHON |
|
|
|
SUDOERS_TIMESTAMP(5) File Formats Manual SUDOERS_TIMESTAMP(5)
sudoers_timestamp — Sudoers Time Stamp Format
The sudoers plugin uses per-user-ID 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 authenticated 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 disabled. 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 0x01U /* not restricted by tty or ppid */
#define TS_TTY 0x02U /* restricted by tty */
#define TS_PPID 0x03U /* restricted by ppid */
#define TS_LOCKEXCL 0x04U /* special lock record */
/* Time stamp flags */
#define TS_DISABLED 0x01U /* entry disabled */
#define TS_ANYUID 0x02U /* 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:
version
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.
flags
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.
auth_uid
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.
start_time
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 reuse of a time stamp
record after a user has logged out. Not all systems support
a method to easily retrieve a process's start time. The
start_time field was added in sudoers version 1.8.22 for the
second revision of the timestamp_entry 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 system 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.
u.ttydev
The device number of the terminal associated with the
session for records of type TS_TTY.
u.ppid
The ID of the parent process for records of type TS_PPID.
The tsdump utility, included with the sudo source distribution,
can be used to display the contents of a sudoers time stamp file.
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. Starting 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 authentication is complete.
This allows sudoers to avoid prompting for a password 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:
1.4.0
Support for tty-based time stamp file was added by appending
the terminal name to the time stamp file name.
1.6.2
The time stamp file was replaced by a per-user directory
which contained any tty-based time stamp files.
1.6.3p2
The target user name was added to the time stamp file name
when the targetpw option was set.
1.7.3
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 prevent reuse of the time
stamp file after logout.
1.8.6p7
The terminal session ID was added to tty-based time stamp
files to prevent reuse of the time stamp by the same user in
a different terminal session. It also helped prevent reuse
of the time stamp file on systems where the terminal
device's inode change time was updated by writing.
1.8.10
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.
1.8.15
Individual records are locked in the time stamp file instead
of the entire file and the lock is held until authentication
is complete.
1.8.22
The start time of the terminal session leader or parent
process is now stored in non-global time stamp records.
This prevents reuse 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.
1.9.15
Time stamp file path names are now based on the invoking
user-ID instead of the user name. This avoids problems with
user names that include a path separator character.
Many people have worked on sudo over the years; this version
consists of code written primarily by:
Todd C. Miller
See the CONTRIBUTORS.md file in the sudo distribution
(https://www.sudo.ws/about/contributors/) for an exhaustive list
of people who have contributed to sudo.
If you believe you have found a bug in , you can either file a bug
report in the sudo bug database, https://bugzilla.sudo.ws/, or
open an issue at https://github.com/sudo-project/sudo/issues. If
you would prefer to use email, messages may be sent to the sudo-
workers mailing list,
https://www.sudo.ws/mailman/listinfo/sudo-workers (public) or
<sudo@sudo.ws> (private).
Please do not report security vulnerabilities through public
GitHub issues, Bugzilla or mailing lists. Instead, report them
via email to <Todd.Miller@sudo.ws>. You may encrypt your message
with PGP if you would like, using the key found at
https://www.sudo.ws/dist/PGPKEYS.
Limited free support is available via the sudo-users mailing list,
see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe
or search the archives.
sudo is provided “AS IS” and any express or implied warranties,
including, but not limited to, the implied warranties of
merchantability and fitness for a particular purpose are
disclaimed. See the LICENSE.md file distributed with sudo or
https://www.sudo.ws/about/license/ for complete details.
This page is part of the sudo (execute a command as another user)
project. Information about the project can be found at
https://www.sudo.ws/. If you have a bug report for this manual
page, see ⟨https://bugzilla.sudo.ws/⟩. This page was obtained
from the project's upstream Git repository
⟨https://github.com/sudo-project/sudo⟩ on 2025-08-11. (At that
time, the date of the most recent commit that was found in the
repository was 2025-07-24.) If you discover any rendering
problems in this HTML version of the page, or you believe there is
a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
man-pages@man7.org
Sudo 1.9.17p2 November 26, 2023 SUDOERS_TIMESTAMP(5)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|