token

7 min read

token is the command-line tool for working with tokens directly. It reads a token's contents, adjusts it, produces derived tokens, and drives impersonation — the low-level operations this topic describes, exposed at a shell.

token subcommand [target] [arguments]

$ token                       # one-line summary of your own token
$ token show --all             # every field of your own token
$ token privs --pid 4821       # the privileges on process 4821's token

token is a direct, debug-level tool. Day to day you do not inspect tokens by hand — the system does. token is for diagnosing an access problem, for understanding what identity a process is really running under, and for building and testing identity setups. Run with no subcommand, it prints a one-line summary of your own token.

Choosing which token #

Almost every subcommand operates on a token, and these flags choose which one. With none, the target is your own.

Reading another process's token is itself access-controlled: it succeeds only with the right authority over that process.

Inspecting a token #

show #

token show prints a token's contents. It is the default — bare token is token show --short.

Field accessors #

Each of these prints one part of a token, for when you want just that piece:

token show reports the token's LogonSession LUID as session_id and its separate interactive-environment scope as interactivity_scope.

query #

token query CLASS performs a raw read of a single named token-info class and prints the result as JSON — the lowest-level inspection route, for tooling.

compare #

token compare LEFT RIGHT compares two tokens. Each positional target is a positive PID or self. To select a thread, primary self token, or peer token on the right, omit RIGHT and use the usual target flags:

token compare 1482 1500
token compare 1482 --pid 1482 --tid 1509
token compare self --real
token compare self --peer 7 --json

The table shows two value columns with = or != for each user SID, integrity SID, LogonSession ID, group state and privilege state. SIDs include their friendly names where known. Groups are enabled, disabled, or deny-only; privileges are enabled or disabled. A - means the group or privilege is absent from that token. The table includes entries present in either token.

With --json, header contains user, integrity and session_id; groups and privileges are arrays. Every compared field has left, right and a boolean matches. Missing group or privilege values are JSON null. Group entries also carry a group SID/name object, and privilege entries carry bit and name (null when unknown). Equality uses SID identity and the stated values, independent of friendly-name rendering. Both equal and differing comparisons exit successfully when all queries succeed.

threads #

token threads PID lists threads in ascending TID order, with an impersonating yes/no column and the effective user's SID and friendly name:

token threads 1482
token threads 1482 --json

The command enumerates /proc/PID/task and uses the normal access-controlled thread-token query. It reports primary-token threads as no, including when several threads have the same user. An impersonating thread remains yes even if its impersonation token has the same user as the primary token.

JSON output has pid, complete, and a threads array. A successful row contains tid, impersonating and user. A thread that disappears or cannot be queried retains its row with an error, null identity fields, and complete: false; the command exits nonzero. Human output shows ? and the error for that row. Directory-enumeration failures also exit nonzero.

Both commands support the normal --raw, --label and --json output choices. Queries are consecutive observations of a running system, not an atomic snapshot of all token fields or threads.

Changing a token #

adjust #

token adjust mutates a token in place:

restrict #

token restrict produces a restricted token — a more limited variant of a token.

duplicate #

token duplicate (alias dup) copies a token, optionally changing its --type (primary or impersonation), its impersonation --level, or its --access mask.

link and linked #

token link joins two tokens as an elevation pair — a full token and its filtered counterpart — given their file descriptors and a session id. token linked shows a token's elevation-linked counterpart, if it has one. See Elevation.

Impersonation #

See Impersonation for the model these drive.

Creating tokens #

Creating and installing tokens is a privileged operation, reserved for the components that legitimately mint identity.

Output options #

token and the inspection surfaces #

token is the convenient front-end. Underneath, it reads the same kernel surfaces and rules described in Inspecting tokens — that page covers the query mechanism, the access rules for reading another process's token, and what cannot be inspected.

Exit status #

Edit this page