LOGINCTL(1)

✨ loginctl(1) ✨ — the manual page, but make it make sense

okay bestie, welcome to loginctl, aka the lil command that lets you peek at and boss around the systemd login manager 💅. That's the systemd(1) login manager, running as systemd-logind.service(8), in case you were wondering who's actually holding the aux cord here.

---

🎀 NAME 🎀

loginctl — control the systemd login manager. that's it, that's the whole job description, and she ate 💖

---

🌸 SYNOPSIS 🌸

loginctl [OPTIONS...] {COMMAND} [NAME...]

---

🦋 DESCRIPTION 🦋

so like, loginctl is your girl for introspecting and controlling the state of the systemd(1) login manager, which lives inside systemd-logind.service(8). think of it as the group chat admin panel for who's logged in, where, and on which seat 🪑✨

---

👑 COMMANDS 👑

here's everything she understands, no gatekeeping fr fr:

💜 Session Commands 💜

• list-sessions — lists the current sessions, periodt. You can toggle the JSON format output with the --json= or -j option 🫶
• session-status [ID...] — shows terse runtime status info about one or more sessions, and then follows it up with the most recent log data from the journal 📓. Takes one or more session identifiers as parameters. If you pass no session identifiers, you get the status of the caller's session. This one is built for human-readable output, so if you're hunting for computer-parsable output, use show-session instead, okay?

Added in version 233.

• show-session [ID...] — shows properties of one or more sessions, or of the manager itself. No argument? You get the manager's properties. Session ID? You get that session's properties. And the special lil moments: if the ID you give is "self", she uses the session that the loginctl process itself belongs to. If it's "auto", she uses the current session just like "self" if it exists, and falls back to the current user's graphical session if it doesn't. By default, empty properties get suppressed 🙈 — use --all to see those too. Wanna pick specific properties? That's --property=. This is the one for whenever you need computer-parsable output; if you want the pretty formatted human-readable version, use session-status 💅

Added in version 233.

• activate [ID] — activates a session, which brings it into the foreground if another session is currently in the foreground on the respective seat 👀. Takes a session identifier as its argument. No argument? Then the caller's session gets put in the foreground.

Added in version 219.

• lock-session [ID...], unlock-session [ID...] — activates/deactivates the screen lock on one or more sessions, but only if the session actually supports it. Takes one or more session identifiers as arguments. No argument at all? The caller's session gets locked/unlocked 🔒

Added in version 233.

• lock-sessions, unlock-sessions — activates/deactivates the screen lock on all current sessions that support it. go big or go home ✨

Added in version 188.

• terminate-session ID... — terminates a session. This kills all processes of the session and deallocates all resources attached to it 💀. Heads up: if the argument is specified as an empty string, then the session invoking the command is the one that gets terminated. not me ending myself 😭

Added in version 233.

• kill-session ID... — sends a signal to one or more processes of the session. Use --kill-whom= to pick which process to kill, and --signal= to pick which signal gets sent. And again: if the argument is specified as an empty string, the signal is sent to the session invoking the command 🙈

Added in version 233.

🍓 User Commands 🍓

• list-users — lists the users currently logged in. The JSON format output can be toggled with the --json= or -j option 💖
• user-status [USER...] — shows terse runtime status info about one or more logged in users, followed by the most recent log data from the journal. Takes one or more user names or numeric user IDs as parameters. No parameters? Then the status is shown for the user of the session of the caller. Built for human-readable output — if you want computer-parsable, use show-user instead 🫶

Added in version 233.

• show-user [USER...] — shows properties of one or more users, or of the manager itself. No argument? Manager properties. A user specified? That user's properties. Empty properties are suppressed by default, so use --all to show those too, and --property= to pick specific ones. Use this whenever you need computer-parsable output; use user-status when you want the formatted human-readable glow-up ✨

Added in version 233.

• enable-linger [USER...], disable-linger [USER...] — enables/disables user lingering for one or more users. If it's enabled for a specific user, a user manager is spawned for that user at boot and kept around even after logouts. Why do we care? Because it lets users who are not logged in run long-running services 🔥. Takes one or more user names or numeric UIDs as arguments. No argument? Then it enables/disables lingering for the user of the session of the caller.

See also the KillUserProcesses= setting in logind.conf(5).

Added in version 233.

• terminate-user USER... — terminates all sessions of a user. That kills all processes of all sessions of the user and deallocates all runtime resources attached to the user 💀. If the argument is specified as an empty string, the sessions of the user invoking the command are the ones that get terminated.

Added in version 233.

• kill-user USER... — sends a signal to all processes of a user. Use --signal= to choose the signal to send. If the argument is specified as an empty string, the signal is sent to the sessions of the user invoking the command.

Added in version 233.

🪑 Seat Commands 🪑

• list-seats — lists the seats currently available on the local system. JSON format output toggles with --json= or -j 💅
• seat-status [NAME...] — shows terse runtime status info about one or more seats. Takes one or more seat names as parameters. If you pass no seat names, the status of the caller's session's seat is shown. Human-readable output vibes — if you want computer-parsable, use show-seat instead 🌸

Added in version 233.

• show-seat [NAME...] — shows properties of one or more seats, or of the manager itself. No argument? Manager properties. A seat specified? That seat's properties. Empty properties are suppressed by default; --all shows those too, and --property= selects specific ones. Computer-parsable output, so use seat-status if you want the formatted human-readable version 🫶

Added in version 233.

• attach NAME DEVICE... — persistently attaches one or more devices to a seat. Devices should be specified via device paths in the /sys/ file system. Wanna create a brand new seat? Attach at least one graphics card to a previously unused seat name 🎮. Seat names may consist only of a–z, A–Z, 0–9, "-" and "_" and must be prefixed with "seat". And to drop a device's assignment to a specific seat, just reassign it to a different seat, or use flush-devices.

Added in version 233.

• flush-devices — removes all device assignments previously created with attach. After this call, only automatically generated seats will remain, and all seat hardware is assigned to them 🧹✨
• terminate-seat NAME... — terminates all sessions on a seat. This kills all processes of all sessions on the seat and deallocates all runtime resources attached to them 💀

Added in version 233.

✨ OPTIONS ✨

okay bestie, here's where the actual knobs and dials live. every one of these is understood, no cap:

• -p, --property= — when you're showing session/user/seat properties, this limits the display to just the properties you name as the argument. don't specify it and you get every property that's set. the argument should be a property name, like "Sessions". say it more than once and you get all the properties with those names. stack 'em up 💅
• --value — when showing session/user/seat properties, this prints only the value and skips the property name and the =. just the juice, none of the label 🧃

added in version 230, for the history girlies

• -a, --all — when showing session/user/seat properties, show all of them, whether they're set or not. no hiding, we're being transparent today ✨
• -l, --full — do not ellipsize process tree entries. no ... shortcuts, we want the whole thing, full glam, no cropping 🔥

added in version 198

• --kill-whom= — when you use it with kill-session, this picks which processes get killed. takes one of "leader" or "all" — so either just the leader process of the session, or every process in it. leave it out and it defaults to all. everyone's invited to the function 💀

added in version 252

• -s, --signal= — when you use it with kill-session or kill-user, this picks which signal gets sent to the selected processes. it must be one of the well known signal specifiers, like SIGTERM, SIGINT or SIGSTOP. leave it out and it defaults to SIGTERM.

and listen — the special value "help" will list the known values and the program exits immediately, and the special value "list" will list the known values along with the numerical signal numbers, and the program exits immediately too. so helpful, so iconic 🎀

• -n, --lines= — when you use it with user-status and session-status, this controls how many journal lines get shown, counting from the most recent ones. takes a positive integer argument. defaults to 10.

added in version 219

• -o, --output= — when you use it with user-status and session-status, this controls the formatting of the journal entries that get shown. for the available choices, go peek at journalctl(1). defaults to "short".

added in version 219

• -H, --host= — runs the operation remotely. give it a hostname, or a username and hostname separated by "@", to connect to. the hostname may optionally be suffixed by a port ssh is listening on, separated by ":", and then a container name, separated by "/", which connects you directly to a specific container on the specified host. this uses SSH to talk to the remote machine manager instance. container names can be enumerated with machinectl -H HOST. and put IPv6 addresses in brackets, bestie, don't forget 🦋
• -M, --machine= — runs the operation on a local container. give it a container name to connect to, optionally prefixed by a user name to connect as and a separating "@" character. if the special string ".host" is used in place of the container name, a connection to the local system is made — which is super useful for connecting to a specific user's user bus: "--user --machine=lennart@.host". if the "@" syntax isn't used, the connection is made as root user. if the "@" syntax is used, either the left hand side or the right hand side may be omitted (but not both!), in which case the local user name and ".host" are implied. both at once? no ma'am 🙈
• --no-ask-password — do not query the user for authentication for privileged operations. we're not doing the password pop-up today 🔐
• --no-pager — do not pipe output into a pager. straight to your eyeballs, no middleman 👀
• --no-legend — do not print the legend, i.e. the column headers and the footer with hints. just the data, minimal vibes ✨
• --json=MODE — shows output formatted as JSON. expects one of "short" (for the shortest possible output without any redundant whitespace or line breaks), "pretty" (for a pretty version of the same, with indentation and line breaks) or "off" (to turn off JSON output, the default). pick your aesthetic 💅
• -j — equivalent to --json=pretty if running on a terminal, and --json=short otherwise. she adapts to the situation, main character energy fr fr 🌟
• -h, --help — print a short help text and exit. the classic cry for help, we love her 🫶
• --version — print a short version string and exit. who are you, what era are you from 💖

---

🎬 EXIT STATUS

on success, 0 is returned, a non-zero failure code otherwise. simple as that, periodt ✨

---

🌸 EXAMPLES 🌸

Example 1. Querying user status

$ loginctl user-status
fatima (1005)
           Since: Sat 2016-04-09 14:23:31 EDT; 54min ago
           State: active
        Sessions: 5 *3
            Unit: user-1005.slice
                  ├─user@1005.service
                    ...
                  ├─session-3.scope
                    ...
                  └─session-5.scope
                    ├─3473 login -- fatima
                    └─3515 -zsh

Apr 09 14:40:30 laptop login[2325]: pam_unix(login:session):
                       session opened for user fatima by LOGIN(uid=0)
Apr 09 14:40:30 laptop login[2325]: LOGIN ON tty3 BY fatima

so there are two sessions, 3 and 5. session 3 is a graphical session, marked with a star ⭐. the tree of processing including the two corresponding scope units and the user manager unit are shown. look at that little family tree, she's thriving 🌳💖

🌸 ENVIRONMENT 🌸

ok so these are the environment variables that change how loginctl (and honestly all the systemd girlies) behaves 💅

• $SYSTEMD_LOG_LEVEL — the max log level of messages that actually get emitted (anything with a higher log level, aka less important, gets suppressed, sorry bestie 😭). Takes a comma-separated list of values. Each value is either one of these, in order of decreasing importance: emerg, alert, crit, err, warning, notice, info, debug — or just an integer in the range 0...7. Peep syslog(3) for more deets. Every value can optionally be prefixed with one of console, syslog, kmsg or journal followed by a colon, so you can set the max log level for that specific log target (like, SYSTEMD_LOG_LEVEL=debug,console:info means log everything at debug level EXCEPT when it's going to the console, which should be at info level ✨). One thing tho: the global max log level takes priority over any per-target max log levels. periodt.
• $SYSTEMD_LOG_COLOR — a boolean 🎀. If true, messages written to the tty get colored by priority (slay).

This setting is only useful when messages are written directly to the terminal, because journalctl(1) and other tools that display logs will color messages based on the log level on their own. so like, don't bother otherwise 💀

• $SYSTEMD_LOG_TIME — a boolean ⏰. If true, console log messages get prefixed with a timestamp.

Again, only useful when messages go directly to the terminal or a file, because journalctl(1) and friends attach timestamps based on the entry metadata themselves. they got it covered 🫶

• $SYSTEMD_LOG_LOCATION — a boolean 📍. If true, messages get prefixed with a filename and line number pointing to where in the source code the message originates.

ngl the log location is usually attached as metadata to journal entries anyway. But having it right there in the message text is lowkey convenient when you're debugging programs, so. iykyk.

• $SYSTEMD_LOG_TID — a boolean 🧵. If true, messages get prefixed with the current numerical thread ID (TID).

Note that the this information is attached as metadata to journal entries anyway. Including it directly in the message text can nevertheless be convenient when debugging programs.

• $SYSTEMD_LOG_TARGET — where your log messages go, bestie. One of:
  • console — log to the attached tty
  • console-prefixed — log to the attached tty but with prefixes encoding the log level and "facility", peep syslog(3)
  • kmsg — log to the kernel circular log buffer
  • journal — log to the journal
  • journal-or-kmsg — log to the journal if it's available, and to kmsg otherwise
  • auto — determine the appropriate log target automatically, this is the default 👑
  • null — disable log output entirely
• $SYSTEMD_LOG_RATELIMIT_KMSG — whether to ratelimit kmsg or not 🚦. Takes a boolean. Defaults to "true". If you disable it, systemd will not ratelimit messages written to kmsg.
• $SYSTEMD_PAGER, $PAGER — which pager to use when --no-pager isn't given 📖. $SYSTEMD_PAGER is used if it's set; otherwise $PAGER gets the job. If neither $SYSTEMD_PAGER nor $PAGER are set, a set of well-known pager implementations gets tried in turn, including less(1) and more(1), until one is found. If no pager implementation is discovered, no pager is invoked, simple as that. Setting either of those env vars to an empty string or the value "cat" is equivalent to passing --no-pager.

Note: if $SYSTEMD_PAGERSECURE is not set, $SYSTEMD_PAGER and $PAGER can only be used to disable the pager (with "cat" or ""), and are otherwise ignored. yeah. it's giving security ✋

• $SYSTEMD_LESS — override the options passed to less (by default "FRSXMK").

Users might want to change two options in particular:

• K — this option instructs the pager to exit immediately when Ctrl+C is pressed. To allow less to handle Ctrl+C itself to switch back to the pager command prompt, unset this option. If the value of $SYSTEMD_LESS does not include "K", and the pager that is invoked is less, Ctrl+C will be ignored by the executable, and needs to be handled by the pager.
• X — this option instructs the pager to not send termcap initialization and deinitialization strings to the terminal. It is set by default to allow command output to remain visible in the terminal even after the pager exits. Nevertheless, this prevents some pager functionality from working — in particular, paged output cannot be scrolled with the mouse 🖱️😭.

Note that setting the regular $LESS environment variable has no effect for less invocations by systemd tools.

See less(1) for more discussion.

• $SYSTEMD_LESSCHARSET — override the charset passed to less (by default "utf-8", if the invoking terminal is determined to be UTF-8 compatible) 🌈.

Note that setting the regular $LESSCHARSET environment variable has no effect for less invocations by systemd tools.

• $SYSTEMD_PAGERSECURE — okay this one is important, listen up 🔥. Common pager commands like less(1), in addition to "paging" (aka scrolling through the output), support opening or writing to other files and running arbitrary shell commands. When commands are invoked with elevated privileges — like under sudo(8) or pkexec(1) — the pager becomes a security boundary. Care must be taken that only programs with strictly limited functionality are used as pagers, and that unintended interactive features like opening or creating new files or starting subprocesses are not allowed. "Secure mode" for the pager may be enabled as described below, if the pager supports that (most pagers are not written in a way that takes this into consideration 😬). It is recommended to either explicitly enable "secure mode" or to completely disable the pager using --no-pager or PAGER=cat when allowing untrusted users to execute commands with elevated privileges.

This option takes a boolean argument. When set to true, the "secure mode" of the pager is enabled. In "secure mode", LESSSECURE=1 will be set when invoking the pager, which instructs the pager to disable commands that open or create new files or start new subprocesses. Currently only less(1) is known to understand this variable and implement "secure mode".

When set to false, no limitation is placed on the pager. Setting SYSTEMD_PAGERSECURE=0 or not removing it from the inherited environment may allow the user to invoke arbitrary commands. 💀

When $SYSTEMD_PAGERSECURE is not set, systemd tools attempt to automatically figure out if "secure mode" should be enabled and whether the pager supports it. "Secure mode" is enabled if the effective UID is not the same as the owner of the login session, see geteuid(2) and sd_pid_get_owner_uid(3), or when running under sudo(8) or similar tools ($SUDO_UID is set [1]). In those cases, SYSTEMD_PAGERSECURE=1 will be set and pagers which are not known to implement "secure mode" will not be used at all. Note that this autodetection only covers the most common mechanisms to elevate privileges and is intended as convenience. It is recommended to explicitly set $SYSTEMD_PAGERSECURE or disable the pager.

Note that if the $SYSTEMD_PAGER or $PAGER variables are to be honoured, other than to disable the pager, $SYSTEMD_PAGERSECURE must be set too.

• $SYSTEMD_COLORS — takes a boolean argument, or a special value 🎨. By default (unset), systemd and related utilities will use colors in their output if possible. If $COLORTERM is set to "truecolor" or "24bit", 24-bit colors will be enabled, 256 colors otherwise — unless $NO_COLOR or $TERM indicates colors are disabled.
  • true — same as unset, except that $NO_COLOR is ignored.
  • false — the output will be monochrome (sad 💀).
  • "16", "256", "24bit" — always use the base 16 ANSI colors, 256 colors, or 24 bit color, respectively.
  • "auto-16", "auto-256", "auto-24bit" — use the given quantity of colours, subject to $TERM, and what the console is connected to.
• $SYSTEMD_URLIFY — the value must be a boolean 🔗. Controls whether clickable links should be generated in the output for terminal emulators supporting this. This can be specified to override the decision that systemd makes based on $TERM and other conditions.

---

👀 SEE ALSO 👀

systemd(1), systemctl(1), systemd-logind.service(8), logind.conf(5)

---

📝 NOTES 📝

1. It is recommended for other tools to set and check $SUDO_UID as appropriate, treating it is a common interface.

---

and that's the whole page bestie, you ATE that 🫶✨ this was systemd 262.1 and the page is dated LOGINCTL(1) — go forth and manage your sessions like the main character you are, no cap 👑💖