From: Zbigniew Jędrzejewski-Szmek Date: Sun, 12 Apr 2020 13:05:08 +0000 (+0200) Subject: man: login1(5) — fix markup and fill in the missing descriptions X-Git-Tag: v246-rc1~567^2~4 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=7592871e26554fb67baf5e18fe4fd9b053224490;p=thirdparty%2Fsystemd.git man: login1(5) — fix markup and fill in the missing descriptions Partially fixes #1042. --- diff --git a/man/org.freedesktop.login1.xml b/man/org.freedesktop.login1.xml index 1c6134f9a6c..ff944b2d1c4 100644 --- a/man/org.freedesktop.login1.xml +++ b/man/org.freedesktop.login1.xml @@ -235,161 +235,6 @@ node /org/freedesktop/login1 { }; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Security - - A number of operations are protected via the PolicyKit privilege - system. SetUserLinger() requires the - org.freedesktop.login1.set-user-linger - privilege. AttachDevice() requires - org.freedesktop.login1.attach-device and - FlushDevices() - org.freedesktop.login1.flush-devices. PowerOff(), - Reboot(), Suspend(), Hibernate(), - HybridSleep() require - org.freedesktop.login1.power-off, - org.freedesktop.login1.power-off-multiple-sessions, - org.freedesktop.login1.power-off-ignore-inhibit, - org.freedesktop.login1.reboot, - org.freedesktop.login1.reboot-multiple-sessions, - org.freedesktop.login1.reboot-ignore-inhibit, - org.freedesktop.login1.suspend, - org.freedesktop.login1.suspend-multiple-sessions, - org.freedesktop.login1.suspend-ignore-inhibit, - org.freedesktop.login1.hibernate, - org.freedesktop.login1.hibernate-multiple-sessions, - respectively. - org.freedesktop.login1.hibernate-ignore-inhibit, depending whether - there are other sessions around or active inhibits. Inhibit() is protected via - either one of org.freedesktop.login1.inhibit-block-shutdown, - org.freedesktop.login1.inhibit-delay-shutdown, - org.freedesktop.login1.inhibit-block-sleep, - org.freedesktop.login1.inhibit-delay-sleep, - org.freedesktop.login1.inhibit-block-idle, - org.freedesktop.login1.inhibit-handle-power-key, - org.freedesktop.login1.inhibit-handle-suspend-key, - org.freedesktop.login1.inhibit-handle-hibernate-key, - org.freedesktop.login1.inhibit-handle-lid-switch depending on the lock - type and mode taken. - - The user_interaction boolean parameters can be used to control whether - PolicyKit should interactively ask the user for authentication credentials if it needs to. - - Methods @@ -409,6 +254,10 @@ node /org/freedesktop/login1 { ListSeats() returns an array with all currently available seats. The structure in the array consists of the following fields: seat id, seat object path. + ListInhibitors() lists all currently active inhibitors. Returns an array of + structures consisting of what, who, why, + mode, user ID uid, and process ID pid. + CreateSession() and ReleaseSession() may be used to open or close login sessions. These calls should never be invoked directly by clients. Creating/closing sessions is exclusively the job of PAM and its @@ -460,43 +309,77 @@ node /org/freedesktop/login1 { all assignments to the automatic defaults. The only argument this takes is the PolicyKit interactivity boolean (see above). - PowerOff(), Reboot(), Suspend(), - Hibernate(), HybridSleep() results in the system being - powered off, rebooted, suspend, hibernated or hibernated+suspended. The only argument is the PolicyKit - interactivity boolean (see above). The main purpose of these calls is that they enforce PolicyKit - policy and hence allow powering off/rebooting/suspending/hibernating even by unprivileged users. They - also enforce inhibition locks. UIs should expose these calls as primary mechanism to - poweroff/reboot/suspend/hibernate/hybrid-sleep the machine. + PowerOff(), Reboot(), Halt(), + Suspend(), Hibernate() result in the system being powered + off, rebooted, halted (shut down without turning off power), suspended (the store of the system is + saved to RAM and the CPU is turned off), or hibernated (the store of the system is saved to disk and + the machine is powered down). HybridSleep() results in the system entering a + hybrid-sleep mode, i.e. the system is both hibernated and suspended. + SuspendThenHibernate() results in the system being suspended, then later woken + using an RTC timer, and hibernated. The only argument is the PolicyKit interactivity boolean + interactive (see above). The main purpose of these calls is that they enforce + PolicyKit policy and hence allow powering off/rebooting/suspending/hibernating even by unprivileged + users. They also enforce inhibition locks. UIs should expose these calls as primary mechanism to + poweroff/reboot/suspend/hibernate the machine. + + SetRebootParameter() sets the parameter for the subsequent reboot operation. + See the description of reboot in + systemctl1 and + reboot2 + for more information. + + SetRebootToFirmwareSetup(), + SetRebootToBootLoaderMenu(), and SetRebootToBootLoaderEntry() + configure the action to be taken from the boot loader after a reboot: respectively entering firmware + setup mode, or the boot loader menu, or a specific boot loader entry. See + systemctl1 for the + command line interface. CanPowerOff(), CanReboot(), - CanSuspend(), CanHibernate(), - CanHybridSleep() tests whether the system supports the respective operation and - whether the calling user is eligible for the desired operation. Returns one of na, - yes, no or challenge. If na - is returned the operation is not available because hardware, kernel or drivers do not support it. If - yes is returned the operation is supported and the user may execute the operation - without further authentication. If no is returned the operation is available but the - user is not allowed to execute the operation. If challenge is returned the operation - is available, but only after authorization. + CanHalt(), CanSuspend(), CanHibernate(), + CanHybridSleep(), CanSuspendThenHibernate(), + CanRebootParameter(), CanRebootToFirmwareSetup(), + CanRebootToBootLoaderMenu(), and + CanRebootToBootLoaderEntry(), test whether the system supports the respective + operation and whether the calling user is allowed to request it. Returns one of na, + yes, no, and challenge. If + na is returned, the operation is not available because hardware, kernel, or drivers + do not support it. If yes is returned, the operation is supported and the user may + execute the operation without further authentication. If no is returned the + operation is available but the user is not allowed to execute the operation. If + challenge is returned the operation is available, but only after + authorization. + + ScheduleShutdown() schedules a shutdown operation type at + time usec in microseconds since the UNIX epoch. type can be one + of poweroff, dry-poweroff, reboot, + dry-reboot, halt, and dry-halt. (The + dry- variants do not actually execute the shutdown action.) + CancelScheduledShutdown() cancels a scheduled shutdown. The output parameter + cancelled is true if a shutdown operation was scheduled. + + SetWallMessage() sets the wall message (the message that will be sent out to + all terminals and stored in an + utmp5 record) for a + subsequent scheduled shutdown operation. The parameter wall_message specifies the + shutdown reason (and may be empty) which will be included in the shutdown message. The parameter + enable specifies whether to print a wall message on shutdown. Inhibit() creates an inhibition lock. It takes four parameters: - What, Who, Why, and - Mode. What is one or more of shutdown, + what, who, why, and + mode. what is one or more of shutdown, sleep, idle, handle-power-key, handle-suspend-key, handle-hibernate-key, handle-lid-switch, separated by colons, for inhibiting poweroff/reboot, - suspend/hibernate, the automatic idle logic, or hardware key handling. Who should be - a short human readable string identifying the application taking the lock. Why + suspend/hibernate, the automatic idle logic, or hardware key handling. who should be + a short human readable string identifying the application taking the lock. why should be a short human readable string identifying the reason why the lock is taken. Finally, - Mode is either block or delay which encodes + mode is either block or delay which encodes whether the inhibit shall be consider mandatory or whether it should just delay the operation to a certain maximum time. The call returns a file descriptor. The lock is released the moment this file descriptor (and all its duplicates) are closed. For more information on the inhibition logic see Inhibitor Locks. - - ListInhibitors() lists all currently active inhibitors. Returns an array of - structures consisting of what, who, why, mode, user ID and process ID. @@ -505,9 +388,9 @@ node /org/freedesktop/login1 { Whenever the inhibition state or idle hint changes daemon PropertyChanged signals are sent out to which clients can subscribe. - The SessionNew(), SessionRemoved(), - UserNew(), UserRemoved(), SeatNew(), - SeatRemoved() signals are sent each time a session is created or removed, a user + The SessionNew, SessionRemoved, + UserNew, UserRemoved, SeatNew, + SeatRemoved signals are sent each time a session is created or removed, a user logs in or out, or a seat is added or removed. They each contain the ID of the object plus the object path. @@ -525,26 +408,126 @@ node /org/freedesktop/login1 { Properties - Most properties simply reflect the configuration stored in logind.conf. For more information, - see - logind.conf5. + Most properties simply reflect the configuration, see + logind.conf5. This + includes: NAutoVTs, KillOnlyUsers, + KillExcludeUsers, KillUserProcesses, IdleAction, + InhibitDelayMaxUSec, + InhibitorsMax, + UserStopDelayUSec, + HandlePowerKey, HandleSuspendKey, + HandleHibernateKey, HandleLidSwitch, + HandleLidSwitchExternalPower, HandleLidSwitchDocked, + IdleActionUSec, HoldoffTimeoutUSec, + RemoveIPC, RuntimeDirectorySize, + InhibitorsMax, and SessionsMax. - The IdleHint property reflects the idle hint state of the system. If the + The IdleHint property reflects the idle hint state of the system. If the system is idle it might get into automatic suspend or shutdown, depending on configuration. - IdleSinceHint and IdleSinceHintMonotonic encode the + IdleSinceHint and IdleSinceHintMonotonic encode the timestamps of the last change of the idle hint boolean, in CLOCK_REALTIME and CLOCK_MONOTONIC timestamps, respectively, in microseconds since the epoch. - The BlockInhibited and DelayInhibited properties encode + The BlockInhibited and DelayInhibited properties encode the currently active locks of the respective modes. They are colon separated lists of shutdown, sleep, idle (see above). - The PreparingForShutdown and PreparingForSleep boolean + NCurrentSessions and NCurrentInhibitors contain the number + of currently registered sessions and inhibitors. + + The BootLoaderEntries property contains a list of boot loader entries. + This includes boot loader entries defined in configuration, and any additional loader entries + reported by the boot loader. See + systemd-boot7 + for more information. + + The PreparingForShutdown and PreparingForSleep boolean properties are true between the time when the two PrepareForShutdown and PrepareForSleep signals are sent, respectively. Note that these properties do not send out PropertyChanged signals. + + The RebootParameter property shows the value set with + SetRebootParameter() method described above. + + The ScheduledShutdown shows the value pair set with + ScheduleShutdown() method described above. + + RebootToFirmwareSetup, RebootToBootLoaderMenu, and + RebootToBootLoaderEntry are true when the resprective post-reboot operation was + selected with SetRebootToFirmwareSetup, + SetRebootToBootLoaderMenu, or + SetRebootToBootLoaderEntry. + + WallMessage and EnableWallMessages properties reflect the + shutdown reasoson and wall message enablement switch which can be set with + SetWallMessage() method described above. + + Docked is true if the machine is connected to dock. + LidClosed is true when the lid (of a laptop) is closed. + OnExternalPower is true when the machine is connected to an external power supply. + + + + + Security + + A number of operations are protected via the PolicyKit privilege + system. SetUserLinger() requires the + org.freedesktop.login1.set-user-linger + privilege. AttachDevice() requires + org.freedesktop.login1.attach-device and + FlushDevices() + org.freedesktop.login1.flush-devices. PowerOff(), + Reboot(), Halt(), Suspend(), + Hibernate() require + org.freedesktop.login1.power-off, + org.freedesktop.login1.power-off-multiple-sessions, + org.freedesktop.login1.power-off-ignore-inhibit, + org.freedesktop.login1.reboot, + org.freedesktop.login1.reboot-multiple-sessions, + org.freedesktop.login1.reboot-ignore-inhibit, + org.freedesktop.login1.halt, + org.freedesktop.login1.halt-multiple-sessions, + org.freedesktop.login1.halt-ignore-inhibit, + org.freedesktop.login1.suspend, + org.freedesktop.login1.suspend-multiple-sessions, + org.freedesktop.login1.suspend-ignore-inhibit, + org.freedesktop.login1.hibernate, + org.freedesktop.login1.hibernate-multiple-sessions, + org.freedesktop.login1.hibernate-ignore-inhibit, + respectively, depending on whether there are other sessions around or active inhibits. + HybridSleep() and SuspendThenHibernate() + use the same privileges as Hibernate(). + SetRebootParameter() requires + org.freedesktop.login1.set-reboot-parameter. + + SetRebootToFirmwareSetup requires + org.freedesktop.login1.set-reboot-to-firmware-setup. + SetRebootToBootLoaderMenu requires + org.freedesktop.login1.set-reboot-to-boot-loader-menu. + SetRebootToBootLoaderEntry requires + org.freedesktop.login1.set-reboot-to-boot-loader-entry. + + + ScheduleShutdown and CancelScheduledShutdown require + the same privileges (listed above) as the immediate poweroff/reboot/halt operations. + + Inhibit() is protected via either one of + org.freedesktop.login1.inhibit-block-shutdown, + org.freedesktop.login1.inhibit-delay-shutdown, + org.freedesktop.login1.inhibit-block-sleep, + org.freedesktop.login1.inhibit-delay-sleep, + org.freedesktop.login1.inhibit-block-idle, + org.freedesktop.login1.inhibit-handle-power-key, + org.freedesktop.login1.inhibit-handle-suspend-key, + org.freedesktop.login1.inhibit-handle-hibernate-key, + org.freedesktop.login1.inhibit-handle-lid-switch depending on the lock + type and mode taken. + + The interactive boolean parameters can be used to control whether PolicyKit + should interactively ask the user for authentication credentials if it needs to. @@ -584,21 +567,17 @@ node /org/freedesktop/login1/seat/seat0 { }; - - - - - - - - - - Methods Terminate() and ActivateSession() work similar to TerminateSeat(), ActivationSessionOnSeat() on the Manager object. + + SwitchTo() switches to the session on the virtual terminal + vtnr. SwitchToNext() and + SwitchToPrevious() switch to, respectively, the next and previous sessions on the + seat in the order of virtual terminals. If there is no active session, they switch to, respectively, + the first and last session on the seat. @@ -618,10 +597,11 @@ node /org/freedesktop/login1/seat/seat0 { ActiveSession encodes the currently active session if there is one. It is a structure consisting of session id and object path. - CanMultiSession encodes whether the session is multi-session capable, CanTTY - whether it is suitable for text logins, CanGraphical whether it is suitable for graphical sessions. + CanMultiSession encodes whether the session is multi-session capable, + CanTTY whether it is suitable for text logins, CanGraphical + whether it is suitable for graphical sessions. - The Sessions array is an array of all current sessions of this seat, each + The Sessions property is an array of all current sessions of this seat, each encoded in a structure consisting of the ID and the object path. The IdleHint, IdleSinceHint, @@ -676,8 +656,6 @@ node /org/freedesktop/login1/user/_1000 { }; - - Methods @@ -733,6 +711,8 @@ node /org/freedesktop/login1/user/_1000 { The IdleHint, IdleSinceHint, IdleSinceHintMonotonic properties encode the idle hint state of the user, similar to the Manager's properties, but specific for this user. + + The Linger property shows whether lingering is enabled for the user. @@ -828,14 +808,6 @@ node /org/freedesktop/login1/session/45 { }; - - - - - - - - Methods @@ -878,6 +850,20 @@ node /org/freedesktop/login1/session/45 { device after receiving a PauseDevice(pause) signal. Forced signals (or after an internal timeout) are automatically completed by systemd-logind asynchronously. + + SetLockedHint() may be used to set the "idle hint" to + locked, i.e. information whether the session is locked. This is intended to be used + by the desktop environment to tell systemd-logind when the session is locked and + unlocked. + + SetBrightness() may be used to set the display brightness. This is intended + to be used by the desktop environment, and allows unprivileged programs to access hardware settings in + a controlled way. The subsystem parameter specifies a kernel subsystem, either + backlight or leds. The name parameter + specifies a device name under the specified subsystem. The brightness parameter + specifies the brightness. The range is defined by individual drivers, see + /sys/class/subsystem/name/max_brightness. + @@ -952,6 +938,9 @@ node /org/freedesktop/login1/session/45 { Service encodes the PAM service name that registered the session. + Desktop describes the desktop environment running in the session (if + known). + Scope contains the systemd scope unit name of this session. Leader encodes the PID of the process that registered the session. @@ -978,6 +967,9 @@ node /org/freedesktop/login1/session/45 { IdleHint, IdleSinceHint, IdleSinceHintMonotonic encapsulate the idle hint state of this session, similarly to how the respective properties on the manager object do it for the whole system. + + LockedHint shows the locked hint state of this session, as set by + SetLockedHint() described above.