From 44fd44f1cf07826dce0688f1caf9000c24aa90c8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Mon, 6 Apr 2020 20:42:12 +0200 Subject: [PATCH 01/26] man: import org.freedesktop.login1(3) from the wiki --- man/org.freedesktop.login1.xml | 767 +++++++++++++++++++++++++++++++++ man/rules/meson.build | 1 + man/systemd-logind.service.xml | 14 +- 3 files changed, 778 insertions(+), 4 deletions(-) create mode 100644 man/org.freedesktop.login1.xml diff --git a/man/org.freedesktop.login1.xml b/man/org.freedesktop.login1.xml new file mode 100644 index 0000000000..2910693865 --- /dev/null +++ b/man/org.freedesktop.login1.xml @@ -0,0 +1,767 @@ + + + + + + + org.freedesktop.login1 + systemd + + + + org.freedesktop.login1 + 5 + + + + org.freedesktop.login1 + The D-Bus interface of systemd-logind + + + + Introduction + + systemd-logind.service8 + is a system service that keeps track of user logins and seats in various ways. + + The daemon provides both a C library interface as well as a D-Bus interface. The library interface + may be used to introspect and watch the state of user logins and seats. The bus interface provides the + same, but in addition may also be used to make changes to system state. For more information please + consult sd-login3. + + + + + The Manager Object + + The service exposes the following interfaces on the Manager object on the bus: + + +$ gdbus introspect --system \ + --dest org.freedesktop.login1 \ + --object-path /org/freedesktop/login1 +node /org/freedesktop/login1 { + interface org.freedesktop.login1.Manager { + methods: + GetSession(in s session_id, + out o object_path); + GetSessionByPID(in u pid, + out o object_path); + GetUser(in u uid, + out o object_path); + GetUserByPID(in u pid, + out o object_path); + GetSeat(in s seat_id, + out o object_path); + ListSessions(out a(susso) session_list); + ListUsers(out a(uso) user_list); + ListSeats(out a(so) seat_list); + ListInhibitors(out a(ssssuu) inhibitor_list); + CreateSession(in u uid, + in u pid, + in s service, + in s type, + in s class, + in s desktop, + in s seat_id, + in u vtnr, + in s tty, + in s display, + in b remote, + in s remote_user, + in s remote_host, + in a(sv) properties, + out s session_id, + out o object_path, + out s runtime_path, + out h fifo_fd, + out u uid, + out s seat_id, + out u vtnr, + out b existing); + ReleaseSession(in s session_id); + ActivateSession(in s session_id); + ActivateSessionOnSeat(in s session_id, + in s seat_id); + LockSession(in s session_id); + UnlockSession(in s session_id); + LockSessions(); + UnlockSessions(); + KillSession(in s session_id, + in s who, + in i signo); + KillUser(in u uid, + in i signo); + TerminateSession(in s session_id); + TerminateUser(in u uid); + TerminateSeat(in s seat_id); + SetUserLinger(in u uid, + in b linger, + in b interactive); + AttachDevice(in s seat_id, + in s sysfs, + in b interactive); + FlushDevices(in b interactive); + PowerOff(in b interactive); + Reboot(in b interactive); + Suspend(in b interactive); + Hibernate(in b interactive); + HybridSleep(in b interactive); + CanPowerOff(out s result); + CanReboot(out s result); + CanSuspend(out s result); + CanHibernate(out s result); + CanHybridSleep(out s result); + ScheduleShutdown(in s type, + in t usec); + CancelScheduledShutdown(out b cancelled); + Inhibit(in s what, + in s who, + in s why, + in s mode, + out h pipe_fd); + CanRebootToFirmwareSetup(out s result); + SetRebootToFirmwareSetup(in b enable); + SetWallMessage(in s wall_message, + in b enable); + signals: + SessionNew(s session_id, + o object_path); + SessionRemoved(s session_id, + o object_path); + UserNew(u uid, + o object_path); + UserRemoved(u uid, + o object_path); + SeatNew(s seat_id, + o object_path); + SeatRemoved(s seat_id, + o object_path); + PrepareForShutdown(b start); + PrepareForSleep(b start); + properties: + readwrite b EnableWallMessages = false; + readwrite s WallMessage = ''; + readonly u NAutoVTs = 6; + readonly as KillOnlyUsers = []; + readonly as KillExcludeUsers = ['root']; + readonly b KillUserProcesses = false; + readonly b RebootToFirmwareSetup = false; + readonly b IdleHint = false; + readonly t IdleSinceHint = 0; + readonly t IdleSinceHintMonotonic = 0; + readonly s BlockInhibited = 'handle-power-key:handle-suspend-key:handle-hibernate-key'; + readonly s DelayInhibited = 'sleep'; + readonly t InhibitDelayMaxUSec = 5000000; + readonly s HandlePowerKey = 'poweroff'; + readonly s HandleSuspendKey = 'suspend'; + readonly s HandleHibernateKey = 'hibernate'; + readonly s HandleLidSwitch = 'suspend'; + readonly s HandleLidSwitchDocked = 'ignore'; + readonly t HoldoffTimeoutUSec = 30000000; + readonly s IdleAction = 'ignore'; + readonly t IdleActionUSec = 1800000000; + readonly b PreparingForShutdown = false; + readonly b PreparingForSleep = false; + readonly (st) ScheduledShutdown = ('', 0); + readonly b Docked = false; + }; + interface org.freedesktop.DBus.Peer { + }; + interface org.freedesktop.DBus.Introspectable { + }; + interface org.freedesktop.DBus.Properties { + }; +}; + + + + 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 + + GetSession() may be used to get the session object path for the session with + the specified ID. Similarly, GetUser() and GetSeat() get the + user and seat objects, respectively. GetSessionByPID() and + GetUserByPID() get the session/user object the specified PID belongs to if there + is any. + + ListSessions() returns an array with all current sessions. The structures in + the array consist of the following fields: session id, user id, user name, seat id, session object + path. If a session does not have a seat attached the seat id field will be an empty string. + + ListUsers() returns an array with all currently logged in users. The + structures in the array consist of the following fields: user id, user name, user object path. + + ListSeats() returns an array with all currently available seats. The + structure in the array consists of the following fields: seat id, seat object path. + + 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 + pam_systemd8 + module. + + ActivateSession() brings the session with the specified ID into the + foreground. ActivateSessionOnSeat() does the same, but only if the seat id + matches. + + LockSession() asks the session with the specified ID to activate the screen + lock. UnlockSession() asks the session with the specified ID to remove an active + screen lock, if there is any. This is implemented by sending out the Lock() and Unlock() signals from + the respective session object which session managers are supposed to listen on. + + LockSessions() asks all sessions to activate the screen locks. This may be + used to lock any access to the machine in one action. Similarly, UnlockSessions() + asks all sessions to deactivate their screen locks. + + KillSession() may be used to send a Unix signal to one or all processes of a + session. As arguments it takes the session id, either the string leader or + all and a signal number. If leader is passed only the session + leader is killed. If all is passed all processes of the session + are killed. + + KillUser() may be used to send a Unix signal to all processes of a user. As + argument it takes the user id and a signal number. + + TerminateSession(), TerminateUser(), + TerminateSeat() may be used to forcibly terminate one specific session, all + processes of a user, and all sessions attached to a specific seat, respectively. The session, user, + and seat are identified by their respective IDs. + + SetUserLinger() enables or disables user lingering. If enabled the runtime + directory of a user is kept around and he may continue to run processes while he is logged out. If + disabled the runtime directory goes away as soon as he logs out. Expects three arguments: the UID, a + boolean whether to enable/disable and a boolean controlling the PolicyKit authorization interactivity + (see above). Note that the user linger state is persistently stored on disk. + + AttachDevice() may be used to assign a specific device to a specific + seat. The device is identified by its /sys path, and must be eligible for seat assignments. Takes three + arguments: the seat id, the sysfs path, and a boolean for controlling PolicyKit interactivity (see + above). Device assignments are persistently stored to disk. To create a new seat, simply specify a + previously unused seat id. For more information about the seat assignment logic see + Multi-Seat for Linux. + + + FlushDevices() removes all explicit seat assignments for devices, resetting + 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. + + 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. + + Inhibit() creates an inhibition lock. It takes four parameters: + 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 + should be a short human readable string identifying the reason why the lock is taken. Finally, + 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. + + + + Signals + + 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 + logs in or out, or a seat is added or removed. They each contain the ID of the object plus the object + path. + + The PrepareForShutdown() and PrepareForSleep() signals + are sent right before (with the argument true) and after (with the argument + false) the system goes down for reboot/poweroff and suspend/hibernate, + respetively. This may be used by applications to save data on disk, release memory, or do other jobs + that shall be done shortly before shutdown/sleep, in conjunction with delay inhibitor locks. After + completion of this work they should release their inhibition locks in order not to delay the operation + any further. For more information see + Inhibitor Locks. + + + + + Properties + + Most properties simply reflect the configuration stored in logind.conf. For more information, + see + logind.conf5. + + + 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 + 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 currently active locks of the respective modes. They are colon separated lists of + shutdown, sleep, idle (see above). + + 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. + + + + + Seat Objects + + +$ gdbus introspect --system --dest org.freedesktop.login1 \ + --object-path /org/freedesktop/login1/seat/seat0 +node /org/freedesktop/login1/seat/seat0 { + interface org.freedesktop.login1.Seat { + methods: + Terminate(); + ActivateSession(in s session_id); + SwitchTo(in u vtnr); + SwitchToNext(); + SwitchToPrevious(); + properties: + readonly s Id = 'seat0'; + readonly (so) ActiveSession = ('', '/'); + readonly b CanMultiSession = true; + readonly b CanTTY = true; + readonly b CanGraphical = true; + readonly a(so) Sessions = [('c1', '/org/freedesktop/login1/session/c1')]; + readonly b IdleHint = true; + readonly t IdleSinceHint = 1389368976087311; + readonly t IdleSinceHintMonotonic = 48213948; + }; + interface org.freedesktop.DBus.Properties { + }; + interface org.freedesktop.DBus.Peer { + }; + interface org.freedesktop.DBus.Introspectable { + }; +}; + + + + Methods + + Terminate() and ActivateSession() work similar to + TerminateSeat(), ActivationSessionOnSeat() on the Manager object. + + + + Signals + + Whenever ActiveSession, Sessions, + CanGraphical, CanMultiSession and CanTTY + or the idle state changes PropertyChanged signals are sent out to which clients + can subscribe. + + + + Properties + + The Id property encodes the ID of the seat. + + 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. + + The Sessions array 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, + IdleSinceHint properties encode the idle state, similar to the one exposed on the + Manager object, but specific for this seat. + + + + + User Objects + + +$ gdbus introspect --system --dest org.freedesktop.login1 \ + --object-path /org/freedesktop/login1/user/_1000 + +node /org/freedesktop/login1/user/_1000 { + interface org.freedesktop.login1.User { + methods: + Terminate(); + Kill(in i signo); + properties: + readonly u UID = 1000; + readonly u GID = 1000; + readonly s Name = 'test'; + readonly t Timestamp = 1389368964102424; + readonly t TimestampMonotonic = 36229061; + readonly s RuntimePath = '/run/user/1000'; + readonly s Service = 'user@1000.service'; + readonly s Slice = 'user-1000.slice'; + readonly (so) Display = ('', '/'); + readonly s State = 'active'; + readonly a(so) Sessions = [('28', '/org/freedesktop/login1/session/_328'), ('3', '/org/freedesktop/login1/session/_33')]; + readonly b IdleHint = false; + readonly t IdleSinceHint = 0; + readonly t IdleSinceHintMonotonic = 0; + readonly b Linger = false; + }; + interface org.freedesktop.DBus.Properties { + }; + interface org.freedesktop.DBus.Peer { + }; + interface org.freedesktop.DBus.Introspectable { + }; +}; + + + + Methods + + Terminate() and Kill() work similar to the + TerminateUser() and KillUser() calls on the manager + object. + + + + Signals + + Whenever Sessions or the idle state changes + PropertyChanged signals are sent out to which clients can subscribe. + + + + Properties + + The UID and GID properties encode the Unix UID and primary + GID of the user. + + The Name property encodes the user name. + + Timestamp and TimestampMonotonic encode the login time of + the user in usec since the epoch, in the CLOCK_REALTIME and + CLOCK_MONOTONIC clocks, respectively. + + RuntimePath encodes the runtime path of the user, + i.e. $XDG_RUNTIME_DIR, for details see the + + XDG Basedir Specification + . + + Service contains the name of the user systemd service unit name of this + user. Each logged in user gets a user service unit assigned that runs a user systemd instance. This is + usually an instance of user@.service. + + Slice contains the name of the user systemd slice unit name of this user. Each + logged in user gets a private slice. + + Display encodes which graphical session should be used as primary UI display + for the use. It is a structure encoding session ID and object path of the session to use. + + State encodes the user state, one of offline, + lingering, online, active, + closing. See + sd_uid_get_state3 + for more information about the states. + + Sessions is an array of structures encoding all current sessions of the + user. Each structure consists of ID and object path. + + The IdleHint, IdleSinceHint, + IdleSinceHintMonotonic properties encode the idle hint state of the user, similar to + the Manager's properties, but specific for this user. + + + + + Session Objects + + +$ gdbus introspect --system --dest org.freedesktop.login1 \ + --object-path /org/freedesktop/login1/session/3 + +node /org/freedesktop/login1/session/3 { + interface org.freedesktop.login1.Session { + methods: + Terminate(); + Activate(); + Lock(); + Unlock(); + SetIdleHint(in b idle); + Kill(in s who, + in i signo); + TakeControl(in b force); + ReleaseControl(); + TakeDevice(in u major, + in u minor, + out h fd, + out b inactive); + ReleaseDevice(in u major, + in u minor); + PauseDeviceComplete(in u major, + in u minor); + signals: + PauseDevice(u major, + u minor, + s type); + ResumeDevice(u major, + u minor, + h fd); + Lock(); + Unlock(); + properties: + readonly s Id = '3'; + readonly (uo) User = (1000, '/org/freedesktop/login1/user/_1000'); + readonly s Name = 'test'; + readonly t Timestamp = 1389370644734067; + readonly t TimestampMonotonic = 72063381; + readonly u VTNr = 0; + readonly (so) Seat = ('', '/'); + readonly s TTY = ''; + readonly s Display = ''; + readonly b Remote = true; + readonly s RemoteHost = '129.174.150.217'; + readonly s RemoteUser = ''; + readonly s Service = 'sshd'; + readonly s Desktop = ''; + readonly s Scope = 'session-3.scope'; + readonly u Leader = 1854; + readonly u Audit = 3; + readonly s Type = 'tty'; + readonly s Class = 'user'; + readonly b Active = true; + readonly s State = 'active'; + readonly b IdleHint = false; + readonly t IdleSinceHint = 0; + readonly t IdleSinceHintMonotonic = 0; + }; + interface org.freedesktop.DBus.Properties { + }; + interface org.freedesktop.DBus.Peer { + }; + interface org.freedesktop.DBus.Introspectable { + }; +}; + + + + Methods + + Terminate(), Activate(), Lock(), + Unlock(), Kill() work similarly to the respective calls on + the Manager object. + + SetIdleHint() shall be called by the session object to update the idle state + of the session, whenever it changes. + + TakeControl() allows a process to take exclusive managed device + access-control for that session. Only one dbus-connection can be a controller for a given session at a + time. If the force argument is set (root only), an existing controller is kicked + out and replaced. Otherwise, this call fails if there is already a controller. Note that this call is + limited to dbus-users with the effective UID set to the User of the Session or root. + + ReleaseControl() drops control of a given session again. Closing the + dbus-connection implicitly releases control, too. See TakeControl() for more. This + also releases all devices for the controller that were requested via TakeDevice(). + + + TakeDevice() allows a session-controller to get a file-descriptor for a + specific device. Pass in the major and minor numbers of the character-device and + systemd-logind will return a file-descriptor for the device. Only a limited set of + device-types is currently supported (but may be extended). systemd-logind + automatically mutes the file-descriptor if the session is inactive and resumes it once the session gets + active again. This guarantees that a session can only access session-devices if the session is + active. Note that this revoke/resume mechanism is asynchronous and may happen at any given time. This + only works on devices that are attached to the seat of the given session. A process is not required to + have direct access to the device-node. systemd-logind only requires you to be the + active session controller (see TakeControl()). Also note that any device can only + be requested once. As long as you don't release it, further TakeDevice() calls + will fail. + + ReleaseDevice() releases a device again (see + TakeDevice()). This is also implicitly done by + ReleaseControl() or when closing the dbus-connection. + + PauseDeviceComplete() allows a session-controller to synchronously pause a + device after receiving a PauseDevice(pause) signal. Forced + signals (or after an internal timeout) are automatically completed by + systemd-logind asynchronously. + + + + Signals + + The active session-controller exclusively gets PauseDevice and + ResumeDevice events for any device it requested via + TakeDevice(). They notify the controller whenever a device is paused or resumed. A + device is never resumed if a session is inactive. Also note that PauseDevice + signals are sent before the PropertyChanged signal for the + Active state. The inverse is true for ResumeDevice. A device + may remain paused for unknown reasons even though the Session is active. + + + A PauseDevice signal carries the major and minor and a string describing the + type as arguments. force means the device got paused by + systemd-logind already and this is only an asynchronous + notification. pause means systemd-logind tries to pause the + device and grants you limited amount of time to pause it. You must respond to this via + PauseDeviceComplete(). This synchronous pausing-mechanism is used for + backwards-compatibility to VTs and systemd-logind is free to not make use of + it. It is also free to send a forced PauseDevice if you don't respond in a timely + manner (or for any other reason). gone means the device was unplugged from the + system and you will no longer get any notifications about it. There is no reason to call + ReleaseDevice(). You may call TakeDevice() again if a new + device gets the major+minor combination assigned. + + ResumeDevice is sent whenever a session is active and a device is + resumed. It carries the major/minor as arguments and provides a new open file-descriptor. You should + switch to the new descriptor and close the old one. They are not guaranteed to have the same underlying + open-file-descriptor in the kernel (except for a limited set of device types). + + Whenever Active or the idle state changes + PropertyChanged signals are sent out to which clients can subscribe. + + Lock/Unlock is sent when the session is asked to be + screen-locked/unlocked. A session manager of the session should listen to this signal and act + accordingly. This signal is sent out as a result of the Lock() and + Unlock() methods, respectively. + + + + Properties + + Id encodes the session ID. + + User encodes the user ID of the user this session belongs to. This is a + structure encoding the Unix UID and the object path. + + Name encodes the user name. + + Timestamp and TimestampMonotonic encode the usec timestamp + since the epoch when the session was created, in CLOCK_REALTIME or + CLOCK_MONOTONIC, respectively. + + VTNr encodes the virtual terminal number of the session if there is any, 0 + otherwise. + + Seat encodes the seat this session belongs to, if there is any. This is a + structure consisting of the ID and the seat object path. + + TTY encodes the kernel TTY path of the session if this is a text login. If not + this is an empty string. + + Display encodes the X11 display name if this is a graphical login. If not, + this is an empty string. + + Remote encodes whether the session is local or remote. + + RemoteHost and RemoteUser encode the remote host and user + if this is a remote session, or an empty string otherwise. + + Service encodes the PAM service name that registered the session. + + Scope contains the systemd scope unit name of this session. + + Leader encodes the PID of the process that registered the session. + + Audit encodes the Kernel Audit session ID of the session, if auditing is + available. + + Type encodes the session type. It's one of unspecified (for + cron PAM sessions and suchlike), tty (for text logins) or + x11/mir/wayland (for graphical logins). + + Class encodes the session class. It's one of user (for + normal user sessions), greeter (for display manager pseudo-sessions), + lock-screen (for display lock screens). + + Active is a boolean that is true if the session is active, i.e. currently in the + foreground. This field is semi-redundant due to State. + + State encodes the session state and one of online, + active, closing. See + sd_session_get_state3 + for more information about the states. + + 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. + + + + + Versioning + + These D-Bus interfaces follow + the usual interface versioning guidelines. + + diff --git a/man/rules/meson.build b/man/rules/meson.build index 9cdfe5d291..4e57b94bbf 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -44,6 +44,7 @@ manpages = [ ['nss-mymachines', '8', ['libnss_mymachines.so.2'], 'ENABLE_NSS_MYMACHINES'], ['nss-resolve', '8', ['libnss_resolve.so.2'], 'ENABLE_NSS_RESOLVE'], ['nss-systemd', '8', ['libnss_systemd.so.2'], 'ENABLE_NSS_SYSTEMD'], + ['org.freedesktop.login1', '5', [], 'ENABLE_LOGIND'], ['os-release', '5', [], ''], ['pam_systemd', '8', [], 'HAVE_PAM'], ['pam_systemd_home', '8', [], 'ENABLE_PAM_HOME'], diff --git a/man/systemd-logind.service.xml b/man/systemd-logind.service.xml index a66c53d076..87ee607c6c 100644 --- a/man/systemd-logind.service.xml +++ b/man/systemd-logind.service.xml @@ -78,14 +78,20 @@ for information about the basic concepts of logind such as users, sessions and seats. - See the - logind D-Bus API Documentation for information about the - APIs systemd-logind provides. + See + org.freedesktop.login13 + for for information about the D-Bus APIs systemd-logind provides. For more information on the inhibition logic see the Inhibitor Lock Developer Documentation. + + If you are interested in writing a display manager that makes use of logind, please have look at + Writing Display + Manager. + If you are interested in writing a desktop environment that makes use of logind, please have look at + Writing + Desktop Environments. From 4cb5fd0da820b07b0b37b2c709cc1da755d0f191 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Wed, 8 Apr 2020 23:34:17 +0200 Subject: [PATCH 02/26] logind: add dbus parameter names --- src/login/logind-dbus.c | 441 +++++++++++++++++++++++++++----- src/login/logind-seat-dbus.c | 16 +- src/login/logind-session-dbus.c | 108 ++++++-- src/login/logind-user-dbus.c | 7 +- 4 files changed, 495 insertions(+), 77 deletions(-) diff --git a/src/login/logind-dbus.c b/src/login/logind-dbus.c index 15201f900f..92a71ccbf2 100644 --- a/src/login/logind-dbus.c +++ b/src/login/logind-dbus.c @@ -3360,66 +3360,389 @@ const sd_bus_vtable manager_vtable[] = { SD_BUS_PROPERTY("NCurrentSessions", "t", property_get_hashmap_size, offsetof(Manager, sessions), 0), SD_BUS_PROPERTY("UserTasksMax", "t", property_get_compat_user_tasks_max, 0, SD_BUS_VTABLE_PROPERTY_CONST|SD_BUS_VTABLE_HIDDEN), - SD_BUS_METHOD("GetSession", "s", "o", method_get_session, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetSessionByPID", "u", "o", method_get_session_by_pid, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetUser", "u", "o", method_get_user, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetUserByPID", "u", "o", method_get_user_by_pid, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetSeat", "s", "o", method_get_seat, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ListSessions", NULL, "a(susso)", method_list_sessions, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ListUsers", NULL, "a(uso)", method_list_users, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ListSeats", NULL, "a(so)", method_list_seats, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ListInhibitors", NULL, "a(ssssuu)", method_list_inhibitors, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("CreateSession", "uusssssussbssa(sv)", "soshusub", method_create_session, 0), - SD_BUS_METHOD("ReleaseSession", "s", NULL, method_release_session, 0), - SD_BUS_METHOD("ActivateSession", "s", NULL, method_activate_session, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ActivateSessionOnSeat", "ss", NULL, method_activate_session_on_seat, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("LockSession", "s", NULL, method_lock_session, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("UnlockSession", "s", NULL, method_lock_session, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("LockSessions", NULL, NULL, method_lock_sessions, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("UnlockSessions", NULL, NULL, method_lock_sessions, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("KillSession", "ssi", NULL, method_kill_session, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("KillUser", "ui", NULL, method_kill_user, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("TerminateSession", "s", NULL, method_terminate_session, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("TerminateUser", "u", NULL, method_terminate_user, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("TerminateSeat", "s", NULL, method_terminate_seat, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetUserLinger", "ubb", NULL, method_set_user_linger, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("AttachDevice", "ssb", NULL, method_attach_device, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("FlushDevices", "b", NULL, method_flush_devices, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("PowerOff", "b", NULL, method_poweroff, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("Reboot", "b", NULL, method_reboot, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("Halt", "b", NULL, method_halt, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("Suspend", "b", NULL, method_suspend, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("Hibernate", "b", NULL, method_hibernate, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("HybridSleep", "b", NULL, method_hybrid_sleep, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SuspendThenHibernate", "b", NULL, method_suspend_then_hibernate, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("CanPowerOff", NULL, "s", method_can_poweroff, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("CanReboot", NULL, "s", method_can_reboot, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("CanHalt", NULL, "s", method_can_halt, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("CanSuspend", NULL, "s", method_can_suspend, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("CanHibernate", NULL, "s", method_can_hibernate, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("CanHybridSleep", NULL, "s", method_can_hybrid_sleep, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("CanSuspendThenHibernate", NULL, "s", method_can_suspend_then_hibernate, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ScheduleShutdown", "st", NULL, method_schedule_shutdown, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("CancelScheduledShutdown", NULL, "b", method_cancel_scheduled_shutdown, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("Inhibit", "ssss", "h", method_inhibit, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("CanRebootParameter", NULL, "s", method_can_reboot_parameter, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetRebootParameter", "s", NULL, method_set_reboot_parameter, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("CanRebootToFirmwareSetup", NULL, "s", method_can_reboot_to_firmware_setup, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetRebootToFirmwareSetup", "b", NULL, method_set_reboot_to_firmware_setup, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("CanRebootToBootLoaderMenu", NULL, "s", method_can_reboot_to_boot_loader_menu, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetRebootToBootLoaderMenu", "t", NULL, method_set_reboot_to_boot_loader_menu, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("CanRebootToBootLoaderEntry", NULL, "s", method_can_reboot_to_boot_loader_entry, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetRebootToBootLoaderEntry", "s", NULL, method_set_reboot_to_boot_loader_entry, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetWallMessage", "sb", NULL, method_set_wall_message, SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetSession", + "s", + SD_BUS_PARAM(session_id), + "o", + SD_BUS_PARAM(object_path), + method_get_session, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetSessionByPID", + "u", + SD_BUS_PARAM(pid), + "o", + SD_BUS_PARAM(object_path), + method_get_session_by_pid, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetUser", + "u", + SD_BUS_PARAM(uid), + "o", + SD_BUS_PARAM(object_path), + method_get_user, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetUserByPID", + "u", + SD_BUS_PARAM(pid), + "o", + SD_BUS_PARAM(object_path), + method_get_user_by_pid, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetSeat", + "s", + SD_BUS_PARAM(seat_id), + "o", + SD_BUS_PARAM(object_path), + method_get_seat, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("ListSessions", + NULL,, + "a(susso)", + SD_BUS_PARAM(sessions), + method_list_sessions, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("ListUsers", + NULL,, + "a(uso)", + SD_BUS_PARAM(users), + method_list_users, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("ListSeats", + NULL,, + "a(so)", + SD_BUS_PARAM(seats), + method_list_seats, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("ListInhibitors", + NULL,, + "a(ssssuu)", + SD_BUS_PARAM(inhibitors), + method_list_inhibitors, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("CreateSession", + "uusssssussbssa(sv)", + SD_BUS_PARAM(uid) + SD_BUS_PARAM(pid) + SD_BUS_PARAM(service) + SD_BUS_PARAM(type) + SD_BUS_PARAM(class) + SD_BUS_PARAM(desktop) + SD_BUS_PARAM(seat_id) + SD_BUS_PARAM(vtnr) + SD_BUS_PARAM(tty) + SD_BUS_PARAM(display) + SD_BUS_PARAM(remote) + SD_BUS_PARAM(remote_user) + SD_BUS_PARAM(remote_host) + SD_BUS_PARAM(properties), + "soshusub", + SD_BUS_PARAM(session_id) + SD_BUS_PARAM(object_path) + SD_BUS_PARAM(runtime_path) + SD_BUS_PARAM(fifo_fd) + SD_BUS_PARAM(uid) + SD_BUS_PARAM(seat_id) + SD_BUS_PARAM(vtnr) + SD_BUS_PARAM(existing), + method_create_session, + 0), + SD_BUS_METHOD_WITH_NAMES("ReleaseSession", + "s", + SD_BUS_PARAM(session_id), + NULL,, + method_release_session, + 0), + SD_BUS_METHOD_WITH_NAMES("ActivateSession", + "s", + SD_BUS_PARAM(session_id), + NULL,, + method_activate_session, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("ActivateSessionOnSeat", + "ss", + SD_BUS_PARAM(session_id) + SD_BUS_PARAM(seat_id), + NULL,, + method_activate_session_on_seat, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("LockSession", + "s", + SD_BUS_PARAM(session_id), + NULL,, + method_lock_session, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("UnlockSession", + "s", + SD_BUS_PARAM(session_id), + NULL,, + method_lock_session, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD("LockSessions", + NULL, + NULL, + method_lock_sessions, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD("UnlockSessions", + NULL, + NULL, + method_lock_sessions, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("KillSession", + "ssi", + SD_BUS_PARAM(session_id) + SD_BUS_PARAM(who) + SD_BUS_PARAM(signal_number), + NULL,, + method_kill_session, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("KillUser", + "ui", + SD_BUS_PARAM(uid) + SD_BUS_PARAM(signal_number), + NULL,, + method_kill_user, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("TerminateSession", + "s", + SD_BUS_PARAM(session_id), + NULL,, + method_terminate_session, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("TerminateUser", + "u", + SD_BUS_PARAM(uid), + NULL,, + method_terminate_user, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("TerminateSeat", + "s", + SD_BUS_PARAM(seat_id), + NULL,, + method_terminate_seat, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetUserLinger", + "ubb", + SD_BUS_PARAM(uid) + SD_BUS_PARAM(enable) + SD_BUS_PARAM(interactive), + NULL,, + method_set_user_linger, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("AttachDevice", + "ssb", + SD_BUS_PARAM(seat_id) + SD_BUS_PARAM(sysfs_path) + SD_BUS_PARAM(interactive), + NULL,, + method_attach_device, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("FlushDevices", + "b", + SD_BUS_PARAM(interactive), + NULL,, + method_flush_devices, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("PowerOff", + "b", + SD_BUS_PARAM(interactive), + NULL,, + method_poweroff, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("Reboot", + "b", + SD_BUS_PARAM(interactive), + NULL,, + method_reboot, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("Halt", + "b", + SD_BUS_PARAM(interactive), + NULL,, + method_halt, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("Suspend", + "b", + SD_BUS_PARAM(interactive), + NULL,, + method_suspend, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("Hibernate", + "b", + SD_BUS_PARAM(interactive), + NULL,, + method_hibernate, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("HybridSleep", + "b", + SD_BUS_PARAM(interactive), + NULL,, + method_hybrid_sleep, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SuspendThenHibernate", + "b", + SD_BUS_PARAM(interactive), + NULL,, + method_suspend_then_hibernate, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("CanPowerOff", + NULL,, + "s", + SD_BUS_PARAM(result), + method_can_poweroff, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("CanReboot", + NULL,, + "s", + SD_BUS_PARAM(result), + method_can_reboot, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("CanHalt", + NULL,, + "s", + SD_BUS_PARAM(result), + method_can_halt, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("CanSuspend", + NULL,, + "s", + SD_BUS_PARAM(result), + method_can_suspend, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("CanHibernate", + NULL,, + "s", + SD_BUS_PARAM(result), + method_can_hibernate, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("CanHybridSleep", + NULL,, + "s", + SD_BUS_PARAM(result), + method_can_hybrid_sleep, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("CanSuspendThenHibernate", + NULL,, + "s", + SD_BUS_PARAM(result), + method_can_suspend_then_hibernate, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("ScheduleShutdown", + "st", + SD_BUS_PARAM(type) + SD_BUS_PARAM(usec), + NULL,, + method_schedule_shutdown, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("CancelScheduledShutdown", + NULL,, + "b", + SD_BUS_PARAM(cancelled), + method_cancel_scheduled_shutdown, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("Inhibit", + "ssss", + SD_BUS_PARAM(what) + SD_BUS_PARAM(who) + SD_BUS_PARAM(why) + SD_BUS_PARAM(mode), + "h", + SD_BUS_PARAM(pipe_fd), + method_inhibit, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("CanRebootParameter", + NULL,, + "s", + SD_BUS_PARAM(result), + method_can_reboot_parameter, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetRebootParameter", + "s", + SD_BUS_PARAM(parameter), + NULL,, + method_set_reboot_parameter, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("CanRebootToFirmwareSetup", + NULL,, + "s", + SD_BUS_PARAM(result), + method_can_reboot_to_firmware_setup, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetRebootToFirmwareSetup", + "b", + SD_BUS_PARAM(enable), + NULL,, + method_set_reboot_to_firmware_setup, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("CanRebootToBootLoaderMenu", + NULL,, + "s", + SD_BUS_PARAM(result), + method_can_reboot_to_boot_loader_menu, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetRebootToBootLoaderMenu", + "t", + SD_BUS_PARAM(timeout), + NULL,, + method_set_reboot_to_boot_loader_menu, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("CanRebootToBootLoaderEntry", + NULL,, + "s", + SD_BUS_PARAM(result), + method_can_reboot_to_boot_loader_entry, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetRebootToBootLoaderEntry", + "s", + SD_BUS_PARAM(boot_loader_entry), + NULL,, + method_set_reboot_to_boot_loader_entry, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetWallMessage", + "sb", + SD_BUS_PARAM(wall_message) + SD_BUS_PARAM(enable), + NULL,, + method_set_wall_message, + SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_SIGNAL("SessionNew", "so", 0), - SD_BUS_SIGNAL("SessionRemoved", "so", 0), - SD_BUS_SIGNAL("UserNew", "uo", 0), - SD_BUS_SIGNAL("UserRemoved", "uo", 0), - SD_BUS_SIGNAL("SeatNew", "so", 0), - SD_BUS_SIGNAL("SeatRemoved", "so", 0), - SD_BUS_SIGNAL("PrepareForShutdown", "b", 0), - SD_BUS_SIGNAL("PrepareForSleep", "b", 0), + SD_BUS_SIGNAL_WITH_NAMES("SessionNew", + "so", + SD_BUS_PARAM(session_id) + SD_BUS_PARAM(object_path), + 0), + SD_BUS_SIGNAL_WITH_NAMES("SessionRemoved", + "so", + SD_BUS_PARAM(session_id) + SD_BUS_PARAM(object_path), + 0), + SD_BUS_SIGNAL_WITH_NAMES("UserNew", + "uo", + SD_BUS_PARAM(uid) + SD_BUS_PARAM(object_path), + 0), + SD_BUS_SIGNAL_WITH_NAMES("UserRemoved", + "uo", + SD_BUS_PARAM(uid) + SD_BUS_PARAM(object_path), + 0), + SD_BUS_SIGNAL_WITH_NAMES("SeatNew", + "so", + SD_BUS_PARAM(seat_id) + SD_BUS_PARAM(object_path), + 0), + SD_BUS_SIGNAL_WITH_NAMES("SeatRemoved", + "so", + SD_BUS_PARAM(seat_id) + SD_BUS_PARAM(object_path), + 0), + SD_BUS_SIGNAL_WITH_NAMES("PrepareForShutdown", + "b", + SD_BUS_PARAM(start), + 0), + SD_BUS_SIGNAL_WITH_NAMES("PrepareForSleep", + "b", + SD_BUS_PARAM(start), + 0), SD_BUS_VTABLE_END }; diff --git a/src/login/logind-seat-dbus.c b/src/login/logind-seat-dbus.c index 0a5df937cc..30fc18b5db 100644 --- a/src/login/logind-seat-dbus.c +++ b/src/login/logind-seat-dbus.c @@ -305,8 +305,20 @@ const sd_bus_vtable seat_vtable[] = { SD_BUS_PROPERTY("IdleSinceHintMonotonic", "t", property_get_idle_since_hint, 0, SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE), SD_BUS_METHOD("Terminate", NULL, NULL, bus_seat_method_terminate, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ActivateSession", "s", NULL, method_activate_session, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SwitchTo", "u", NULL, method_switch_to, SD_BUS_VTABLE_UNPRIVILEGED), + + SD_BUS_METHOD_WITH_NAMES("ActivateSession", + "s", + SD_BUS_PARAM(session_id), + NULL,, + method_activate_session, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SwitchTo", + "u", + SD_BUS_PARAM(vtnr), + NULL,, + method_switch_to, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD("SwitchToNext", NULL, NULL, method_switch_to_next, SD_BUS_VTABLE_UNPRIVILEGED), SD_BUS_METHOD("SwitchToPrevious", NULL, NULL, method_switch_to_previous, SD_BUS_VTABLE_UNPRIVILEGED), diff --git a/src/login/logind-session-dbus.c b/src/login/logind-session-dbus.c index 80ec89ba0a..69bf0986f2 100644 --- a/src/login/logind-session-dbus.c +++ b/src/login/logind-session-dbus.c @@ -583,22 +583,100 @@ const sd_bus_vtable session_vtable[] = { SD_BUS_PROPERTY("IdleSinceHintMonotonic", "t", property_get_idle_since_hint, 0, SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE), SD_BUS_PROPERTY("LockedHint", "b", property_get_locked_hint, 0, SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE), - SD_BUS_METHOD("Terminate", NULL, NULL, bus_session_method_terminate, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("Activate", NULL, NULL, bus_session_method_activate, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("Lock", NULL, NULL, bus_session_method_lock, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("Unlock", NULL, NULL, bus_session_method_lock, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetIdleHint", "b", NULL, method_set_idle_hint, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetLockedHint", "b", NULL, method_set_locked_hint, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("Kill", "si", NULL, bus_session_method_kill, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("TakeControl", "b", NULL, method_take_control, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ReleaseControl", NULL, NULL, method_release_control, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("TakeDevice", "uu", "hb", method_take_device, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ReleaseDevice", "uu", NULL, method_release_device, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("PauseDeviceComplete", "uu", NULL, method_pause_device_complete, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetBrightness", "ssu", NULL, method_set_brightness, SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD("Terminate", + NULL, + NULL, + bus_session_method_terminate, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD("Activate", + NULL, + NULL, + bus_session_method_activate, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD("Lock", + NULL, + NULL, + bus_session_method_lock, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD("Unlock", + NULL, + NULL, + bus_session_method_lock, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetIdleHint", + "b", + SD_BUS_PARAM(idle), + NULL,, + method_set_idle_hint, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetLockedHint", + "b", + SD_BUS_PARAM(locked), + NULL,, + method_set_locked_hint, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("Kill", + "si", + SD_BUS_PARAM(who) + SD_BUS_PARAM(signal_number), + NULL,, + bus_session_method_kill, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("TakeControl", + "b", + SD_BUS_PARAM(force), + NULL,, + method_take_control, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD("ReleaseControl", + NULL, + NULL, + method_release_control, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("TakeDevice", + "uu", + SD_BUS_PARAM(major) + SD_BUS_PARAM(minor), + "hb", + SD_BUS_PARAM(fd) + SD_BUS_PARAM(inactive), + method_take_device, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("ReleaseDevice", + "uu", + SD_BUS_PARAM(major) + SD_BUS_PARAM(minor), + NULL,, + method_release_device, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("PauseDeviceComplete", + "uu", + SD_BUS_PARAM(major) + SD_BUS_PARAM(minor), + NULL,, + method_pause_device_complete, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetBrightness", + "ssu", + SD_BUS_PARAM(subsystem) + SD_BUS_PARAM(name) + SD_BUS_PARAM(brightness), + NULL,, + method_set_brightness, + SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_SIGNAL("PauseDevice", "uus", 0), - SD_BUS_SIGNAL("ResumeDevice", "uuh", 0), + SD_BUS_SIGNAL_WITH_NAMES("PauseDevice", + "uus", + SD_BUS_PARAM(major) + SD_BUS_PARAM(minor) + SD_BUS_PARAM(type), + 0), + SD_BUS_SIGNAL_WITH_NAMES("ResumeDevice", + "uuh", + SD_BUS_PARAM(major) + SD_BUS_PARAM(minor) + SD_BUS_PARAM(fd), + 0), SD_BUS_SIGNAL("Lock", NULL, 0), SD_BUS_SIGNAL("Unlock", NULL, 0), diff --git a/src/login/logind-user-dbus.c b/src/login/logind-user-dbus.c index 9bf68a610e..f247567935 100644 --- a/src/login/logind-user-dbus.c +++ b/src/login/logind-user-dbus.c @@ -277,7 +277,12 @@ const sd_bus_vtable user_vtable[] = { SD_BUS_PROPERTY("Linger", "b", property_get_linger, 0, 0), SD_BUS_METHOD("Terminate", NULL, NULL, bus_user_method_terminate, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("Kill", "i", NULL, bus_user_method_kill, SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("Kill", + "i", + SD_BUS_PARAM(signal_number), + NULL,, + bus_user_method_kill, + SD_BUS_VTABLE_UNPRIVILEGED), SD_BUS_VTABLE_END }; From de2efb75f72a732c82d36b015b190a4fe892672e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Tue, 7 Apr 2020 21:22:13 +0200 Subject: [PATCH 03/26] man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. org.foo.bar is used for interface names, function() for methods, and signal (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them. --- man/org.freedesktop.machine1.xml | 406 +++++++++++++++++++++++++++++++ man/rules/meson.build | 1 + man/systemd-machined.service.xml | 91 ++++++- 3 files changed, 486 insertions(+), 12 deletions(-) create mode 100644 man/org.freedesktop.machine1.xml diff --git a/man/org.freedesktop.machine1.xml b/man/org.freedesktop.machine1.xml new file mode 100644 index 0000000000..d089081a45 --- /dev/null +++ b/man/org.freedesktop.machine1.xml @@ -0,0 +1,406 @@ + + + + + + + org.freedesktop.machine1 + systemd + + + + org.freedesktop.machine1 + 5 + + + + org.freedesktop.machine1 + The D-Bus interface of systemd-machined + + + + Introduction + + + systemd-machined.service8 + is a system service that keeps track of locally running virtual machines and containers. + This page describes the D-Bus interface. + + + + The Manager Object + + The service exposes the following interfaces on the Manager object on the bus: + + +$ gdbus introspect --system \ + --dest org.freedesktop.machine1 \ + --object-path /org/freedesktop/machine1 + +node /org/freedesktop/machine1 { + interface org.freedesktop.machine1.Manager { + methods: + GetMachine(in s name, + out o machine); + GetImage(in s name, + out o image); + GetMachineByPID(in u pid, + out o machine); + ListMachines(out a(ssso) machines); + ListImages(out a(ssbttto) machines); + CreateMachine(in s name, + in ay id, + in s service, + in s class, + in u leader, + in s root_directory, + in a(sv) scope_properties, + out o path); + CreateMachineWithNetwork(in s name, + in ay id, + in s service, + in s class, + in u leader, + in s root_directory, + in ai ifindices, + in a(sv) scope_properties, + out o path); + RegisterMachine(in s name, + in ay id, + in s service, + in s class, + in u leader, + in s root_directory, + out o path); + RegisterMachineWithNetwork(in s name, + in ay id, + in s service, + in s class, + in u leader, + in s root_directory, + in ai ifindices, + out o path); + KillMachine(in s name, + in s who, + in s signal); + TerminateMachine(in s id); + GetMachineAddresses(in s name, + out a(iay) addresses); + GetMachineOSRelease(in s name, + out a{ss} fields); + OpenMachinePTY(in s name, + out h pty, + out s pty_path); + OpenMachineLogin(in s name, + out h pty, + out s pty_path); + OpenMachineShell(in s name, + in s user, + in s path, + in as args, + in as environment, + out h pty, + out s pty_path); + BindMountMachine(in s name, + in s source, + in s destination, + in b read_only, + in b mkdir); + CopyFromMachine(in s name, + in s source, + in s destination); + CopyToMachine(in s name, + in s source, + in s destination); + RemoveImage(in s name); + RenameImage(in s name, + in s new_name); + CloneImage(in s name, + in s new_name, + in b read_only); + MarkImageReadOnly(in s name, + in b read_only); + SetPoolLimit(in t size); + SetImageLimit(in s name, + in t size); + MapFromMachineUser(in s name, + in u uid_inner, + out u uid_outer); + MapToMachineUser(in u uid_outer, + out s machine_name, + out o machine_path, + out u uid_inner; + MapFromMachineGroup(in s name, + in u gid_inner, + out u gid_outer); + MapToMachineGroup(in u gid_outer, + out s machine_name, + out o machine_path, + out u gid_inner); + signals: + MachineNew(s machine, + o path); + MachineRemoved(s machine, + o path); + properties: + readonly s PoolPath = '/var/lib/machines'; + readonly t PoolUsage = 18446744070652059648; + readonly t PoolLimit = 2160721920; + }; + interface org.freedesktop.DBus.Properties { + }; + interface org.freedesktop.DBus.Peer { + }; + interface org.freedesktop.DBus.Introspectable { + }; +}; + + + + Methods + + GetMachine() may be used to get the machine object path for the machine with + the specified name. Similarly, GetMachineByPID() get the machine object the + specified PID belongs to if there is any. + + GetImage() may be used to the the image object path for the image with the + specified name. + + ListMachines() returns an array with all currently registered machines. The + structures in the array consist of the following fields: machine name, machine class, an identifier for + the service that registered the machine and the machine object path. + + ListImages() returns an array with all currently known images. The + structures in the array consist of the following fields: image name, type, read-only flag, creation + time, modification time, current disk space, image object path. + + CreateMachine() may be used to register a new virtual machine or container + with systemd-machined, creating a scope unit for it. This takes as arguments: a + machine name chosen by the registrar, an optional UUID as 32 byte array, a string that identifies the + service that registers the machine, a class string, the PID of the leader process of the machine, an + optional root directory of the container, and an array of additional properties to use for the scope + registration. The virtual machine name must be suitable as hostname, and hence should follow the usual + DNS hostname rules, as well as Linux hostname restrictions. Specifically: only 7 Bit ASCII is + permitted, a maximum length of 64 characters is enforced, only characters from the set + a-zA-Z0-9-_. are allowed, the name may not begin with a dot, and it may not contain + two dots immediately following each other. Container and VM managers should ideally use the hostname + used internally in the machine for this parameter. This recommendation is made in order to make the + machine name naturally resolvable using + nss-mymachines8. If + a container manager needs to embed characters outside of the indicated range, escaping is required, + possibly using _ as the escape character. Another (somewhat natural) option would be + to utilize Internet IDNA encoding. The UUID is passed as 32 byte array, or if no suitable UUID is + available an empty array (zero length) or zeroed out array shall be passed. The UUID should identify + the virtual machine/container uniquely, and should ideally be the same one as + /etc/machine-id in the VM/container is initialized from. The service string can be + free-form, but it is recommended to pass a short lowercase identifier like + systemd-nspawn, libvirt-lxc or similar. The class string should + be either container or vm indicating whether the machine to + register is of the respective class. The leader PID should be the host PID of the init process of the + container, or the encapsulating process of the VM. If the root directory of the container is known and + available in the host's hierarchy, it should be passed, otherwise use the empty string. Finally, the + scope properties are passed as array in the same way as to PID1's + StartTransientUnit(). This method call will internally register a transient scope + unit for the calling client (utilizing the passed scope_properties), and move the leader PID into + it. The call returns an object path for the registered machine object, implementing the + org.freedesktop.machine1.Machine interface (see below). Also see the + New Control Group + Interfaces for details about scope units, and how to alter resource control settings on the + created machine at runtime. + + RegisterMachine() is similar to CreateMachine(), + however only registers a machine, but does not create a scope unit for it. The caller's unit will be + registered instead. This call is only recommended to be used for container or VM managers that are run + multiple times, one instance for each container/VM they manage, and are invoked as system + services. + + CreateMachineWithNetwork() and + RegisterMachineWithNetwork() are similar to CreateMachine() + and RegisterMachine() but take an extra argument: an array of network interface + indexes that point towards the virtual machine or container. The interface indexes should reference one + or more network interfaces on the host that can be used to communicate with the guest. Commonly the + passed interface index refers to the host side of a "veth" link (in case of containers), or a + "tun"/"tap" link (in case of VMs) or the host side of a bridge interface that bridges access to the + VM/container interfaces. Specifying this information is useful to enable support for link-local IPv6 + communication to the machines, since the scope field of sockaddr_in6 can be initialized by the + specified ifindex. + nss-mymachines8 + makes use of this information. + + KillMachine() sends a UNIX signal to the machine's processes. It takes a + machine name (as originally passed to CreateMachine() or returned by + ListMachines()). An identifier what precisely to send the signal to being either + leader or all, plus a numeric UNIX signal integer. + + TerminateMachine() terminates a virtual machine, killing its processes. It + takes a machine name as argument. + + GetMachineAddresses() retrieves the IP addresses of a container. This call + returns an array of pairs consisting of an address family specifier (AF_INET or + AF_INET6) and a byte array containing the addresses. This is only supported for + containers that make use of network namespacing. + + GetMachineOSRelease() retrieves the OS release information of a + container. This call returns an array of key value pairs read from the + os-release5 file in + the container, and is useful to identify the operating system used in a container. + + OpenMachinePTY() allocates a pseudo TTY in the container and returns a file + descriptor and its path. This is equivalent to transitioning into the container and invoking + posix_openpt3. + + OpenMachineLogin() allocates a pseudo TTY in the container and ensures that + a getty loging prompt of the container is running on the other end. It returns the file descriptor of + the PTY plus the PTY path. This is useful for acquiring a pty with a login prompt from the + container. + + OpenMachineShell() allocates a pseudo TTY in the container, as the specified + user, and invokes an executable of the specified path, with a list of arguments (starting from + argv[0]), and an environment block. It then returns the file descriptor of the PTY plus the PTY + path. + + BindMountMachine() bind mounts a file or directory from the host into the + container. Takes a machine name, the source directory on the host, and the destination directory in the + container as argument. Also takes two booleans, one indicating whether the bind mount shall be + read-only, the other indicating whether the destination mount point shall be created first, if it is + missing. + + CopyFromMachine() copies files or directories from a container into the + host. Takes a container name, a source directory in the container and a destination directory on the + host as argument. CopyToMachine() does the opposite and copies files from a source + directory on the host into a destination directory in the container. + + RemoveImage() removes the image by the specified name. + + RenameImage() renames the specified image to a new name. + + CloneImage() clones the specified image under a new name. Also takes a + boolean argument indicating whether the resuling image shall be read-only or not. + + MarkImageReadOnly() toggles the read-only flag of an image. + + SetPoolLimit() sets an overall quota limit on the pool of images. + + SetImageLimit() sets a per-image quota limit. + + MapFromMachineUser(), MapToMachineUser(), + MapFromMachineGroup(), MapToMachineGroup() may be used to map + UIDs/GIDs from the host user namespace to a container namespace or back. + + + + Signals + + MachineNew and MachineRemoved are sent whenever a new + machine is registered or removed. These signals carry the machine name plus the object path to the + org.freedesktop.machine1.Machine interface (see below). + + + + Properties + + PoolPath specifies the file system path where images are written to. + + PoolUsage specifies the current usage size of the image pool in bytes. + + PoolLimit specifies the size limit of the image pool in bytes. + + + + + Machine Objects + + +$ gdbus introspect --system \ + --dest org.freedesktop.machine1 \ + --object-path /org/freedesktop/machine1/machine/rawhide + +node /org/freedesktop/machine1/machine/fedora_2dtree { + interface org.freedesktop.machine1.Machine { + methods: + Terminate(); + Kill(in s who, + in s signal); + GetAddresses(out a(iay) addresses); + GetOSRelease(out a{ss} fields); + signals: + properties: + readonly s Name = 'fedora-tree'; + readonly ay Id = [0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]; + readonly t Timestamp = 1374193370484284; + readonly t TimestampMonotonic = 128247251308; + readonly s Service = 'nspawn'; + readonly s Unit = 'machine-fedora\\x2dtree.scope'; + readonly u Leader = 30046; + readonly s Class = 'container'; + readonly s RootDirectory = '/home/lennart/fedora-tree'; + readonly ai NetworkInterfaces = [7]; + readonly s State = 'running'; + }; + interface org.freedesktop.DBus.Properties { + }; + interface org.freedesktop.DBus.Peer { + }; + interface org.freedesktop.DBus.Introspectable { + }; +}; + + + + Methods + + Terminate() and Kill() terminate/kill the machine, and + take the same arguments as TerminateMachine() and + KillMachine() on the Manager interface. + + GetAddresses() and GetOSRelease() get IP address and OS + release information from the machine, and take the same arguments as + GetMachineAddresses() and GetMachineOSRelease() of the + Manager interface, described above. + + + + Properties + + Name is the machine name, as it was passed in during registration with + CreateMachine() on the manager object. + + Id is the machine UUID. + + Timestamp and TimestampMonotonic are the realtime and + monotonic timestamps when the virtual machines where created. + + Service contains a short string identifying the registering service, as passed + in during registration of the machine. + + Unit is the systemd scope or service unit name for the machine. + + Leader is the PID of the leader process of the machine. + + Class is the class of the machine and either the string "vm" (for real VMs + based on virtualized hardware) or "container" (for light-weight userspace virtualization sharing the + same kernel as the host). + + RootDirectory is the root directory of the container if that is known and + applicable, or the empty string. + + NetworkInterfaces contains an array of network interface indexes that point + towards the container or VM or the host. For details about this information see the description of + CreateMachineWithNetwork() above. + + State is the state of the machine, and one of opening, + running, closing. Note that the state machine is not considered + part of the API and states might be removed or added without this being considered API breakage. + + + + + + Versioning + + These D-Bus interfaces follow + the usual interface versioning guidelines. + + diff --git a/man/rules/meson.build b/man/rules/meson.build index 4e57b94bbf..c6baedcf6c 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -45,6 +45,7 @@ manpages = [ ['nss-resolve', '8', ['libnss_resolve.so.2'], 'ENABLE_NSS_RESOLVE'], ['nss-systemd', '8', ['libnss_systemd.so.2'], 'ENABLE_NSS_SYSTEMD'], ['org.freedesktop.login1', '5', [], 'ENABLE_LOGIND'], + ['org.freedesktop.machine1', '5', [], 'ENABLE_MACHINED'], ['os-release', '5', [], ''], ['pam_systemd', '8', [], 'HAVE_PAM'], ['pam_systemd_home', '8', [], 'ENABLE_PAM_HOME'], diff --git a/man/systemd-machined.service.xml b/man/systemd-machined.service.xml index 8771434e5a..b5fad154e7 100644 --- a/man/systemd-machined.service.xml +++ b/man/systemd-machined.service.xml @@ -29,24 +29,91 @@ Description - systemd-machined is a system service that - keeps track of virtual machines and containers, and processes - belonging to them. + systemd-machined is a system service that keeps track of locally running virtual + machines and containers. + + systemd-machined is useful for registering and keeping track of both OS + containers (containers that share the host kernel but run a full init system of their own and behave in + most regards like a full virtual operating system rather than just one virtualized app) and full virtual + machines (virtualized hardware running normal operating systems and possibly different kernels). + + systemd-machined should not be used for registering/keeping + track of application sandbox containers. A machine in the context of + systemd-machined is supposed to be an abstract term covering both OS containers and + full virtual machines, but not application sandboxes. + + Machines registered with machined are exposed in various ways in the system. For example: + + Tools like + ps1 + will show to which machine a specific process belongs in a column of + its own, and so will + gnome-system-monitor or + systemd-cgls1. + + + systemd's various tools + (systemctl1, + journalctl1, + loginctl1, + hostnamectl1, + timedatectl1, + localectl1, + machinectl1, ...) + support the switch to operate on local containers instead of the host system. + + + systemctl list-machines will show the system state of all local + containers, connecting to the container's init system for that. + + systemctl's switch has the effect of not only showing the + locally running services, but recursively the services of all registered containers. + + The machinectl command provides access to a number of useful + operations on registered containers, such as introspecting them, rebooting, shutting them down, and + getting a login prompt on them. + + The + sd-bus3 library + exposes the + sd_bus_open_system_container3 + call to connect to the system bus of any registered container. + + The + nss-mymachines8 + module makes sure all registered containers can be resolved via normal glibc + gethostbyname3 + or + getaddrinfo3 + calls. + See systemd-nspawn1 for some examples on how to run containers with OS tools. - Use - nss-mymachines8 - to make the names of local containers known to - systemd-machined locally resolvable as host - names. + If you are interested in writing a VM or container manager that makes use of machined, please have + look at Writing + Virtual Machine or Container Managers. Also see the New Control Group + Interfaces. - See the - - machined D-Bus API Documentation for information about the - APIs systemd-machined provides. + The daemon provides both a C library interface + (which is shared with systemd-logind.service8) + as well as a D-Bus interface. + The library interface may be used to introspect and watch the state of virtual machines/containers. + The bus interface provides the same but in addition may also be used to register or terminate + machines. + For more information please consult + sd-login3 + and + org.freedesktop.machine13. + + + A small companion daemon + systemd-importd.service8 + is also available, which implements importing, exporting, and downloading of container and VM images. + From bbe17ca1cb6ce6aba48dd79e5ab66579b7108828 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Tue, 7 Apr 2020 15:42:08 +0200 Subject: [PATCH 04/26] machined: add dbus parameter names --- src/machine/machine-dbus.c | 98 ++++++++-- src/machine/machined-dbus.c | 346 ++++++++++++++++++++++++++++++++---- 2 files changed, 393 insertions(+), 51 deletions(-) diff --git a/src/machine/machine-dbus.c b/src/machine/machine-dbus.c index 5c0f714184..c75467cadf 100644 --- a/src/machine/machine-dbus.c +++ b/src/machine/machine-dbus.c @@ -1334,18 +1334,92 @@ const sd_bus_vtable machine_vtable[] = { SD_BUS_PROPERTY("RootDirectory", "s", NULL, offsetof(Machine, root_directory), SD_BUS_VTABLE_PROPERTY_CONST), SD_BUS_PROPERTY("NetworkInterfaces", "ai", property_get_netif, 0, SD_BUS_VTABLE_PROPERTY_CONST), SD_BUS_PROPERTY("State", "s", property_get_state, 0, 0), - SD_BUS_METHOD("Terminate", NULL, NULL, bus_machine_method_terminate, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("Kill", "si", NULL, bus_machine_method_kill, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetAddresses", NULL, "a(iay)", bus_machine_method_get_addresses, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetOSRelease", NULL, "a{ss}", bus_machine_method_get_os_release, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetUIDShift", NULL, "u", bus_machine_method_get_uid_shift, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("OpenPTY", NULL, "hs", bus_machine_method_open_pty, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("OpenLogin", NULL, "hs", bus_machine_method_open_login, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("OpenShell", "ssasas", "hs", bus_machine_method_open_shell, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("BindMount", "ssbb", NULL, bus_machine_method_bind_mount, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("CopyFrom", "ss", NULL, bus_machine_method_copy, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("CopyTo", "ss", NULL, bus_machine_method_copy, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("OpenRootDirectory", NULL, "h", bus_machine_method_open_root_directory, SD_BUS_VTABLE_UNPRIVILEGED), + + SD_BUS_METHOD("Terminate", + NULL, + NULL, + bus_machine_method_terminate, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("Kill", + "si", + SD_BUS_PARAM(who) + SD_BUS_PARAM(signal), + NULL,, + bus_machine_method_kill, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetAddresses", + NULL,, + "a(iay)", + SD_BUS_PARAM(addresses), + bus_machine_method_get_addresses, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetOSRelease", + NULL,, + "a{ss}", + SD_BUS_PARAM(fields), + bus_machine_method_get_os_release, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetUIDShift", + NULL,, + "u", + SD_BUS_PARAM(shift), + bus_machine_method_get_uid_shift, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("OpenPTY", + NULL,, + "hs", + SD_BUS_PARAM(pty) + SD_BUS_PARAM(pty_path), + bus_machine_method_open_pty, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("OpenLogin", + NULL,, + "hs", + SD_BUS_PARAM(pty) + SD_BUS_PARAM(pty_path), + bus_machine_method_open_login, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("OpenShell", + "ssasas", + SD_BUS_PARAM(user) + SD_BUS_PARAM(path) + SD_BUS_PARAM(args) + SD_BUS_PARAM(environment), + "hs", + SD_BUS_PARAM(pty) + SD_BUS_PARAM(pty_path), + bus_machine_method_open_shell, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("BindMount", + "ssbb", + SD_BUS_PARAM(source) + SD_BUS_PARAM(destination) + SD_BUS_PARAM(read_only) + SD_BUS_PARAM(mkdir), + NULL,, + bus_machine_method_bind_mount, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("CopyFrom", + "ss", + SD_BUS_PARAM(source) + SD_BUS_PARAM(destination), + NULL,, + bus_machine_method_copy, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("CopyTo", + "ss", + SD_BUS_PARAM(source) + SD_BUS_PARAM(destination), + NULL,, + bus_machine_method_copy, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("OpenRootDirectory", + NULL,, + "h", + SD_BUS_PARAM(fd), + bus_machine_method_open_root_directory, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_VTABLE_END }; diff --git a/src/machine/machined-dbus.c b/src/machine/machined-dbus.c index 97dfb94278..76d5119089 100644 --- a/src/machine/machined-dbus.c +++ b/src/machine/machined-dbus.c @@ -1127,48 +1127,316 @@ static int method_map_to_machine_group(sd_bus_message *message, void *groupdata, const sd_bus_vtable manager_vtable[] = { SD_BUS_VTABLE_START(0), + SD_BUS_PROPERTY("PoolPath", "s", property_get_pool_path, 0, 0), SD_BUS_PROPERTY("PoolUsage", "t", property_get_pool_usage, 0, 0), SD_BUS_PROPERTY("PoolLimit", "t", property_get_pool_limit, 0, 0), - SD_BUS_METHOD("GetMachine", "s", "o", method_get_machine, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetImage", "s", "o", method_get_image, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetMachineByPID", "u", "o", method_get_machine_by_pid, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ListMachines", NULL, "a(ssso)", method_list_machines, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ListImages", NULL, "a(ssbttto)", method_list_images, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("CreateMachine", "sayssusa(sv)", "o", method_create_machine, 0), - SD_BUS_METHOD("CreateMachineWithNetwork", "sayssusaia(sv)", "o", method_create_machine_with_network, 0), - SD_BUS_METHOD("RegisterMachine", "sayssus", "o", method_register_machine, 0), - SD_BUS_METHOD("RegisterMachineWithNetwork", "sayssusai", "o", method_register_machine_with_network, 0), - SD_BUS_METHOD("UnregisterMachine", "s", NULL, method_unregister_machine, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("TerminateMachine", "s", NULL, method_terminate_machine, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("KillMachine", "ssi", NULL, method_kill_machine, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetMachineAddresses", "s", "a(iay)", method_get_machine_addresses, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetMachineOSRelease", "s", "a{ss}", method_get_machine_os_release, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("OpenMachinePTY", "s", "hs", method_open_machine_pty, 0), - SD_BUS_METHOD("OpenMachineLogin", "s", "hs", method_open_machine_login, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("OpenMachineShell", "sssasas", "hs", method_open_machine_shell, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("BindMountMachine", "sssbb", NULL, method_bind_mount_machine, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("CopyFromMachine", "sss", NULL, method_copy_machine, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("CopyToMachine", "sss", NULL, method_copy_machine, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("OpenMachineRootDirectory", "s", "h", method_open_machine_root_directory, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetMachineUIDShift", "s", "u", method_get_machine_uid_shift, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("RemoveImage", "s", NULL, method_remove_image, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("RenameImage", "ss", NULL, method_rename_image, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("CloneImage", "ssb", NULL, method_clone_image, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("MarkImageReadOnly", "sb", NULL, method_mark_image_read_only, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetImageHostname", "s", "s", method_get_image_hostname, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetImageMachineID", "s", "ay", method_get_image_machine_id, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetImageMachineInfo", "s", "a{ss}", method_get_image_machine_info, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetImageOSRelease", "s", "a{ss}", method_get_image_os_release, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetPoolLimit", "t", NULL, method_set_pool_limit, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetImageLimit", "st", NULL, method_set_image_limit, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("CleanPool", "s", "a(st)", method_clean_pool, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("MapFromMachineUser", "su", "u", method_map_from_machine_user, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("MapToMachineUser", "u", "sou", method_map_to_machine_user, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("MapFromMachineGroup", "su", "u", method_map_from_machine_group, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("MapToMachineGroup", "u", "sou", method_map_to_machine_group, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_SIGNAL("MachineNew", "so", 0), - SD_BUS_SIGNAL("MachineRemoved", "so", 0), + + SD_BUS_METHOD_WITH_NAMES("GetMachine", + "s", + SD_BUS_PARAM(name), + "o", + SD_BUS_PARAM(machine), + method_get_machine, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetImage", + "s", + SD_BUS_PARAM(name), + "o", + SD_BUS_PARAM(image), + method_get_image, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetMachineByPID", + "u", + SD_BUS_PARAM(pid), + "o", + SD_BUS_PARAM(machine), + method_get_machine_by_pid, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("ListMachines", + NULL,, + "a(ssso)", + SD_BUS_PARAM(machines), + method_list_machines, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("ListImages", + NULL,, + "a(ssbttto)", + SD_BUS_PARAM(images), + method_list_images, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("CreateMachine", + "sayssusa(sv)", + SD_BUS_PARAM(name) + SD_BUS_PARAM(id) + SD_BUS_PARAM(service) + SD_BUS_PARAM(class) + SD_BUS_PARAM(leader) + SD_BUS_PARAM(root_directory) + SD_BUS_PARAM(scope_properties), + "o", + SD_BUS_PARAM(path), + method_create_machine, 0), + SD_BUS_METHOD_WITH_NAMES("CreateMachineWithNetwork", + "sayssusaia(sv)", + SD_BUS_PARAM(name) + SD_BUS_PARAM(id) + SD_BUS_PARAM(service) + SD_BUS_PARAM(class) + SD_BUS_PARAM(leader) + SD_BUS_PARAM(root_directory) + SD_BUS_PARAM(ifindices) + SD_BUS_PARAM(scope_properties), + "o", + SD_BUS_PARAM(path), + method_create_machine_with_network, 0), + SD_BUS_METHOD_WITH_NAMES("RegisterMachine", + "sayssus", + SD_BUS_PARAM(name) + SD_BUS_PARAM(id) + SD_BUS_PARAM(service) + SD_BUS_PARAM(class) + SD_BUS_PARAM(leader) + SD_BUS_PARAM(root_directory), + "o", + SD_BUS_PARAM(path), + method_register_machine, 0), + SD_BUS_METHOD_WITH_NAMES("RegisterMachineWithNetwork", + "sayssusai", + SD_BUS_PARAM(name) + SD_BUS_PARAM(id) + SD_BUS_PARAM(service) + SD_BUS_PARAM(class) + SD_BUS_PARAM(leader) + SD_BUS_PARAM(root_directory) + SD_BUS_PARAM(ifindices), + "o", + SD_BUS_PARAM(path), + method_register_machine_with_network, 0), + SD_BUS_METHOD_WITH_NAMES("UnregisterMachine", + "s", + SD_BUS_PARAM(name), + NULL,, + method_unregister_machine, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("TerminateMachine", + "s", + SD_BUS_PARAM(id), + NULL,, + method_terminate_machine, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("KillMachine", + "ssi", + SD_BUS_PARAM(name) + SD_BUS_PARAM(who) + SD_BUS_PARAM(signal), + NULL,, + method_kill_machine, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetMachineAddresses", + "s", + SD_BUS_PARAM(name), + "a(iay)", + SD_BUS_PARAM(addresses), + method_get_machine_addresses, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetMachineOSRelease", + "s", + SD_BUS_PARAM(name), + "a{ss}", + SD_BUS_PARAM(fields), + method_get_machine_os_release, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("OpenMachinePTY", + "s", + SD_BUS_PARAM(name), + "hs", + SD_BUS_PARAM(pty) + SD_BUS_PARAM(pty_path), + method_open_machine_pty, + 0), + SD_BUS_METHOD_WITH_NAMES("OpenMachineLogin", + "s", + SD_BUS_PARAM(name), + "hs", + SD_BUS_PARAM(pty) + SD_BUS_PARAM(pty_path), + method_open_machine_login, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("OpenMachineShell", + "sssasas", + SD_BUS_PARAM(name) + SD_BUS_PARAM(user) + SD_BUS_PARAM(path) + SD_BUS_PARAM(args) + SD_BUS_PARAM(environment), + "hs", + SD_BUS_PARAM(pty) + SD_BUS_PARAM(pty_path), + method_open_machine_shell, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("BindMountMachine", + "sssbb", + SD_BUS_PARAM(name) + SD_BUS_PARAM(source) + SD_BUS_PARAM(destination) + SD_BUS_PARAM(read_only) + SD_BUS_PARAM(mkdir), + NULL,, + method_bind_mount_machine, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("CopyFromMachine", + "sss", + SD_BUS_PARAM(name) + SD_BUS_PARAM(source) + SD_BUS_PARAM(destination), + NULL,, + method_copy_machine, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("CopyToMachine", + "sss", + SD_BUS_PARAM(name) + SD_BUS_PARAM(source) + SD_BUS_PARAM(destination), + NULL,, + method_copy_machine, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("OpenMachineRootDirectory", + "s", + SD_BUS_PARAM(name), + "h", + SD_BUS_PARAM(fd), + method_open_machine_root_directory, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetMachineUIDShift", + "s", + SD_BUS_PARAM(name), + "u", + SD_BUS_PARAM(shift), + method_get_machine_uid_shift, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("RemoveImage", + "s", + SD_BUS_PARAM(name), + NULL,, + method_remove_image, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("RenameImage", + "ss", + SD_BUS_PARAM(name) + SD_BUS_PARAM(new_name), + NULL,, + method_rename_image, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("CloneImage", + "ssb", + SD_BUS_PARAM(name) + SD_BUS_PARAM(new_name) + SD_BUS_PARAM(read_only), + NULL,, + method_clone_image, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("MarkImageReadOnly", + "sb", + SD_BUS_PARAM(name) + SD_BUS_PARAM(read_only), + NULL,, + method_mark_image_read_only, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetImageHostname", + "s", + SD_BUS_PARAM(name), + "s", + SD_BUS_PARAM(hostname), + method_get_image_hostname, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetImageMachineID", + "s", + SD_BUS_PARAM(name), + "ay", + SD_BUS_PARAM(id), + method_get_image_machine_id, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetImageMachineInfo", + "s", + SD_BUS_PARAM(name), + "a{ss}", + SD_BUS_PARAM(machine_info), + method_get_image_machine_info, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetImageOSRelease", + "s", + SD_BUS_PARAM(name), + "a{ss}", + SD_BUS_PARAM(os_release), + method_get_image_os_release, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetPoolLimit", + "t", + SD_BUS_PARAM(size), + NULL,, + method_set_pool_limit, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetImageLimit", + "st", + SD_BUS_PARAM(name) + SD_BUS_PARAM(size), + NULL,, + method_set_image_limit, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("CleanPool", + "s", + SD_BUS_PARAM(mode), + "a(st)", + SD_BUS_PARAM(images), + method_clean_pool, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("MapFromMachineUser", + "su", + SD_BUS_PARAM(name) + SD_BUS_PARAM(uid_inner), + "u", + SD_BUS_PARAM(uid_outer), + method_map_from_machine_user, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("MapToMachineUser", + "u", + SD_BUS_PARAM(uid_outer), + "sou", + SD_BUS_PARAM(machine_name) + SD_BUS_PARAM(machine_path) + SD_BUS_PARAM(uid_inner), + method_map_to_machine_user, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("MapFromMachineGroup", + "su", + SD_BUS_PARAM(name) + SD_BUS_PARAM(gid_inner), + "u", + SD_BUS_PARAM(gid_outer), + method_map_from_machine_group, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("MapToMachineGroup", + "u", + SD_BUS_PARAM(gid_outer), + "sou", + SD_BUS_PARAM(machine_name) + SD_BUS_PARAM(machine_path) + SD_BUS_PARAM(gid_inner), + method_map_to_machine_group, + SD_BUS_VTABLE_UNPRIVILEGED), + + SD_BUS_SIGNAL_WITH_NAMES("MachineNew", + "so", + SD_BUS_PARAM(machine) + SD_BUS_PARAM(path), + 0), + SD_BUS_SIGNAL_WITH_NAMES("MachineRemoved", + "so", + SD_BUS_PARAM(machine) + SD_BUS_PARAM(path), + 0), + SD_BUS_VTABLE_END }; From 2fe60ff1d07b8110c341c67154e6f2adbb478bd8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Wed, 8 Apr 2020 21:55:37 +0200 Subject: [PATCH 05/26] man: import org.freedesktop.import1(3) from the wiki --- man/org.freedesktop.import1.xml | 269 +++++++++++++++++++++++++++++++ man/org.freedesktop.machine1.xml | 2 +- man/rules/meson.build | 1 + 3 files changed, 271 insertions(+), 1 deletion(-) create mode 100644 man/org.freedesktop.import1.xml diff --git a/man/org.freedesktop.import1.xml b/man/org.freedesktop.import1.xml new file mode 100644 index 0000000000..9c8498ff7f --- /dev/null +++ b/man/org.freedesktop.import1.xml @@ -0,0 +1,269 @@ + + + + + + + org.freedesktop.import1 + systemd + + + + org.freedesktop.import1 + 5 + + + + org.freedesktop.import1 + The D-Bus interface of systemd-importd + + + + Introduction + + + systemd-importd.service8 + is a system service which may be used to import, export and download additional system images, for + running them as local containers using tools such as + systemd-nspawn1 The + service is used as backend for machinectl pull-raw and machinectl + pull-tar and related commands. + This page describes the D-Bus interface. + + Note that + systemd-importd.service8 + is mostly a small companion service for + systemd-machined.service8. + Many operations to manipulate local container and VM images are hence available via the systemd-machined bus API, c.f. + org.freedesktop.machine1.service5. + + + + + The Manager Object + + The service exposes the following interfaces on the Manager object on the bus: + + +$ gdbus introspect --system \ + --dest org.freedesktop.import1 \ + --object-path /org/freedesktop/import1 + +node /org/freedesktop/import1 { + interface org.freedesktop.import1.Manager { + methods: + ImportTar(in h fd, + in s local_name, + in b force, + in b read_only, + out u transfer_id, + out o transfer_path); + ImportRaw(in h fd, + in s local_name, + in b force, + in b read_only, + out u transfer_id, + out o transfer_path); + ExportTar(in s local_name, + in h fd, + in s format, + out u transfer_id, + out o transfer_path); + ExportRaw(in s local_name, + in h fd, + in s format, + out u transfer_id, + out o transfer_path); + PullTar(in s url, + in s local_name, + in s verify_mode, + in b force, + out u transfer_id, + out o transfer_path); + PullRaw(in s url, + in s local_name, + in s verify_mode, + in b force, + out u transfer_id, + out o transfer_path); + ListTransfers(out a(usssdo) list); + CancelTransfer(in u transfer_id); + signals: + TransferNew(u transfer_id, + o transfer_path); + TransferRemoved(u transfer_id, + o transfer_path, + s result); + }; + interface org.freedesktop.DBus.Peer { + }; + interface org.freedesktop.DBus.Introspectable { + }; + interface org.freedesktop.DBus.Properties { + }; +}; + + + + Methods + + ImportTar() and ImportRaw() import a system image and + place it into /var/lib/machines/. The first argument should be a file descriptor + (opened for reading) referring to the tar or raw file to import. It should reference either a file on + disk or a pipe or socket. When ImportTar() is used the file descriptor should + refer to a tar file, optionally compressed with + gzip1, + bzip21, + or + xz1. + systemd-importd will detect the used compression scheme (if any) automatically. When + ImportRaw() is used the file descriptor should refer to a raw or qcow2 disk image + containing an MBR or GPT disk label, also optionally compressed with gzip, bzip2 or xz. In either case, + if the file is specified as file descriptor on disk, progress information is generated for the import + operation (since the size on disk is known then), if a socket or pipe is specified this is not + available. The file descriptor argument is followed by a local name for the image. This should be a + name suitable as a hostname and will be used to name the imported image below + /var/lib/machines. A tar import is placed as directory tree or + btrfs8 + subvolume below /var/lib/machines/, under the name specified with no suffix + appended. A raw import is placed as file in /var/lib/machines/ with the + .raw suffix appended. The argument controls whether any + pre-existing image with the same name shall be removed for the operation. If true, it is removed, if + false the operation fails on a name conflict. Finally, the argument controls + whether to create a writable or read-only image. The two calls return immediately after invocation, + with the import transfer ongoing. They return a pair of transfer identifier and object path, which may + be used to retrieve progress information about the transfer, or cancel it. The transfer identifier is a + simple numeric identifier, the object path references an + org.freedesktop.import1.Transfer object, see below. Listen for a + TransferRemoved signal for the transfer ID it order to detect when a transfer is + complete. The returned transfer object is useful to determine the current progress or log output of the + ongoing import operation. + + ExportTar() and ExportRaw() implement the reverse + operation, and may be used to export a system image in order to place it in a tar or raw image. They + take the machine name to export as first parameter, followed by a file descriptor (opened for writing) + where the tar or raw file will be written. It may either reference a file on disk or a pipe/socket. The + third argument specifies in which compression format to write the image. It takes one of + uncompressed, xz, bzip2 or + gzip, depending on which compression scheme is required. The image written to the + specified file descriptor will be a tar file in case of ExportTar() or a raw disk + image in case of ExportRaw(). Note that currently raw disk images may not be + exported as tar files, and vice versa, however this restriction might be lifted eventually. The call + returns a transfer identifier and object path for canceling or tracking the export operation, similar + to ImportTar() or ImportRaw() described above. + + PullTar() and PullRaw() may be used to download, verify + and import a system image from a web site. They take an URL argument, that should reference a tar or + raw file on the http:// or https:// protocols, possibly + compressed with xz, bzip2 or gzip. The second argument is a local name for the image. It should be + suitable as hostname, similar to the matching argument of the ImportTar() and + ImportRaw() calls above. The third argument indicates the verification mode for + the image. It may be one of no, checksum, + signature. no turns of any kind of verification of the image; + checksum looks for a SHA256SUM file next to the downloaded + image, and verifies any SHA256 hash value in that file again the image; signature + does the same but also tries to authenticate the SHA256SUM file via + gpg8 + first. The last argument indicates whether to replace a possibly pre-existing image with the same local + name (if true), or whether to fail (if false). Like the import + and export calls above these calls return a pair of transfer identifier and object path for the ongoing + download. + + ListTransfers() returns a list of ongoing import, export or download + operations, as created with the six calls described above. It returns an array of structures, which + consist of the numeric transfer identifier, a string indicating the operation (one of + import-tar, import-raw, export-tar, + export-raw, pull-tar or pull-raw), a string + describing the remote file (in case of download operations this is the source URL, in case of + import/export operations this is a short string describing the file descriptor passed in), a string + with the local machine image name, a progress value between 0.0 (for 0%) and 1.0 (for 100%), as well as + the transfer object path. + + CancelTransfer() may be used to cancel an ongoing import, export or download + operation. Simply specify the transfer identifier to cancel. + + + + Signals + + The TransferNew signal is generated each time a new transfer is added with + the import, export or download calls described above. It carries the transfer ID and object path just + created. + + The TransferRemoved signal is sent each time a transfer was completed, + canceled or failed. It also carries the transfer ID and object path, followed by a string indicating + the result of the operation, which is one of done (on success), + canceled or failed. + + + + + The Transfer Object + + +$ gdbus introspect --system \ + --dest org.freedesktop.import1 \ + --object-path /org/freedesktop/import1/transfer/_1 + +node /org/freedesktop/import1/transfer/_1 { + interface org.freedesktop.import1.Transfer { + methods: + Cancel(); + signals: + LogMessage(u priority, + s line); + properties: + readonly u Id = 1; + readonly s Local = 'xenial-server-cloudimg-amd64-root'; + readonly s Remote = 'https://cloud-images.ubuntu.com/xenial/current/xenial-server-cloudimg-amd64-root.tar.gz'; + readonly s Type = 'pull-tar'; + readonly s Verify = 'signature'; + readonly d Progress = 0.253; + }; + interface org.freedesktop.DBus.Peer { + }; + interface org.freedesktop.DBus.Introspectable { + }; + interface org.freedesktop.DBus.Properties { + }; +}; + + + + Methods + + The Cancel() method may be used to cancel the transfer. It takes no + parameters. This call is pretty much equivalent to the CancelTransfer() call on + the Manager interface (see above), but is exposed on the + Transfer object itself instead of taking a transfer ID. + + + + Properties + + The Id property exposes the numeric transfer ID of the transfer object. + + The Local, Remote, Type properties + expose the local container name of this transfer, the remote source (in case of download: the URL, in + case of import/export a string describing the file descriptor passed in), and the type of operation + (see the Manager's ListTransfer() call above for an explanation of the possible + values). + + The Verify property exposes the selected verification setting, and is only + defined for download operations (see above). + + The Progress property exposes the current progress of the transfer, as a value + between 0.0 and 1.0. To show a progress bar on screen it recommend to query this value in regular + intervals, for example every 500 ms or so. + + + + + Versioning + + These D-Bus interfaces follow + the usual interface versioning guidelines. + + diff --git a/man/org.freedesktop.machine1.xml b/man/org.freedesktop.machine1.xml index d089081a45..f26829ee45 100644 --- a/man/org.freedesktop.machine1.xml +++ b/man/org.freedesktop.machine1.xml @@ -156,7 +156,7 @@ node /org/freedesktop/machine1 { interface org.freedesktop.DBus.Introspectable { }; }; - + Methods diff --git a/man/rules/meson.build b/man/rules/meson.build index c6baedcf6c..6beed3f6dd 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -44,6 +44,7 @@ manpages = [ ['nss-mymachines', '8', ['libnss_mymachines.so.2'], 'ENABLE_NSS_MYMACHINES'], ['nss-resolve', '8', ['libnss_resolve.so.2'], 'ENABLE_NSS_RESOLVE'], ['nss-systemd', '8', ['libnss_systemd.so.2'], 'ENABLE_NSS_SYSTEMD'], + ['org.freedesktop.import1', '5', [], 'ENABLE_IMPORTD'], ['org.freedesktop.login1', '5', [], 'ENABLE_LOGIND'], ['org.freedesktop.machine1', '5', [], 'ENABLE_MACHINED'], ['os-release', '5', [], ''], From 956ecd3cd31ac3ab3c6d622b501cf9aa5b528807 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Wed, 8 Apr 2020 21:51:59 +0200 Subject: [PATCH 06/26] importd: add dbus parameter names --- src/import/importd.c | 122 ++++++++++++++++++++++++++++++++++++++----- 1 file changed, 110 insertions(+), 12 deletions(-) diff --git a/src/import/importd.c b/src/import/importd.c index 93e704ed61..c4e8920169 100644 --- a/src/import/importd.c +++ b/src/import/importd.c @@ -1112,30 +1112,128 @@ static BUS_DEFINE_PROPERTY_GET_ENUM(property_get_verify, import_verify, ImportVe static const sd_bus_vtable transfer_vtable[] = { SD_BUS_VTABLE_START(0), + SD_BUS_PROPERTY("Id", "u", NULL, offsetof(Transfer, id), SD_BUS_VTABLE_PROPERTY_CONST), SD_BUS_PROPERTY("Local", "s", NULL, offsetof(Transfer, local), SD_BUS_VTABLE_PROPERTY_CONST), SD_BUS_PROPERTY("Remote", "s", NULL, offsetof(Transfer, remote), SD_BUS_VTABLE_PROPERTY_CONST), SD_BUS_PROPERTY("Type", "s", property_get_type, offsetof(Transfer, type), SD_BUS_VTABLE_PROPERTY_CONST), SD_BUS_PROPERTY("Verify", "s", property_get_verify, offsetof(Transfer, verify), SD_BUS_VTABLE_PROPERTY_CONST), SD_BUS_PROPERTY("Progress", "d", property_get_progress, 0, 0), + SD_BUS_METHOD("Cancel", NULL, NULL, method_cancel, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_SIGNAL("LogMessage", "us", 0), + + SD_BUS_SIGNAL_WITH_NAMES("LogMessage", + "us", + SD_BUS_PARAM(priority) + SD_BUS_PARAM(line), + 0), + SD_BUS_VTABLE_END, }; static const sd_bus_vtable manager_vtable[] = { SD_BUS_VTABLE_START(0), - SD_BUS_METHOD("ImportTar", "hsbb", "uo", method_import_tar_or_raw, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ImportRaw", "hsbb", "uo", method_import_tar_or_raw, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ImportFileSystem", "hsbb", "uo", method_import_fs, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ExportTar", "shs", "uo", method_export_tar_or_raw, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ExportRaw", "shs", "uo", method_export_tar_or_raw, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("PullTar", "sssb", "uo", method_pull_tar_or_raw, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("PullRaw", "sssb", "uo", method_pull_tar_or_raw, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ListTransfers", NULL, "a(usssdo)", method_list_transfers, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("CancelTransfer", "u", NULL, method_cancel_transfer, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_SIGNAL("TransferNew", "uo", 0), - SD_BUS_SIGNAL("TransferRemoved", "uos", 0), + + SD_BUS_METHOD_WITH_NAMES("ImportTar", + "hsbb", + SD_BUS_PARAM(fd) + SD_BUS_PARAM(local_name) + SD_BUS_PARAM(force) + SD_BUS_PARAM(read_only), + "uo", + SD_BUS_PARAM(transfer_id) + SD_BUS_PARAM(transfer_path), + method_import_tar_or_raw, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("ImportRaw", + "hsbb", + SD_BUS_PARAM(fd) + SD_BUS_PARAM(local_name) + SD_BUS_PARAM(force) + SD_BUS_PARAM(read_only), + "uo", + SD_BUS_PARAM(transfer_id) + SD_BUS_PARAM(transfer_path), + method_import_tar_or_raw, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("ImportFileSystem", + "hsbb", + SD_BUS_PARAM(fd) + SD_BUS_PARAM(local_name) + SD_BUS_PARAM(force) + SD_BUS_PARAM(read_only), + "uo", + SD_BUS_PARAM(transfer_id) + SD_BUS_PARAM(transfer_path), + method_import_fs, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("ExportTar", + "shs", + SD_BUS_PARAM(local_name) + SD_BUS_PARAM(fd) + SD_BUS_PARAM(format), + "uo", + SD_BUS_PARAM(transfer_id) + SD_BUS_PARAM(transfer_path), + method_export_tar_or_raw, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("ExportRaw", + "shs", + SD_BUS_PARAM(local_name) + SD_BUS_PARAM(fd) + SD_BUS_PARAM(format), + "uo", + SD_BUS_PARAM(transfer_id) + SD_BUS_PARAM(transfer_path), + method_export_tar_or_raw, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("PullTar", + "sssb", + SD_BUS_PARAM(url) + SD_BUS_PARAM(local_name) + SD_BUS_PARAM(verify_mode) + SD_BUS_PARAM(force), + "uo", + SD_BUS_PARAM(transfer_id) + SD_BUS_PARAM(transfer_path), + method_pull_tar_or_raw, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("PullRaw", + "sssb", + SD_BUS_PARAM(url) + SD_BUS_PARAM(local_name) + SD_BUS_PARAM(verify_mode) + SD_BUS_PARAM(force), + "uo", + SD_BUS_PARAM(transfer_id) + SD_BUS_PARAM(transfer_path), + method_pull_tar_or_raw, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("ListTransfers", + NULL,, + "a(usssdo)", + SD_BUS_PARAM(transfers), + method_list_transfers, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("CancelTransfer", + "u", + SD_BUS_PARAM(transfer_id), + NULL,, + method_cancel_transfer, + SD_BUS_VTABLE_UNPRIVILEGED), + + SD_BUS_SIGNAL_WITH_NAMES("TransferNew", + "uo", + SD_BUS_PARAM(transfer_id) + SD_BUS_PARAM(transfer_path), + 0), + SD_BUS_SIGNAL_WITH_NAMES("TransferRemoved", + "uos", + SD_BUS_PARAM(transfer_id) + SD_BUS_PARAM(transfer_path) + SD_BUS_PARAM(result), + 0), + SD_BUS_VTABLE_END, }; From e09a36bd4617dc6e4dfc447b62affba0d112a0e6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Thu, 9 Apr 2020 15:42:27 +0200 Subject: [PATCH 07/26] man: import org.freedesktop.hostname1(3) from the wiki --- man/custom-entities.ent.in | 1 + man/org.freedesktop.hostname1.xml | 236 ++++++++++++++++++++++++++++++ man/rules/meson.build | 1 + man/systemd-hostnamed.service.xml | 34 +++-- 4 files changed, 263 insertions(+), 9 deletions(-) create mode 100644 man/org.freedesktop.hostname1.xml diff --git a/man/custom-entities.ent.in b/man/custom-entities.ent.in index 84a29f5de4..03fe05f1bc 100644 --- a/man/custom-entities.ent.in +++ b/man/custom-entities.ent.in @@ -6,6 +6,7 @@ + diff --git a/man/org.freedesktop.hostname1.xml b/man/org.freedesktop.hostname1.xml new file mode 100644 index 0000000000..a381cb8239 --- /dev/null +++ b/man/org.freedesktop.hostname1.xml @@ -0,0 +1,236 @@ + + + +%entities; +]> + + + + + org.freedesktop.hostname1 + systemd + + + + org.freedesktop.hostname1 + 5 + + + + org.freedesktop.hostname1 + The D-Bus interface of systemd-hostnamed + + + + Introduction + + + systemd-hostnamed.service8 + is a system service that can be used to control the host name and related machine meta data from user + programs. This page describes the hostname semantics and the D-Bus interface. + + + + The D-Bus API + + The service exposes the following interfaces on the bus: + + +$ gdbus introspect --system \ + --dest org.freedesktop.hostname1 \ + --object-path /org/freedesktop/hostname1 + +node /org/freedesktop/hostname1 { + interface org.freedesktop.hostname1 { + methods: + SetHostname(in s name, + in b user_interaction); + SetStaticHostname(in s name, + in b user_interaction); + SetPrettyHostname(in s name, + in b user_interaction); + SetIconName(in s name, + in b user_interaction); + SetChassis(in s name, + in b user_interaction); + signals: + properties: + readonly s Hostname = 'dhcp-192-168-47-11'; + readonly s StaticHostname = 'lennarts-computer'; + readonly s PrettyHostname = 'Lennart’s Computer'; + readonly s IconName = 'computer-laptop'; + readonly s Chassis = 'laptop'; + }; + interface org.freedesktop.DBus.Properties { + }; + interface org.freedesktop.DBus.Introspectable { + }; + interface org.freedesktop.DBus.Peer { + }; +}; + + + Whenever the hostname or other meta data is changed via the daemon, + PropertyChanged signals are sent out to subscribed clients. Changing a hostname + using this interface is authenticated via PolicyKit. + + + + Semantics + + The static (configured) host name is the one configured in + /etc/hostname. It is chosen by the local user. It is not always in sync with the + current hostname as returned by the + gethostname3 + system call. If no host name is configured this property will be the empty string. Setting this property + to the empty string will remove /etc/hostname. This hostname should be an + internet-style hostname, 7-bit lowercase ASCII, no special chars/spaces. + + The transient (dynamic) host name is the one configured via the kernel's + sethostname3. + It can be different from the static hostname in case DHCP or mDNS have been configured to change the name + based on network information. + This property is never empty. If no hostname is set this will default to + &FALLBACK_HOSTNAME; (configurable at compilation time). Setting this property to the + empty string will reset the dynamic hostname to the static host name. If no static host name is + configured the dynamic host name will be reset to &FALLBACK_HOSTNAME;. This hostname + should be an internet-style hostname, 7-bit lowercase ASCII, no special chars/spaces. + + The pretty host name is a free-form UTF-8 host name for presentation to the + user. User interfaces should ensure that the pretty hostname and the static hostname stay in sync. + I.e. when the former is Lennart’s Computer the latter should be + lennarts-computer. If no pretty host name is set this setting will be the empty + string. Applications should then find a suitable fallback, such as the dynamic hostname. + + The icon name is a name following the XDG icon naming spec. If not set, + information such as the chassis type (see below) is used to find a suitable fallback icon name + (i.e. computer-laptop vs. computer-desktop is picked based on the + chassis information). If no such data is available, returns the empty string. In that case an application + should fall back to a replacement icon, for example computer. If this property is set + to the empty string, this automatic fallback name selection is enabled again. + + The chassis type should be one of the following that are currently defined: + desktop, laptop, server, + tablet, handset, as well as the special chassis types + vm and container for virtualized systems. Note that in most cases + the chassis type will be determined automatically from DMI/SMBIOS/ACPI firmware information. Writing to + this setting is hence useful only to override misdetected chassis types, or configure a chassis type if + none could be auto-detected. Set this property to the empty string to reenable the automatic detection of + the chassis type from firmware information. + + A client which wants to change the local host name for DHCP/mDNS should invoke + SetHostname("newname", false) as soon as the name is available and afterwards reset it via + SetHostname(""). + + Note that systemd-hostnamed starts only on request and terminates after a + short idle period. This effectively means that PropertyChanged messages are not sent + out for changes made directly on the files (as in: administrator edits the files with vi). This is + actually intended behavior: manual configuration changes should require manual reloading of them. + + The transient (dynamic) hostname directly maps to the kernel hostname. This hostname should be + assumed to be highly dynamic, and hence should be watched directly, without involving + PropertyChanged messages from systemd-hostnamed. For that, open + /proc/sys/kernel/hostname and + poll3 + for SIGHUP which is triggered by the kernel every time the hostname changes. Again: + this is special for the transient (dynamic) hostname, and does not apply to the configured (fixed) + hostname. + + Applications may bypass the daemon to read the hostname data if notifications of host name changes + are not necessary. Use + gethostname3, + /etc/hostname (possibly with per-distribution fallbacks), and + machine-info3 + for that. For more information on these files and syscalls see the respective man pages. + + The user_interaction boolean parameters can be used to control whether PolicyKit should + interactively ask the user for authentication credentials if it needs to. + + The PolicyKit action for SetHostname() is + org.freedesktop.hostname1.set-hostname. For + SetStaticHostname() and SetPrettyHostname() it is + org.freedesktop.hostname1.set-static-hostname. For + SetIconName() and SetChassis() it is + org.freedesktop.hostname1.set-machine-info. + + Here are three examples how the pretty hostname and the icon name should be used: + + When registering DNS-SD services: use the pretty host name in the service name, and + pass the icon name in the TXT data, if there is an icon name. Browsing clients can then show the server + icon on each service. Especially useful for WebDAV stuff. Similar for UPnP media + sharing. + + Set the bluetooth name to the pretty host name. + + When your file browser has a "Computer" icon, replace the name with the pretty hostname if set, and the icon with the icon name, if it is set. + + + To properly handle name lookups with changing local hostnames without having to edit + /etc/hosts for them, we recommend using systemd-hostnamed in + combination with nss-myhostname3. + + + Here are some recommendations to follow when generating a static (internet) hostname from a pretty + name: + + Generate a single DNS label only, not an FQDN. That means no dots allowed. Strip them, + or replace them by -. + + It's probably safer not to use any non-ASCII chars, even if DNS allows this in some way + these days. In fact, restrict your charset to a-zA-Z0-9 and -. + Strip other chars, or try to replace them in some smart way with chars from this set, for example + ä → ae, and use - as replacement for all kinds + of punctuation chars or spaces. + + Try to avoid creating repeated -, as well as - as + the first or last char. + + Limit the hostname to 63 chars, which is the length of a DNS label. + + If after stripping special chars the empty string is the result, you can pass this + as-is to systemd-hostnamed in which case it will automatically make + &FALLBACK_HOSTNAME; out of this. + + It probably is a good idea to replace uppercase by lowercase chars. + + + Note that while systemd-hostnamed applies some checks to the hostname you pass + they are much looser than the recommendations above. For example, systemd-hostnamed + will also accept _ in the hostname, but I'd recommend not using this to avoid clashes + with DNS-SD service types. Also systemd-hostnamed allows longer hostnames, but + because of the DNS label limitations, I'd recommend not making use of this. + + Here are a couple of example conversions: + + Lennart's PC → lennarts-pc + Müllers Computer → muellers-computer + Voran! → voran + Es war einmal ein Männlein → es-war-einmal-ein-maennlein + Jawoll. Ist doch wahr! → jawoll-ist-doch-wahr + レナート → localhost + ...zack!!! zack!... → zack-zack + + + Oh, and of course, an already valid internet hostname label you enter and pass through this + conversion should stay unmodified, so that users have direct control of it, if they want -- by simply + ignoring the fact that the pretty hostname is pretty and just edit it as if it was the normal internet + name. + + + + Versioning + + These D-Bus interfaces follow + the usual interface versioning guidelines. + + + + See also + + David Zeuthen's original Fedora + Feature page about xdg-hostname + + diff --git a/man/rules/meson.build b/man/rules/meson.build index 6beed3f6dd..d69286301b 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -44,6 +44,7 @@ manpages = [ ['nss-mymachines', '8', ['libnss_mymachines.so.2'], 'ENABLE_NSS_MYMACHINES'], ['nss-resolve', '8', ['libnss_resolve.so.2'], 'ENABLE_NSS_RESOLVE'], ['nss-systemd', '8', ['libnss_systemd.so.2'], 'ENABLE_NSS_SYSTEMD'], + ['org.freedesktop.hostname1', '5', [], 'ENABLE_HOSTNAMED'], ['org.freedesktop.import1', '5', [], 'ENABLE_IMPORTD'], ['org.freedesktop.login1', '5', [], 'ENABLE_LOGIND'], ['org.freedesktop.machine1', '5', [], 'ENABLE_MACHINED'], diff --git a/man/systemd-hostnamed.service.xml b/man/systemd-hostnamed.service.xml index 19bd4c06f2..185e038809 100644 --- a/man/systemd-hostnamed.service.xml +++ b/man/systemd-hostnamed.service.xml @@ -18,7 +18,7 @@ systemd-hostnamed.service systemd-hostnamed - Host name bus mechanism + Daemon to control system hostname from programs @@ -29,19 +29,35 @@ Description - systemd-hostnamed is a system service - that may be used as a mechanism to change the system's hostname. - systemd-hostnamed is automatically activated - on request and terminates itself when it is unused. + systemd-hostnamed.service is a system service that may be used to change the + system's hostname and related machine meta data from user programs. It is automatically activated on + request and terminates itself when unused. + + It currently offers access to five variables: + + The current host name (Example: dhcp-192-168-47-11) + + + The static (configured) host name (Example: + lennarts-computer) + + The pretty host name (Example: Lennart's Computer) + + + A suitable icon name for the local host (Example: + computer-laptop) + + A chassis type (Example: tablet) + + The tool hostnamectl1 is a command line client to this service. - See the - developer documentation for information about the APIs - systemd-hostnamed provides. + See the + org.freedesktop.hostname11 + for a description of the D-Bus API. From 106d79be06299cb62a947c9c3ca7f5076db9ae66 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Thu, 9 Apr 2020 15:39:58 +0200 Subject: [PATCH 08/26] hostnamed: add dbus parameter names --- src/hostname/hostnamed.c | 66 +++++++++++++++++++++++++++++++++++----- 1 file changed, 58 insertions(+), 8 deletions(-) diff --git a/src/hostname/hostnamed.c b/src/hostname/hostnamed.c index 21f6471495..66af1c0b5c 100644 --- a/src/hostname/hostnamed.c +++ b/src/hostname/hostnamed.c @@ -677,14 +677,64 @@ static const sd_bus_vtable hostname_vtable[] = { SD_BUS_PROPERTY("OperatingSystemPrettyName", "s", NULL, offsetof(Context, data) + sizeof(char*) * PROP_OS_PRETTY_NAME, SD_BUS_VTABLE_PROPERTY_CONST), SD_BUS_PROPERTY("OperatingSystemCPEName", "s", NULL, offsetof(Context, data) + sizeof(char*) * PROP_OS_CPE_NAME, SD_BUS_VTABLE_PROPERTY_CONST), SD_BUS_PROPERTY("HomeURL", "s", NULL, offsetof(Context, data) + sizeof(char*) * PROP_HOME_URL, SD_BUS_VTABLE_PROPERTY_CONST), - SD_BUS_METHOD("SetHostname", "sb", NULL, method_set_hostname, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetStaticHostname", "sb", NULL, method_set_static_hostname, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetPrettyHostname", "sb", NULL, method_set_pretty_hostname, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetIconName", "sb", NULL, method_set_icon_name, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetChassis", "sb", NULL, method_set_chassis, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetDeployment", "sb", NULL, method_set_deployment, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetLocation", "sb", NULL, method_set_location, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetProductUUID", "b", "ay", method_get_product_uuid, SD_BUS_VTABLE_UNPRIVILEGED), + + SD_BUS_METHOD_WITH_NAMES("SetHostname", + "sb", + SD_BUS_PARAM(hostname) + SD_BUS_PARAM(interactive), + NULL,, + method_set_hostname, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetStaticHostname", + "sb", + SD_BUS_PARAM(hostname) + SD_BUS_PARAM(interactive), + NULL,, + method_set_static_hostname, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetPrettyHostname", + "sb", + SD_BUS_PARAM(hostname) + SD_BUS_PARAM(interactive), + NULL,, + method_set_pretty_hostname, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetIconName", + "sb", + SD_BUS_PARAM(icon) + SD_BUS_PARAM(interactive), + NULL,, + method_set_icon_name, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetChassis", + "sb", + SD_BUS_PARAM(chassis) + SD_BUS_PARAM(interactive), + NULL,, + method_set_chassis, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetDeployment", + "sb", + SD_BUS_PARAM(deployment) + SD_BUS_PARAM(interactive), + NULL,, + method_set_deployment, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetLocation", + "sb", + SD_BUS_PARAM(location) + SD_BUS_PARAM(interactive), + NULL,, + method_set_location, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetProductUUID", + "b", + SD_BUS_PARAM(interactive), + "ay", + SD_BUS_PARAM(uuid), + method_get_product_uuid, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_VTABLE_END, }; From 9c970e5f55108456e45b3b2f7617be599ddff516 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Thu, 9 Apr 2020 17:17:16 +0200 Subject: [PATCH 09/26] man: import org.freedesktop.timedate1(3) from the wiki --- man/org.freedesktop.timedate1.xml | 132 ++++++++++++++++++++++++++++++ man/rules/meson.build | 1 + man/systemd-timedated.service.xml | 23 ++++-- 3 files changed, 151 insertions(+), 5 deletions(-) create mode 100644 man/org.freedesktop.timedate1.xml diff --git a/man/org.freedesktop.timedate1.xml b/man/org.freedesktop.timedate1.xml new file mode 100644 index 0000000000..65a5f5b2fb --- /dev/null +++ b/man/org.freedesktop.timedate1.xml @@ -0,0 +1,132 @@ + + + + + + + org.freedesktop.timedate1 + systemd + + + + org.freedesktop.timedate1 + 5 + + + + org.freedesktop.timedate1 + The D-Bus interface of systemd-timedated + + + + Introduction + + + systemd-timedated.service8 + is a system service that can be used to control the system time and related settings. This page + describes the D-Bus interface. + + + + The D-Bus API + + The service exposes the following interfaces on the bus: + + +$ gdbus introspect --system \ + --dest org.freedesktop.timedate1 \ + --object-path /org/freedesktop/timedate1 + +node /org/freedesktop/timedate1 { + interface org.freedesktop.timedate1 { + methods: + SetTime(in x usec_utc, + in b relative, + in b user_interaction); + SetTimezone(in s timezone, + in b user_interaction); + SetLocalRTC(in b local_rtc, + in b fix_system, + in b user_interaction); + SetNTP(in b use_ntp, + in b user_interaction); + signals: + properties: + readonly s Timezone = 'Europe/Berlin'; + readonly b LocalRTC = false; + readonly b NTP = true; + }; + interface org.freedesktop.DBus.Properties { + }; + interface org.freedesktop.DBus.Introspectable { + }; + interface org.freedesktop.DBus.Peer { + }; +}; + + + + Methods + + Use SetTime() to change the system clock. Pass a value of microseconds since + the UNIX epoch (1 Jan 1970 UTC). If relative is true, the passed usec value will be + added to the current system time, if it is false the current system time will be set to the passed usec + value. If the system time is set with this call the RTC will be updated as well. + + Use SetTimezone() to set the system timezone. Pass a value like + Europe/Berlin to set the timezone. Valid timezones are listed in + /usr/share/zoneinfo/zone.tab. If the RTC is configured to be maintained in local + time, it will be updated accordingly. + + Use SetLocalRTC() to control whether the RTC is in local time or UTC. It is + strongly recommended to maintain the RTC in UTC. Some OSes (Windows) however maintain the RTC in local + time, which might make it necessary to enable this feature. However, this creates various problems as + daylight changes might be missed. If fix_system is passed true, + the time from the RTC is read again and the system clock adjusted according to the new setting. If + fix_system is passed false the system time is written to the RTC + taking the new setting into account. Use fix_system=true in installers and livecds + where the RTC is probably more reliable than the system time. Use fix_system=false + in configuration UIs that are run during normal operation and where the system clock is probably more + reliable than the RTC. + + Use SetNTP() to control whether the system clock is synchronized with the + network using systemd-timesyncd. This will enable and start or disable and stop + the chosen time synchronization service. + + Whenever the timezone and local_rtc settings are changed via the daemon + PropertyChanged signals are sent out to which clients can subscribe. Changing the + time settings using this interface is authenticated via PolicyKit. + + Note that this service will not inform you about system time changes. Use + timerfd3 + with CLOCK_REALTIME and TFD_TIMER_CANCEL_ON_SET for that. + + + The user_interaction boolean parameters can be used to control whether + PolicyKit should interactively ask the user for authentication credentials if it needs to. + + The PolicyKit action for SetTimezone() is + org.freedesktop.timedate1.set-timezone. For + SetLocalRTC() it is + org.freedesktop.timedate1.set-local-rtc, for + SetTime() it is org.freedesktop.timedate1.set-time + and for SetNTP() it is + org.freedesktop.timedate1.set-ntp. + + + + + Versioning + + These D-Bus interfaces follow + the usual interface versioning guidelines. + + + + See also + + More information on how the system clock and RTC interact + + diff --git a/man/rules/meson.build b/man/rules/meson.build index d69286301b..34b775d91a 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -48,6 +48,7 @@ manpages = [ ['org.freedesktop.import1', '5', [], 'ENABLE_IMPORTD'], ['org.freedesktop.login1', '5', [], 'ENABLE_LOGIND'], ['org.freedesktop.machine1', '5', [], 'ENABLE_MACHINED'], + ['org.freedesktop.timedate1', '5', [], 'ENABLE_TIMEDATED'], ['os-release', '5', [], ''], ['pam_systemd', '8', [], 'HAVE_PAM'], ['pam_systemd_home', '8', [], 'ENABLE_PAM_HOME'], diff --git a/man/systemd-timedated.service.xml b/man/systemd-timedated.service.xml index f981848cb2..b722b33115 100644 --- a/man/systemd-timedated.service.xml +++ b/man/systemd-timedated.service.xml @@ -29,7 +29,7 @@ Description - systemd-timedated is a system service + systemd-timedated.service is a system service that may be used as a mechanism to change the system clock and timezone, as well as to enable/disable network time synchronization. systemd-timedated is automatically activated @@ -39,10 +39,23 @@ timedatectl1 is a command line client to this service. - See the - developer documentation for information about the APIs - systemd-timedated provides. + systemd-timedated currently offers access to + the following four settings: + + The system time + + The system timezone + + A boolean controlling whether the system RTC is in local or UTC + timezone + + Whether the time synchronization service is enabled/started or + disabled/stopped, see next section. + + + See + org.freedesktop.timedate15 + for information about the D-Bus API. From 599c99ee3b5f3e1d02a47a21d7e0438c4c78a01f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Thu, 9 Apr 2020 17:24:55 +0200 Subject: [PATCH 10/26] timedated: add dbus parameter names --- src/timedate/timedated.c | 44 +++++++++++++++++++++++++++++++++++----- 1 file changed, 39 insertions(+), 5 deletions(-) diff --git a/src/timedate/timedated.c b/src/timedate/timedated.c index 5e2fb50d83..bc49da910e 100644 --- a/src/timedate/timedated.c +++ b/src/timedate/timedated.c @@ -1035,6 +1035,7 @@ static int method_list_timezones(sd_bus_message *m, void *userdata, sd_bus_error static const sd_bus_vtable timedate_vtable[] = { SD_BUS_VTABLE_START(0), + SD_BUS_PROPERTY("Timezone", "s", NULL, offsetof(Context, zone), SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE), SD_BUS_PROPERTY("LocalRTC", "b", bus_property_get_bool, offsetof(Context, local_rtc), SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE), SD_BUS_PROPERTY("CanNTP", "b", property_get_can_ntp, 0, 0), @@ -1042,11 +1043,44 @@ static const sd_bus_vtable timedate_vtable[] = { SD_BUS_PROPERTY("NTPSynchronized", "b", property_get_ntp_sync, 0, 0), SD_BUS_PROPERTY("TimeUSec", "t", property_get_time, 0, 0), SD_BUS_PROPERTY("RTCTimeUSec", "t", property_get_rtc_time, 0, 0), - SD_BUS_METHOD("SetTime", "xbb", NULL, method_set_time, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetTimezone", "sb", NULL, method_set_timezone, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetLocalRTC", "bbb", NULL, method_set_local_rtc, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetNTP", "bb", NULL, method_set_ntp, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ListTimezones", NULL, "as", method_list_timezones, SD_BUS_VTABLE_UNPRIVILEGED), + + SD_BUS_METHOD_WITH_NAMES("SetTime", + "xbb", + SD_BUS_PARAM(usec_utc) + SD_BUS_PARAM(relative) + SD_BUS_PARAM(interactive), + NULL,, + method_set_time, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetTimezone", + "sb", + SD_BUS_PARAM(timezone) + SD_BUS_PARAM(interactive), + NULL,, + method_set_timezone, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetLocalRTC", + "bbb", + SD_BUS_PARAM(local_rtc) + SD_BUS_PARAM(fix_system) + SD_BUS_PARAM(interactive), + NULL,, + method_set_local_rtc, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetNTP", + "bb", + SD_BUS_PARAM(use_ntp) + SD_BUS_PARAM(interactive), + NULL,, + method_set_ntp, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("ListTimezones", + NULL,, + "as", + SD_BUS_PARAM(timezones), + method_list_timezones, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_VTABLE_END, }; From 91c7ac94baf82e73c6b78494ad672e951e5e3de0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Thu, 9 Apr 2020 17:43:52 +0200 Subject: [PATCH 11/26] man: import org.freedesktop.locale1(3) from the wiki --- man/org.freedesktop.locale1.xml | 132 ++++++++++++++++++++++++++++++++ man/rules/meson.build | 1 + man/systemd-localed.service.xml | 9 +-- 3 files changed, 137 insertions(+), 5 deletions(-) create mode 100644 man/org.freedesktop.locale1.xml diff --git a/man/org.freedesktop.locale1.xml b/man/org.freedesktop.locale1.xml new file mode 100644 index 0000000000..7c345acc00 --- /dev/null +++ b/man/org.freedesktop.locale1.xml @@ -0,0 +1,132 @@ + + + + + + + org.freedesktop.locale1 + systemd + + + + org.freedesktop.locale1 + 5 + + + + org.freedesktop.locale1 + The D-Bus interface of systemd-localed + + + + Introduction + + + systemd-localed.service8 + is a system service that can be used to control the system locale and keyboard mapping from user + programs. This page describes the D-Bus interface. + + + + The D-Bus API + + The service exposes the following interfaces on the bus: + + +$ gdbus introspect --system \ + --dest org.freedesktop.locale1 \ + --object-path /org/freedesktop/locale1 + +node /org/freedesktop/locale1 { + interface org.freedesktop.locale1 { + methods: + SetLocale(in as locale, + in b user_interaction); + SetVConsoleKeyboard(in s keymap, + in s keymap_toggle, + in b convert, + in b user_interaction); + SetX11Keyboard(in s layout, + in s model, + in s variant, + in s options, + in b convert, + in b user_interaction); + signals: + properties: + readonly as Locale = ['LANG=en_US.UTF-8']; + readonly s VConsoleKeymap = 'de'; + readonly s VConsoleKeymapToggle = ''; + readonly s X11Layout = 'de'; + readonly s X11Model = ''; + readonly s X11Variant = ''; + readonly s X11Options = ''; + }; + interface org.freedesktop.DBus.Properties { + }; + interface org.freedesktop.DBus.Introspectable { + }; + interface org.freedesktop.DBus.Peer { + }; +}; + + + The system locale consists of an array of environment-variable-assignment-like strings. The + following strings are known: LANG=, LC_CTYPE=, + LC_NUMERIC=, LC_TIME=, LC_COLLATE=, + LC_MONETARY=, LC_MESSAGES=, LC_PAPER=, + LC_NAME=, LC_ADDRESS=, LC_TELEPHONE=, + LC_MEASUREMENT=, LC_IDENTIFICATION=. + + Whenever the system locale or keymap is changed via the daemon PropertyChanged + signals are sent out to which clients can subscribe. + + + Methods + + If you set a new system locale all old system locale settings will be dropped, and the new + settings will be saved to disk. It will also be passed to the system manager, and subsequently started + daemons will inherit the new system locale from it. Note that already running daemons will not learn + about the new system locale. + + The SetVConsoleKeyboard() call may be used to set the key mapping on the + virtual console. Similarly, SetX11Keyboard() may be used to set the default key + mapping of the X11 servers. + + Note that SetVConsoleKeyboard() instantly applies the new keymapping to the + console, while SetX11Keyboard() simply sets a default that may be used by later + sessions. + + The boolean argument convert may be set to optionally convert the console + keyboard configuration to X11 keyboard mappings, resp. vice versa. If true and + SetVConsoleKeyboard() is used the nearest X11 keyboard setting for the chosen + console setting is set. If true and SetX11Keyboard() is used, the nearest console + keyboard setting for the chosen X11 setting is set. Usually it is hence sufficient to call one of the + two functions. + + For graphical UIs that need to set the system keyboard mapping simply invoke + SetX11Keyboard(), set convert=true and ignore + SetVConsoleKeyboard(). + + Use the empty string for the keymap parameters you wish not to set. + + Changing the system locale or keymap using this interface is authenticated via PolicyKit. The + PolicyKit action for SetLocale() is + org.freedesktop.locale1.set-locale. The PolicyKit action for + SetX11Keyboard() and SetVConsoleKeyboard() is + org.freedesktop.locale1.set-keyboard. + + The user_interaction boolean parameters can be used to control whether + PolicyKit should interactively ask the user for authentication credentials if it needs to. + + + + + Versioning + + These D-Bus interfaces follow + the usual interface versioning guidelines. + + diff --git a/man/rules/meson.build b/man/rules/meson.build index 34b775d91a..c881bae6cd 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -46,6 +46,7 @@ manpages = [ ['nss-systemd', '8', ['libnss_systemd.so.2'], 'ENABLE_NSS_SYSTEMD'], ['org.freedesktop.hostname1', '5', [], 'ENABLE_HOSTNAMED'], ['org.freedesktop.import1', '5', [], 'ENABLE_IMPORTD'], + ['org.freedesktop.locale1', '5', [], 'ENABLE_LOCALED'], ['org.freedesktop.login1', '5', [], 'ENABLE_LOGIND'], ['org.freedesktop.machine1', '5', [], 'ENABLE_MACHINED'], ['org.freedesktop.timedate1', '5', [], 'ENABLE_TIMEDATED'], diff --git a/man/systemd-localed.service.xml b/man/systemd-localed.service.xml index f620aade11..cd4359dc46 100644 --- a/man/systemd-localed.service.xml +++ b/man/systemd-localed.service.xml @@ -29,7 +29,7 @@ Description - systemd-localed is a system service + systemd-localed.service is a system service that may be used as mechanism to change the system locale settings, as well as the console key mapping and default X11 key mapping. systemd-localed is automatically @@ -40,10 +40,9 @@ localectl1 is a command line client to this service. - See the - developer documentation for information about the APIs - systemd-localed provides. + See the + org.freedesktop.locale11 + for a description of the D-Bus API. From 5cc34d6d1a37aa6e479e032719409cb9cb9b95fd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Thu, 9 Apr 2020 17:53:03 +0200 Subject: [PATCH 12/26] localed: add dbus parameter names --- src/locale/localed.c | 32 +++++++++++++++++++++++++++++--- 1 file changed, 29 insertions(+), 3 deletions(-) diff --git a/src/locale/localed.c b/src/locale/localed.c index 09f16d25f4..3d626f6bcc 100644 --- a/src/locale/localed.c +++ b/src/locale/localed.c @@ -676,9 +676,35 @@ static const sd_bus_vtable locale_vtable[] = { SD_BUS_PROPERTY("X11Options", "s", property_get_xkb, 0, SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE), SD_BUS_PROPERTY("VConsoleKeymap", "s", property_get_vconsole, 0, SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE), SD_BUS_PROPERTY("VConsoleKeymapToggle", "s", property_get_vconsole, 0, SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE), - SD_BUS_METHOD("SetLocale", "asb", NULL, method_set_locale, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetVConsoleKeyboard", "ssbb", NULL, method_set_vc_keyboard, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetX11Keyboard", "ssssbb", NULL, method_set_x11_keyboard, SD_BUS_VTABLE_UNPRIVILEGED), + + SD_BUS_METHOD_WITH_NAMES("SetLocale", + "asb", + SD_BUS_PARAM(locale) + SD_BUS_PARAM(interactive), + NULL,, + method_set_locale, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetVConsoleKeyboard", + "ssbb", + SD_BUS_PARAM(keymap) + SD_BUS_PARAM(keymap_toggle) + SD_BUS_PARAM(convert) + SD_BUS_PARAM(interactive), + NULL,, + method_set_vc_keyboard, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetX11Keyboard", + "ssssbb", + SD_BUS_PARAM(layout) + SD_BUS_PARAM(model) + SD_BUS_PARAM(variant) + SD_BUS_PARAM(options) + SD_BUS_PARAM(convert) + SD_BUS_PARAM(interactive), + NULL,, + method_set_x11_keyboard, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_VTABLE_END }; From ffd10e5a24bf7ece97b90dcebd64250b380ce16b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Thu, 9 Apr 2020 21:57:16 +0200 Subject: [PATCH 13/26] man: import org.freedesktop.resolve1(3) from the wiki --- man/org.freedesktop.resolve1.xml | 567 +++++++++++++++++++++++++++++++ man/rules/meson.build | 1 + man/systemd-resolved.service.xml | 11 +- 3 files changed, 574 insertions(+), 5 deletions(-) create mode 100644 man/org.freedesktop.resolve1.xml diff --git a/man/org.freedesktop.resolve1.xml b/man/org.freedesktop.resolve1.xml new file mode 100644 index 0000000000..f0cf668f19 --- /dev/null +++ b/man/org.freedesktop.resolve1.xml @@ -0,0 +1,567 @@ + + + +%entities; +]> + + + + + org.freedesktop.resolve1 + systemd + + + + org.freedesktop.resolve1 + 5 + + + + org.freedesktop.resolve1 + The D-Bus interface of systemd-resolved + + + + Introduction + + + systemd-resolved.service8 + is a system service that provides host name resolution and caching using DNS, LLMNR, and mDNS. It also + does DNSSEC validation. This page describes the resolve semantics and the D-Bus interface. + + This page contains an API reference only. If you are looking for a longer explanation how to use + this API, please consult + + Writing Network Configuration Managers + and + Writing Resolver + Clients. + + + + + The Manager Object + + The service exposes the following interfaces on the Manager object on the bus: + + +$ gdbus introspect --system \ + --dest org.freedesktop.resolve1 \ + --object-path /org/freedesktop/resolve1 + +node /org/freedesktop/resolve1 { + interface org.freedesktop.resolve1.Manager { + methods: + ResolveHostname(in i ifindex, + in s name, + in i family, + in t flags, + out a(iiay) addresses, + out s canonical, + out t flags); + ResolveAddress(in i ifindex, + in i family, + in ay address, + in t flags, + out a(is) names, + out t flags); + ResolveRecord(in i ifindex, + in s name, + in q class, + in q type, + in t flags, + out a(iqqay) records, + out t flags); + ResolveService(in i ifindex, + in s name, + in s type, + in s domain, + in i family, + in t flags, + out a(qqqsa(iiay)s) srv_data, + out aay txt_data, + out s canonical_name, + out s canonical_type, + out s canonical_domain, + out t flags); + ResetStatistics(); + GetLink(in i ifindex, + out o path); + SetLinkDNS(in i ifindex, + in a(iay) addresses); + SetLinkDomains(in i ifindex, + in a(sb) domains); + SetLinkLLMNR(in i ifindex, + in s mode); + SetLinkMulticastDNS(in i ifindex, + in s mode); + SetLinkDNSSEC(in i ifindex, + in s mode); + SetLinkDNSSECNegativeTrustAnchors(in i ifindex, + in as names); + RevertLink(in i ifindex); + properties: + readonly s LLMNRHostname = 'delta'; + readonly a(iiay) DNS = [(0, 2, [0xac, 0x1f, 0x00, 0x01])]; + readonly a(isb) Domains = [(0, 'fritz.box', false)]; + readonly (tt) TransactionStatistics = (0, 846); + readonly (ttt) CacheStatistics = (55, 406, 439); + readonly (tttt) DNSSECStatistics = (0, 0, 0, 0); + readonly b DNSSECSupported = false; + }; + interface org.freedesktop.DBus.Peer { + }; + interface org.freedesktop.DBus.Introspectable { + }; + interface org.freedesktop.DBus.Properties { + }; +}; + + + + Methods + + ResolveHostname() takes a hostname and acquires one or more IP addresses for + it. As parameters it takes the Linux network interface index to execute the query on, or 0 if it may be + done on any suitable interface. The name parameter specifies the hostname to + resolve. Note that IDNA conversion is applied to this name when necessary, and when it is resolved via + Unicast DNS, but not for resolution via LLMNR or MulticastDNS. The family parameter + specifies the address family of the IP address to retrieve. It may be AF_INET, + AF_INET6 or AF_UNSPEC, to request addresses of a specific + family. If AF_UNSPEC is specified (recommended), both kinds are retrieved, subject + to local network configuration (i.e. if no local, routable IPv6 address is found, no IPv6 address is + retrieved; and similarly for IPv4). A 64-bit flags field may be used to alter + behaviour of the resolver operation (see below). The method returns an array of address records. Each + address record consists of an interface index the address belongs to, an address family as well as a + byte array with the actual IP address data (which either has 4 or 16 elements, depending on the address + family). The returned address family will be one of AF_INET or + AF_INET6. For IPv6, the returned address interface index should be used to + initialize the .sin6_scope_id field of a struct sockaddr_in6, to permit + support for resolution to link-local IP addresses. The address array is followed by the canonical name + of the host, which may or may not be identical to the name looked up. Finally, a 64-bit + flags field is returned, that is defined similarly to the flags + field that was passed in, but contains information about the resolved data (see below). If the hostname + passed in is an IPv4 or IPv6 address formatted as string, it is parsed, and the result returned. In + this case no network communication is done. + + ResolveAddress() executes the reverse operation: it takes an IP address and + acquires one or more hostnames for it. As parameters it takes the interface index to execute the query + on, or 0 if all suitable interfaces are OK. The family + parameter indicates the address family of the IP address to resolve, it may be either + AF_INET or AF_INET6. The address parameter + takes the raw IP address data (as either 4 or 16 byte array). The flags input + parameter may be used to alter the resolver operation (see below). The call returns an array of name + records, consisting of an interface index plus the name each. The flags output + field contains additional information about the resolver operation (see below). + + ResolveRecord() takes a DNS resource record (RR) type, class and name, and + retrieves the full resource record set (RRset), including the RDATA, for it. As parameter it takes the + Linux network interface index to execute the query on, or 0 if it may be done on + any suitable interface. The name parameter specifies the RR domain name to look up + (no IDNA conversion is applied), followed by the 16-bit class and type fields (which may be + ANY). Finally, a flags field may be passed in to alter behaviour of the look-up (see + below). On return an array of RR items is returned. Each array entry consists of the network interface + index the RR was discovered on, the type and class field of the RR found, and a byte array of the raw + RR discovered. The raw RR data starts with the RR's domain name, in the original casing, followed + by the RR type, class, TTL and RDATA, in the binary format documented in + RFC 1035. For RRs that support name + compression in the payload (such as MX or PTR), the compression is expanded in the returned + data. + + Note that the class field has to be specified as IN or ANY currently, and specifying a different + class will return an error indicating that look-ups of this kind are unsupported. Similarly, some + special types are not supported either (AXFR, OPT, …). While systmed-resolved parses and validates resource + record of many types, it is crucial that clients using this API understand that the RR data originates + from the network and should be thoroughly validated before use. + + ResolveService() may be used to resolve a DNS SRV service record, as the + hostnames referenced in it, and possibly an accompanying DNS-SD TXT record containing additional + service metadata. The primary benefit of using this call over ResolveRecord() + specifying the SRV type is that it will resolve the SRV and TXT RRs as well as the hostnames referenced + in the SRV in a single operation. As parameters it takes a Linux network interface index, a service + name, a service type and a service domain. The call may be invoked in three different modes: + + + To resolve a DNS-SD service, specify the service name (e.g. Lennart's + Files), the service type (e.g. _webdav._tcp) and the domain to search in + (e.g. local) in the three service parameters. The service name must be in UTF-8 + format, and no IDNA conversion is applied to it in this mode (as mandated by the DNS-SD + specifications). However, if necessary IDNA conversion is applied to the domain parameter. + + + To resolve a plain SRV record, set the service name parameter to the empty string, + and set the service type and domain properly. (IDNA conversion is applied to the domain, if + necessary.) + + Alternatively, leave both the service name and type empty, and specify the full + domain name of the SRV record (i.e. prefixed with the service type) in the domain parameter. (No IDNA + coversion is applied in this mode.) + + + The family parameter of the ResolveService() call encodes + the desired family of the addresses to resolve (use AF_INET, + AF_INET6, AF_UNSPEC), if this is enabled (Use the + NO_ADDRESS flag to turn address resolution off, see below). The + flags parameter takes a couple of flags that may be used to alter the resolver + operation. + + On return, ResolveService() returns an array of SRV record structures. Each + item consists of the priority, weight and port fields and the hostname to contact, as encoded in the SRV + record. Immediately following is an array with the addresses of this hostname, with each item consisting + of the interface index, the address family and the address data in a byte array. This address array is + followed with the canonicalized hostname. After this array of SRV record structures an array of byte + arrays follows, that encodes the TXT RR strings, in case DNS-SD look-ups are enabled. The next parameters + are the canonical service name, type and domain. This may or may not be identical to the parameters + passed in. Finally, a flags field is returned that contains information about the + resolver operation performed. + + The ResetStatistics() method resets to zero the various statistics counters + systmed-resolved maintains. (For details, see the statistics properties below.) + + The GetLink() method takes a network interface index and returns the object + path to the org.freedesktop.resolve1.Link object corresponding to it. + + + The SetLinkDNS() method sets the DNS servers to use on a specific + interface. This call (and the following ones) may be used by network management software to configure + per-interface DNS settings. It takes a network interface index as well as an array of DNS server IP + address records. Each array item consists of an address family (either AF_INET or + AF_INET6), followed by a 4-byte or 16-byte array with the raw address data. This + call is a one-call shortcut for retrieving the Link object for a network interface using + GetLink() (see above) and then invoking the SetDNS() call + (see below) on it. + + + Network management software integrating with systmed-resolved is recommended + to invoke this method (and the five below) after the interface appeared in the kernel (and thus after a + network interface index has been assigned), but before the network interfaces is activated (set + IFF_UP on) so that all settings take effect during the full time the network + interface is up. It is safe to alter settings while the interface is up, however. Use the + RevertLink() (described below) to reset all per-interface settings. + + The SetLinkDomains() method sets the search and routing domains to use on a + specific network interface for DNS look-ups. It take a network interface index plus an array of domains, + each with a boolean parameter indicating whether the specified domain shall be used as search domain + (false), or just as routing domain (true). Search domains are used for qualifying single-label names into + FQDN when looking up hostnames, as well as for making routing decisions on which interface to send + queries ending in the domain to. Routing domains are not used for single-label name qualification, and + are only used for routing decisions. Pass the search domains in the order they shall be used. + + The SetLinkLLMNR() method enables or disables LLMNR support on a specific + network interface. It takes a network interface index as well as a string that either may be empty, + yes, no or resolve. If empty, the systemd-wide + default LLMNR setting is used. If yes LLMNR is used for resolution of single-label + names, and the local hostname is registered on all local LANs for LLMNR resolution by peers. If + no LLMNR is turned off fully on this interface. If resolve LLMNR + is only enabled for resolving names, but the local host name is not registered for other peers to + use. + + Similarly, the SetLinkMulticastDNS() method enables or disables MulticastDNS + support on a specific interface. It takes the same parameters as SetLinkLLMNR() + described above. + + The SetLinkDNSSEC() method enables or disables DNSSEC validation on a + specific network interface. It takes a network interface index as well as a string that either may be + empty, yes, no or allow-downgrade. If empty, + the system-wide default DNSSEC setting is used. If yes full DNSSEC validation is + done for all look-ups. If the selected DNS server does not support DNSSEC, look-ups will fail if this + mode is used. If no DNSSEC validation is fully disabled. If + allow-downgrade DNSSEC validation is enabled, but is turned off automatically if the + selected server does not support it (thus opening up behaviour to downgrade attacks). Note that DNSSEC + only applies to traditional DNS, not to LLMNR or MulticastDNS. + + The SetLinkDNSSECNegativeTrustAnchors() method may be used to configure DNSSEC + Negative Trust Anchors (NTAs) for a specific network interface. It takes a network interface index and a + list of domains as parameters. + + The RevertLink() method may be used to revert all per-link settings done with + the six calls described above to the defaults again. + + + The Flags Parameter + + The four calls above accept and return a 64-bit flags value. In most cases passing 0 is sufficient + and recommended. However, the following flags are defined to alter the look-up: + + +#define SD_RESOLVED_DNS (UINT64_C(1) << 0) +#define SD_RESOLVED_LLMNR_IPV4 (UINT64_C(1) << 1) +#define SD_RESOLVED_LLMNR_IPV6 (UINT64_C(1) << 2) +#define SD_RESOLVED_MDNS_IPV4 (UINT64_C(1) << 3) +#define SD_RESOLVED_MDNS_IPV6 (UINT64_C(1) << 4) +#define SD_RESOLVED_NO_CNAME (UINT64_C(1) << 5) +#define SD_RESOLVED_NO_TXT (UINT64_C(1) << 6) +#define SD_RESOLVED_NO_ADDRESS (UINT64_C(1) << 7) +#define SD_RESOLVED_NO_SEARCH (UINT64_C(1) << 8) +#define SD_RESOLVED_AUTHENTICATED (UINT64_C(1) << 9) + + + On input, the first five flags control the protocols to use for the look-up. They refer to + classic unicast DNS, LLMNR via IPv4/UDP and IPv6/UDP respectively, as well as MulticastDNS via + IPv4/UDP and IPv6/UDP. If all of these five bits are off on input (which is strongly recommended) the + look-up will be done via all suitable protocols for the specific look-up. Note that these flags + operate as filter only, but cannot force a look-up to be done via a protocol. Specifically, systmed-resolved + will only route look-ups within the .local TLD to MulticastDNS (plus some reverse look-up address + domains), and single-label names to LLMNR (plus some reverse address lookup domains). It will route + neither of these to Unicast DNS servers. Also, it will do LLMNR and Multicast DNS only on interfaces + suitable for multicasting. + + On output these five flags indicate which protocol was used to execute the operation, and hence + where the data was found. + + The primary use case for these five flags are follow-up look-ups based on DNS data retrieved + earlier. In this case it is often a good idea to limit the follow-up look-up to the protocol that was + used to discover the first DNS data look-up. + + The NO_CNAME flag controls whether CNAME/DNAME resource records shall be followed during the + look-up. This flag is only available at input, none of the functions will return it on output. If a + CNAME/DNAME RR is discovered while resolving a hostname an error is returned instead. By default, + when the flag is off, CNAME/DNAME RRs are followed. + + The NO_TXT and NO_ADDRESS flags influence operation of the + ResolveService() call only. They are only defined for input, not output. If + NO_TXT set, the DNS-SD TXT RR look-up is not done in the same operation. If NO_ADDRESS is specified + the hostnames discovered are not implicitly translated to their addresses. + + The NO_SEARCH flag turns off the search domain logic. It is only defined for input in + ResolveHostname(). When specified, single-label hostnames are not qualified + using defined search domains, if any are configured. Note that ResolveRecord() + will not qualify single-label domain names using search domains in any case. Also note that + multi-label hostnames are never subject to search list expansion. + + The AUTHENTICATED bit is defined only in the output flags of the four functions. If set, the + returned data has been fully authenticated. Specifically, this bit is set for all DNSSEC-protected data + for which a full trust chain may be established to a trusted domain anchor. It is also set for locally + synthesized data, such as localhost or data from + /etc/hosts. Moreover, it is set for all LLMNR or mDNS RRs which originate from the + local host. Applications that require authenticated RR data for operation should check this flag before + trusting the data. Not that systmed-resolved will not return invalidated data in any case, hence this flag + simply allows to discern the cases where data is known to be trustable, or where there is proof that + the data is "rightfully" unauthenticated (which includes cases where the underlying protocol or server + does not support authenticating data). + + + + + + Properties + + LLMNRHostname contains the hostname currently exposed on the network via LLMNR. It + usually follows the system hostname as may be queried via + gethostname3, + but may differ if a conflict is detected on the network. + + DNS contains an array containing all DNS servers currently used by + systmed-resolved. It contains similar information as the DNS server data written to + /run/systemd/resolve/resolv.conf. Each structure in the array consists of a numeric network interface + index, an address family, and a byte array containing the DNS server address (either 4 bytes in length + for IPv4 or 16 bytes in lengths for IPv6). The array contains DNS servers configured system-wide, + including those possibly read from a foreign /etc/resolv.conf or the + DNS= setting in /etc/systemd/resolved.conf, as well as + per-interface DNS server information either retrieved from + systemd-networkd8, + or configured by external software via SetLinkDNS() (see above). The network + interface index will be 0 for the system-wide configured services, and non-zero for the per-link + servers. + + Similarly, the Domains property contains an array containing all search and + routing domains currently used by systmed-resolved. Each entry consists of a network interface index (again, 0 + encodes system-wide entries), the actual domain name, and whether the entry is used only for routing + (true), or for both routing and searching (false). + + The TransactionStatistics property contains information about the number of + transactions systmed-resolved has been processing. It contains a pair of unsigned 64-bit counters, the first + containing the number of currently ongoing transactions, the second the number of total transactions + systmed-resolved is processing or has processed. The latter value may be reset using the + ResetStatistics() call described above. Note that the number of transaction does + not directly map to the number of resolver bus calls issued. While simple look-ups usually require a + single transaction only, more complex look-ups might result in more, for example when CNAMEs or DNSSEC + are in use. + + The CacheStatistics property contains information about the executed cache + operations so far. It exposes three 64-bit counters: the first being the total number of current cache + entries (both positive and negative), the second number of cache hits, and the third the number of + cache misses. The latter counters may be reset using ResetStatistics() (see + above). + + The DNSSECStatistics property contains information about the DNSSEC + validations executed so far. It contains four 64-bit counters: the number of secure, insecure, bogus, + and indeterminate DNSSEC validations so far. The counters are increased for each validated RRset, and + each non-existance proof. The secure counter is increased for each operation that successfully verified + a signed reply, the insecure counter is increased for each operation that successfully verified that an + unsigned reply is rightfully unsigned. The bogus counter is increased for each operation where the + validation did not check out, and the data is likely to have been tempered with. Finally the + indeterminate counter is increased for each operation which did not complete because the necessary keys + could not be acquired or the cryptographic algorithms were unknown. + + The DNSSECSupported boolean property reports whether DNSSEC is enabled and + the selected DNS servers support it. It combines information about system-wide and per-link DNS + settings (see below), and only reports true if DNSSEC is enabled and supported on every interface for + which DNS is configured and for the system-wide settings if there are any. Note that systmed-resolved assumes + DNSSEC is supported by DNS servers until it verified that this is not the case. Thus, the reported + value may initially be true, until the first transactions are executed. + + + + + Link Object + + +$ gdbus introspect --system \ + --dest org.freedesktop.resolve1 \ + --object-path /org/freedesktop/resolve1/link/_34 + +node /org/freedesktop/resolve1/link/_34 { + interface org.freedesktop.resolve1.Link { + methods: + SetDNS(in a(iay) arg_0); + SetDomains(in a(sb) arg_0); + SetLLMNR(in s arg_0); + SetMulticastDNS(in s arg_0); + SetDNSSEC(in s arg_0); + SetDNSSECNegativeTrustAnchors(in as arg_0); + Revert(); + signals: + properties: + readonly t ScopesMask = 6; + readonly a(iay) DNS = []; + readonly a(sb) Domains = []; + readonly s LLMNR = 'yes'; + readonly s MulticastDNS = 'no'; + readonly s DNSSEC = ''; + readonly as DNSSECNegativeTrustAnchors = []; + readonly b DNSSECSupported = true; + }; + interface org.freedesktop.DBus.Peer { + }; + interface org.freedesktop.DBus.Introspectable { + }; + interface org.freedesktop.DBus.Properties { + }; +}; + + + For each Linux network interface a "Link" object is created, which exposes per-link DNS + configuration and state. Use GetLink() on the Manager interface to retrieve the + object path for a link object given the network interface index (see above). + + + Methods + + The various methods exposed by the Link interface are equivalent to their similarly named + counterparts on the Manager interface. e.g. SetDNS() on the Link object maps to + SetLinkDNS() on the Manager object, the main difference being that the later + expects an interface index to be speicified. Invoking the calls on the Manager interface has the + benefit of reducing roundtrips, as it is not necessary to first request the Link object path via + GetLink() before invoking the methods. For further details on these calls see the + Manager documentation above. + + + + Properties + + ScopesMask defines which resolver scopes are currently active on this + interface. This 64-bit unsigned integer field is a bit mask, consisting of a subset of the bits as the + flags parameter describe above. Specifically, it may have the DNS, LLMNR and MDNS bits (the latter in + IPv4 and IPv6 flavours) set. Each individual bit is set when the protocol applies to a specific + interface and is enabled for it. It is unset otherwise. Specifically, a multicast-capable interface in + "UP" state with an IP address is suitable for LLMNR or MulticastDNS, and any interface that is UP and + has an IP address is suitable for DNS. Note the relationship of the bits exposed here with the LLMNR + and MulticastDNS properties also exposed on the Link interface. The latter expose what is *configured* + to be used on the interface, the former expose what is actually used on the interface, taking into + account the abilities of the interface. + + DNSSECSupported exposes a boolean field that indicates whether DNSSEC is + currently configured and in use on the interface. Note that if DNSSEC is enabled on an interface it is + assumed available until it is detected that the configured server does not actually support it. Thus, + this property may initially report that DNSSEC is supported on an interface. + + The other properties reflect the state of the various configuration settings for the link, which + may be set with the various methods calls such as SetDNS() or SetLLMNR(). + + + + + Common Errors + + Many bus calls systmed-resolved exposes (in particular the resolver calls such + as ResolveHostname() on the Manager interface) return + some of the following errors: + + + org.freedesktop.resolve1.NoNameServers + No suitable DNS servers have been found to resolve a request. + + + org.freedesktop.resolve1.InvalidReply + A response from the selected DNS server could not be understood. + + + org.freedesktop.resolve1.NoSuchRR + The requested name exists, but there is no resource record of the requested type for + it. (This is the DNS NODATA case). + + org.freedesktop.resolve1.CNameLoop + The look-up failed because a CNAME or DNAME loop was detected. + + + org.freedesktop.resolve1.Aborted + The look-up was aborted, because the selected protocol became unavailable while the + operation was ongoing. + + + org.freedesktop.resolve1.NoSuchService + A service look-up was successful, but the SRV record reported that the service is not + available. + + org.freedesktop.resolve1.DnssecFailed + The acquired response did not pass DNSSEC validation. + + + org.freedesktop.resolve1.NoTrustAnchor + No chain of trust could be established for the response, to a configured DNSSEC trust + anchor. + + + org.freedesktop.resolve1.ResourceRecordTypeUnsupported + The requested resource record type is not supported on the selected DNS servers. This + error is generated for example when an RRSIG record is requested from a DNS server that does not + support DNSSEC. + + + + org.freedesktop.resolve1.NoSuchLink + No network interface with the specified network interface index exists. + + + org.freedesktop.resolve1.LinkBusy + The requested configuration change can not be made, because + systemd-networkd8, + already took possession of the interface and supplied configuration data for it. + + + org.freedesktop.resolve1.NetworkDown + The requested look-up failed because the system is currently not connected to any + suitable network. + + org.freedesktop.resolve1.DnsError.NXDOMAIN + org.freedesktop.resolve1.DnsError.REFUSED + ... + The look-up failed with a DNS return code reporting a failure. The error names used as + suffixes here are defined in by IANA in + DNS RCODEs. + + + + + + + Versioning + + These D-Bus interfaces follow + the usual interface versioning guidelines. + + diff --git a/man/rules/meson.build b/man/rules/meson.build index c881bae6cd..1552fe2d10 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -49,6 +49,7 @@ manpages = [ ['org.freedesktop.locale1', '5', [], 'ENABLE_LOCALED'], ['org.freedesktop.login1', '5', [], 'ENABLE_LOGIND'], ['org.freedesktop.machine1', '5', [], 'ENABLE_MACHINED'], + ['org.freedesktop.resolve1', '5', [], 'ENABLE_RESOLVE'], ['org.freedesktop.timedate1', '5', [], 'ENABLE_TIMEDATED'], ['os-release', '5', [], ''], ['pam_systemd', '8', [], 'HAVE_PAM'], diff --git a/man/systemd-resolved.service.xml b/man/systemd-resolved.service.xml index 53c46a1018..3fb0846157 100644 --- a/man/systemd-resolved.service.xml +++ b/man/systemd-resolved.service.xml @@ -34,11 +34,12 @@ resolver and responder. Local applications may submit network name resolution requests via three interfaces: - The native, fully-featured API systemd-resolved exposes on the bus. See the - API Documentation for - details. Usage of this API is generally recommended to clients as it is asynchronous and fully featured (for - example, properly returns DNSSEC validation status and interface scope for addresses as necessary for supporting - link-local networking). + The native, fully-featured API systemd-resolved exposes on the bus, + see + org.freedesktop.resolve15 + for details. Usage of this API is generally recommended to clients as it is asynchronous and fully + featured (for example, properly returns DNSSEC validation status and interface scope for addresses as + necessary for supporting link-local networking). The glibc getaddrinfo3 API as defined From edc6a8031e21b76404a2c45222586ccb1cac2276 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Thu, 9 Apr 2020 22:49:47 +0200 Subject: [PATCH 14/26] resolved: add dbus parameter names --- src/resolve/resolved-bus.c | 177 ++++++++++++++++++++++++++++---- src/resolve/resolved-link-bus.c | 57 ++++++++-- 2 files changed, 207 insertions(+), 27 deletions(-) diff --git a/src/resolve/resolved-bus.c b/src/resolve/resolved-bus.c index ffe61bdb9f..0f60c42963 100644 --- a/src/resolve/resolved-bus.c +++ b/src/resolve/resolved-bus.c @@ -1853,26 +1853,165 @@ static const sd_bus_vtable resolve_vtable[] = { SD_BUS_PROPERTY("DNSSECNegativeTrustAnchors", "as", bus_property_get_ntas, 0, 0), SD_BUS_PROPERTY("DNSStubListener", "s", bus_property_get_dns_stub_listener_mode, offsetof(Manager, dns_stub_listener_mode), 0), - SD_BUS_METHOD("ResolveHostname", "isit", "a(iiay)st", bus_method_resolve_hostname, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ResolveAddress", "iiayt", "a(is)t", bus_method_resolve_address, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ResolveRecord", "isqqt", "a(iqqay)t", bus_method_resolve_record, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ResolveService", "isssit", "a(qqqsa(iiay)s)aayssst", bus_method_resolve_service, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ResetStatistics", NULL, NULL, bus_method_reset_statistics, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("FlushCaches", NULL, NULL, bus_method_flush_caches, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ResetServerFeatures", NULL, NULL, bus_method_reset_server_features, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetLink", "i", "o", bus_method_get_link, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetLinkDNS", "ia(iay)", NULL, bus_method_set_link_dns_servers, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetLinkDomains", "ia(sb)", NULL, bus_method_set_link_domains, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetLinkDefaultRoute", "ib", NULL, bus_method_set_link_default_route, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetLinkLLMNR", "is", NULL, bus_method_set_link_llmnr, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetLinkMulticastDNS", "is", NULL, bus_method_set_link_mdns, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetLinkDNSOverTLS", "is", NULL, bus_method_set_link_dns_over_tls, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetLinkDNSSEC", "is", NULL, bus_method_set_link_dnssec, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetLinkDNSSECNegativeTrustAnchors", "ias", NULL, bus_method_set_link_dnssec_negative_trust_anchors, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("RevertLink", "i", NULL, bus_method_revert_link, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("RegisterService", "sssqqqaa{say}", "o", bus_method_register_service, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("UnregisterService", "o", NULL, bus_method_unregister_service, SD_BUS_VTABLE_UNPRIVILEGED), + + SD_BUS_METHOD_WITH_NAMES("ResolveHostname", + "isit", + SD_BUS_PARAM(ifindex) + SD_BUS_PARAM(name) + SD_BUS_PARAM(family) + SD_BUS_PARAM(flags), + "a(iiay)st", + SD_BUS_PARAM(addresses) + SD_BUS_PARAM(canonical) + SD_BUS_PARAM(flags), + bus_method_resolve_hostname, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("ResolveAddress", + "iiayt", + SD_BUS_PARAM(ifindex) + SD_BUS_PARAM(family) + SD_BUS_PARAM(address) + SD_BUS_PARAM(flags), + "a(is)t", + SD_BUS_PARAM(names) + SD_BUS_PARAM(flags), + bus_method_resolve_address, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("ResolveRecord", + "isqqt", + SD_BUS_PARAM(ifindex) + SD_BUS_PARAM(name) + SD_BUS_PARAM(class) + SD_BUS_PARAM(type) + SD_BUS_PARAM(flags), + "a(iqqay)t", + SD_BUS_PARAM(records) + SD_BUS_PARAM(flags), + bus_method_resolve_record, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("ResolveService", + "isssit", + SD_BUS_PARAM(ifindex) + SD_BUS_PARAM(name) + SD_BUS_PARAM(type) + SD_BUS_PARAM(domain) + SD_BUS_PARAM(family) + SD_BUS_PARAM(flags), + "a(qqqsa(iiay)s)aayssst", + SD_BUS_PARAM(srv_data) + SD_BUS_PARAM(txt_data) + SD_BUS_PARAM(canonical_name) + SD_BUS_PARAM(canonical_type) + SD_BUS_PARAM(canonical_domain) + SD_BUS_PARAM(flags), + bus_method_resolve_service, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetLink", + "i", + SD_BUS_PARAM(ifindex), + "o", + SD_BUS_PARAM(path), + bus_method_get_link, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetLinkDNS", + "ia(iay)", + SD_BUS_PARAM(ifindex) + SD_BUS_PARAM(addresses), + NULL,, + bus_method_set_link_dns_servers, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetLinkDomains", + "ia(sb)", + SD_BUS_PARAM(ifindex) + SD_BUS_PARAM(domains), + NULL,, + bus_method_set_link_domains, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetLinkDefaultRoute", + "ib", + SD_BUS_PARAM(ifindex) + SD_BUS_PARAM(enable), + NULL,, + bus_method_set_link_default_route, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetLinkLLMNR", + "is", + SD_BUS_PARAM(ifindex) + SD_BUS_PARAM(mode), + NULL,, + bus_method_set_link_llmnr, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetLinkMulticastDNS", + "is", + SD_BUS_PARAM(ifindex) + SD_BUS_PARAM(mode), + NULL,, + bus_method_set_link_mdns, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetLinkDNSOverTLS", + "is", + SD_BUS_PARAM(ifindex) + SD_BUS_PARAM(mode), + NULL,, + bus_method_set_link_dns_over_tls, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetLinkDNSSEC", + "is", + SD_BUS_PARAM(ifindex) + SD_BUS_PARAM(mode), + NULL,, + bus_method_set_link_dnssec, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetLinkDNSSECNegativeTrustAnchors", + "ias", + SD_BUS_PARAM(ifindex) + SD_BUS_PARAM(names), + NULL,, + bus_method_set_link_dnssec_negative_trust_anchors, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("RevertLink", + "i", + SD_BUS_PARAM(ifindex), + NULL,, + bus_method_revert_link, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("RegisterService", + "sssqqqaa{say}", + SD_BUS_PARAM(name) + SD_BUS_PARAM(name_template) + SD_BUS_PARAM(type) + SD_BUS_PARAM(service_port) + SD_BUS_PARAM(service_priority) + SD_BUS_PARAM(serwise_weight) + SD_BUS_PARAM(txt_datas), + "o", + SD_BUS_PARAM(service_path), + bus_method_register_service, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("UnregisterService", + "o", + SD_BUS_PARAM(service_path), + NULL,, + bus_method_unregister_service, + SD_BUS_VTABLE_UNPRIVILEGED), + + SD_BUS_METHOD("ResetStatistics", + NULL, + NULL, + bus_method_reset_statistics, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD("FlushCaches", + NULL, + NULL, + bus_method_flush_caches, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD("ResetServerFeatures", + NULL, + NULL, + bus_method_reset_server_features, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_VTABLE_END, }; diff --git a/src/resolve/resolved-link-bus.c b/src/resolve/resolved-link-bus.c index 2a166c11b0..a2d61f398d 100644 --- a/src/resolve/resolved-link-bus.c +++ b/src/resolve/resolved-link-bus.c @@ -697,14 +697,55 @@ const sd_bus_vtable link_vtable[] = { SD_BUS_PROPERTY("DNSSECNegativeTrustAnchors", "as", property_get_ntas, 0, 0), SD_BUS_PROPERTY("DNSSECSupported", "b", property_get_dnssec_supported, 0, 0), - SD_BUS_METHOD("SetDNS", "a(iay)", NULL, bus_link_method_set_dns_servers, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetDomains", "a(sb)", NULL, bus_link_method_set_domains, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetDefaultRoute", "b", NULL, bus_link_method_set_default_route, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetLLMNR", "s", NULL, bus_link_method_set_llmnr, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetMulticastDNS", "s", NULL, bus_link_method_set_mdns, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetDNSOverTLS", "s", NULL, bus_link_method_set_dns_over_tls, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetDNSSEC", "s", NULL, bus_link_method_set_dnssec, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetDNSSECNegativeTrustAnchors", "as", NULL, bus_link_method_set_dnssec_negative_trust_anchors, SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetDNS", + "a(iay)", + SD_BUS_PARAM(addresses), + NULL,, + bus_link_method_set_dns_servers, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetDomains", + "a(sb)", + SD_BUS_PARAM(domains), + NULL,, + bus_link_method_set_domains, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetDefaultRoute", + "b", + SD_BUS_PARAM(enable), + NULL,, + bus_link_method_set_default_route, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetLLMNR", + "s", + SD_BUS_PARAM(mode), + NULL,, + bus_link_method_set_llmnr, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetMulticastDNS", + "s", + SD_BUS_PARAM(mode), + NULL,, + bus_link_method_set_mdns, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetDNSOverTLS", + "s", + SD_BUS_PARAM(mode), + NULL,, + bus_link_method_set_dns_over_tls, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetDNSSEC", + "s", + SD_BUS_PARAM(mode), + NULL,, + bus_link_method_set_dnssec, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetDNSSECNegativeTrustAnchors", + "as", + SD_BUS_PARAM(names), + NULL,, + bus_link_method_set_dnssec_negative_trust_anchors, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD("Revert", NULL, NULL, bus_link_method_revert, SD_BUS_VTABLE_UNPRIVILEGED), SD_BUS_VTABLE_END From 3031660c211b87dba9f039c824788441b1f0598e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 10 Apr 2020 11:34:32 +0200 Subject: [PATCH 15/26] man: import org.freedesktop.systemd1(3) from the wiki As usual, the formatting was fixed and various obvious updates were done, but nothing major. I removed documentation of snapshots and related methods though. --- TODO | 3 + man/org.freedesktop.systemd1.xml | 2018 ++++++++++++++++++++++++++++++ man/rules/meson.build | 1 + man/systemd.xml | 4 + 4 files changed, 2026 insertions(+) create mode 100644 man/org.freedesktop.systemd1.xml diff --git a/TODO b/TODO index ef204dfed0..0838cda5c4 100644 --- a/TODO +++ b/TODO @@ -4,6 +4,9 @@ Bugfixes: manager or system manager can be always set. It would be better to reject them when parsing config. +* busctl prints errors to stdout: + busctl tree org.freedesktop.systemd1 /org/freedesktop/systemd1 + External: * Fedora: add an rpmlint check that verifies that all unit files in the RPM are listed in %systemd_post macros. diff --git a/man/org.freedesktop.systemd1.xml b/man/org.freedesktop.systemd1.xml new file mode 100644 index 0000000000..24fafac272 --- /dev/null +++ b/man/org.freedesktop.systemd1.xml @@ -0,0 +1,2018 @@ + + + + + + + org.freedesktop.systemd1 + systemd + + + + org.freedesktop.systemd1 + 5 + + + + org.freedesktop.systemd1 + The D-Bus interface of systemd-systemdd + + + + Introduction + + + systemd1 and its + auxiliary daemons expose a number of APIs over D-Bus. This page describes the various APIs exposed by the + system and service manager itself, and does not cover the auxiliary daemons. + + + The service manager exposes a number of objects on the bus: one + Manager object as central entry point for clients, and individual objects + for each unit and for each queued job. The unit objects each implement a generic + Unit interface plus a type-specific interface. For example, service units + implement org.freedesktop.systemd1.Unit as well as + org.freedesktop.system1.Service. The manager object can be used to list + unit and job objects, or to directly convert a unit name or job id into a bus path of the corresponding + D-Bus object. + + Properties exposing time values are usually encoded in microseconds (usec) on the bus, even if + their corresponding settings in the unit files are in seconds. + + In contrast to most of the other services of the systemd suite PID 1 does not use PolicyKit for + controlling access to privileged operations, but relies exclusively on the low-level D-Bus policy + language. (This is done in order to avoid a cyclic dependency between PolicyKit and systemd/PID 1.) This + means that sensitive operations exposed by PID 1 on the bus are generally not available to unprivileged + processes directly. However some (such as shutdown/reboot/suspend) are made available through the D-Bus + API of logind, see + org.freedesktop.login15. + + + + + The Manager Object + + The main entry point object is available on the fixed + /org/freedesktop/systemd1 object path: + + +$ gdbus introspect --system \ + --dest org.freedesktop.systemd1 \ + --object-path /org/freedesktop/systemd1 + +node /org/freedesktop/systemd1 { + interface org.freedesktop.systemd1.Manager { + methods: + GetUnit(in s name, + out o unit); + GetUnitByPID(in u pid, + out o unit); + LoadUnit(in s name, + out o unit); + StartUnit(in s name, + in s mode, + out o job); + StartUnitReplace(in s old_unit, + in s new_unit, + in s mode, + out o job); + StopUnit(in s name, + in s mode, + out o job); + ReloadUnit(in s name, + in s mode, + out o job); + RestartUnit(in s name, + in s mode, + out o job); + TryRestartUnit(in s name, + in s mode, + out o job); + ReloadOrRestartUnit(in s name, + in s mode, + out o job); + ReloadOrTryRestartUnit(in s name, + in s mode, + out o job); + KillUnit(in s name, + in s who, + in i signal); + ResetFailedUnit(in s name); + GetJob(in u id, + out o job); + CancelJob(in u id); + ClearJobs(); + ResetFailed(); + ListUnits(out a(ssssssouso) units); + ListJobs(out a(usssoo) jobs); + Subscribe(); + Unsubscribe(); + Reload(); + Reexecute(); + Exit(); + Reboot(); + PowerOff(); + Halt(); + KExec(); + SwitchRoot(in s new_root, + in s init); + SetEnvironment(in as names); + UnsetEnvironment(in as names); + UnsetAndSetEnvironment(in as unset, + in as set); + ListUnitFiles(out a(ss) files); + GetUnitFileState(in s file, + out s state); + EnableUnitFiles(in as files, + in b runtime, + in b force, + out b carries_install_info, + out a(sss) changes); + DisableUnitFiles(in as files, + in b runtime, + out a(sss) changes); + ReenableUnitFiles(in as files, + in b runtime, + in b force, + out b carries_install_info, + out a(sss) changes); + LinkUnitFiles(in as files, + in b runtime, + in b force, + out a(sss) changes); + PresetUnitFiles(in as files, + in b runtime, + in b force, + out b carries_install_info, + out a(sss) changes); + MaskUnitFiles(in as files, + in b runtime, + in b force, + out a(sss) changes); + UnmaskUnitFiles(in as files, + in b runtime, + out a(sss) changes); + SetDefaultTarget(in as files, + out a(sss) changes); + GetDefaultTarget(out s name); + SetUnitProperties(in s name, + in b runtime, + in a(sv) properties); + StartTransientUnit(in s name, + in s mode, + in a(sv) properties, + in a(sa(sv)) aux, + out o job); + signals: + UnitNew(s id, + o unit); + UnitRemoved(s id, + o unit); + JobNew(u id, + o job, + s unit); + JobRemoved(u id, + o job, + s unit, + s result); + StartupFinished(t firmware, + t loader, + t kernel, + t initrd, + t userspace, + t total); + UnitFilesChanged(); + Reloading(b active); + properties: + readonly s Version = 'systemd 205'; + readonly s Features = '+PAM +LIBWRAP +AUDIT +SELINUX +IMA +SYSVINIT +LIBCRYPTSETUP +GCRYPT +ACL +XZ'; + readonly s Tainted = ''; + readonly t FirmwareTimestamp = 0; + readonly t FirmwareTimestampMonotonic = 0; + readonly t LoaderTimestamp = 0; + readonly t LoaderTimestampMonotonic = 0; + readonly t KernelTimestamp = 0; + readonly t KernelTimestampMonotonic = 0; + readonly t InitRDTimestamp = 0; + readonly t InitRDTimestampMonotonic = 0; + readonly t UserspaceTimestamp = 1373892700771932; + readonly t UserspaceTimestampMonotonic = 347348267507; + readonly t FinishTimestamp = 1373892717621078; + readonly t FinishTimestampMonotonic = 347365116654; + readonly t GeneratorsStartTimestamp = 1374345509428734; + readonly t GeneratorsStartTimestampMonotonic = 500549330609; + readonly t GeneratorsFinishTimestamp = 1374345509562375; + readonly t GeneratorsFinishTimestampMonotonic = 500549464250; + readonly t UnitsLoadStartTimestamp = 1374345509562782; + readonly t UnitsLoadStartTimestampMonotonic = 500549464657; + readonly t UnitsLoadFinishTimestamp = 1374345509652212; + readonly t UnitsLoadFinishTimestampMonotonic = 500549554088; + readonly t SecurityStartTimestamp = 1374345509562782; + readonly t SecurityStartTimestampMonotonic = 500549464657; + readonly t SecurityFinishTimestamp = 1374345509652212; + readonly t SecurityFinishTimestampMonotonic = 500549554088; + readwrite s LogLevel = 'info'; + readwrite s LogTarget = 'journal'; + readonly u NNames = 100; + readonly u NJobs = 0; + readonly u NInstalledJobs = 266; + readonly u NFailedJobs = 4; + readonly d Progress = 1.0; + readonly as Environment = ['PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin', 'LANG=C']; + readonly b ConfirmSpawn = false; + readonly b ShowStatus = true; + readonly as UnitPath = ['/etc/systemd/system', '/run/systemd/system', '/run/systemd/generator', '/usr/local/lib/systemd/system', '/usr/lib/systemd/system']; + readonly s DefaultStandardOutput = 'journal'; + readonly s DefaultStandardError = 'inherit'; + readwrite t RuntimeWatchdogUSec = 0; + readwrite t ShutdownWatchdogUSec = 600000000; + readonly s Virtualization = ''; + readonly s Architecture = 'x86-64'; + }; + interface org.freedesktop.DBus.Properties { + ... + }; + interface org.freedesktop.DBus.Peer { + ... + }; + interface org.freedesktop.DBus.Introspectable { + ... + }; +}; + + + + Security + + Read access is generally granted to all clients, but changes may only be made by privileged + clients. PolicyKit is not used by this service, and access is controlled exclusively via the D-Bus + policy. + + + + Methods + + Note that many of the calls exist twice: once on the Manager + object, and once on the respective unit objects. This is to optimize access times so that methods that + belong to unit objects do not have to be called with a resolved unit path, but can be called with only + the unit id, too. + + GetUnit() may be used to get the unit object path for a unit name. It takes + the unit name and returns the object path. If a unit has not been loaded yet by this name this call + will fail. + + GetUnitByPID() may be used to get the unit object path of the unit a process + ID belongs to. Takes a UNIX PID and returns the object path. The PID must refer to an existing process + of the system. + + LoadUnit() is similar to GetUnit() but will load the + unit from disk if possible. + + StartUnit() enqeues a start job, and possibly depending jobs. Takes the unit + to activate, plus a mode string. The mode needs to be one of replace, + fail, isolate, ignore-dependencies, + ignore-requirements. If replace the call will start the unit and + its dependencies, possibly replacing already queued jobs that conflict with this. If + fail the call will start the unit and its dependencies, but will fail if this would + change an already queued job. If isolate the call will start the unit in question + and terminate all units that aren't dependencies of it. If ignore-dependencies it + will start a unit but ignore all its dependencies. If ignore-requirements it will + start a unit but only ignore the requirement dependencies. It is not recommended to make use of the + latter two options. Returns the newly created job object. + + StartUnitReplace() is similar to StartUnit() but + replaces a job that is queued for one unit by a job for another. + + StopUnit() is similar to StartUnit() but stops the + specified unit rather than starting it. Note that isolate mode is invalid for this + call. + + ReloadUnit(), RestartUnit(), + TryRestartUnit(), ReloadOrRestartUnit(), + ReloadOrTryRestartUnit() may be used to restart and/or reload a unit, and takes + similar arguments as StartUnit(). Reloading is done only if the unit is already + running and fails otherwise. If a service is restarted that isn't running it will be started, unless + the "Try" flavor is used in which case a service that isn't running is not affected by the restart. The + "ReloadOrRestart" flavors attempt a reload if the unit supports it and use a restart otherwise. + + KillUnit() may be used to kill (i.e. send a signal to) all processes of a + unit. Takes the unit name, an enum who and a UNIX + signal number to send. The who enum is one of + main, control or all. If + main, only the main process of a unit is killed. If control only + the control process of the unit is killed, if all all processes are killed. A + control process is for example a process that is configured via + ExecStop= and is spawned in parallel to the main daemon process, in order to shut it + down. + + GetJob() returns the job object path for a specific job, identified by its + id. + + CancelJob() cancels a specific job identified by its numer ID. This + operation is also available in the Cancel() method of Job objects (see below), and + exists primarily to reduce the necessary round trips to execute this operation. Note that this will not + have any effect on jobs whose execution has already begun. + + ClearJobs() flushes the job queue, removing all jobs that are still + queued. Note that this does not have any effect on jobs whose execution has already begun, it only + flushes jobs that are queued and have not yet begun execution. + + ResetFailedUnit() resets the "failed" state of a specific unit. + + ResetFailed() resets the "failed" state of all units. + + ListUnits() returns an array with all currently loaded units. Note that + units may be known by multiple names at the same name, and hence there might be more unit names loaded + than actual units behind them. The array consists of structures with the following elements: + + The primary unit name as string + + The human readable description string + + The load state (i.e. whether the unit file has been loaded + successfully) + + The active state (i.e. whether the unit is currently started or + not) + + The sub state (a more fine-grained version of the active state that is specific to + the unit type, which the active state is not) + + A unit that is being followed in its state by this unit, if there is any, otherwise + the empty string. + + The unit object path + + If there is a job queued for the job unit the numeric job id, 0 + otherwise + + The job type as string + + The job object path + + + ListJobs() returns an array with all currently queued jobs. Returns an array + consisting of structures with the following elements: + + The numeric job id + + The primary unit name for this job + + The job type as string + + The job state as string + + The job object path + + The unit object path + + + Subscribe() enables most bus signals to be sent out. Clients which are + interested in signals need to call this function. Signals are only sent out if at least one client + invoked this function. Unsubscribe() undoes the signal subscription that + Subscribe() implements. It is not necessary to invoke + Unsubscribe() as clients are tracked. Signals are no longer sent out as soon as + all clients which previously asked for Subscribe() either closed the bus + connection or invoked Unsubscribe(). + + Reload() may be invoked to reload all unit files. + + Reexecute() may be invoked to reexecute the main manager process. It will + serialize its state, reexecute, and deserizalize the state again. This is useful for upgrades and is a + more comprehensive version of Reload(). + + Exit() may be invoked to ask the manager to exit. This is not available for + the system manager and is useful only for user session managers. + + Reboot(), PowerOff(), Halt(), + KExec() may be used to ask for immediate reboot, powering down, halt or kexec + based reboot of the system. Note that this does not shut down any services and immediately transitions + into the reboot process. These functions are normally only called as last step of shutdown, and should + not be called directly. To shut down the machine it is a much better choice generally to invoke + Reboot() and PoweOff() on the + systemd-logind manager object; see + org.freedesktop.login15 + for more information. + + SwitchRoot() may be used to transition to a new root directory. This is + intended to be used by initial RAM disks. The call takes two arguments: the new root directory (which + needs to be specified), plus an init binary path (which may be left empty, in which case it is + automatically searched for). The state of the system manager will be serialized before the + transition. After the transition the manager binary on the main system is invoked and replaces the old + PID 1. All state will then be deserialized. + + SetEnvironment() may be used to alter the environment block that is passed + to all spawned processes. Takes a string array with environment variable assignments. Settings passed + will override previously set variables. + + UnsetEnvironment() may be used to unset environment variables. Takes a + string array with environment variable names. All variables specified will be unset (if they have been + set previously) and no longer be passed to all spawned processes. This call has no effect for variables + that were previously not set, but will not fail in that case. + + UnsetAndSetEnvironment() is a combination of + UnsetEnvironment() and SetEnvironment(). It takes two + lists. The first one is a list of variables to unset, the second one of assignments to set. If a + variable is listed in both, the variable is set after this call, i.e. the set list overrides the unset + list. + + ListUnitFiles() returns an array of unit names plus their enablement + status. Note that ListUnit() returns a list of units currently loaded into memory, + while ListUnitFiles() returns a list of unit files that could + be found on disk. Note that while most units are read directly from a unit file with the same name some + units are not backed by files, and some files (templates) cannot directly be loaded as units but need + to be instantiated. + + GetUnitFileState() returns the current enablement status of specific unit + file. + + EnableUnitFiles() may be used to enable one or more units in the system (by + creating symlinks to them in /etc or /run). It takes a list + of unit files to enable (either just file names or full absolute paths if the unit files are residing + outside the usual unit search paths), and two booleans: the first controls whether the unit shall be + enabled for runtime only (true, /run), or persistently (false, + /etc). The second one controls whether symlinks pointing to other units shall be + replaced if necessary. This call returns one boolean and an array with the changes made. The boolean + signals whether the unit files contained any enablement information (i.e. an [Install]) section. The + changes list consists of structures with three strings: the type of the change (one of + symlink or unlink), the file name of the symlink and the + destination of the symlink. Note that most of the following calls return a changes list in the same + format. + + Similarly, DisableUnitFiles() disables one or more units in the system, + i.e. removes all symlinks to them in /etc and /run. + + Similarly, ReenableUnitFiles() applies the changes to one or more units that + would result from disabling and enabling the unit quickly one after the other in an atomic + fashion. This is useful to apply updated [Install] information contained in unit files. + + Similarly, LinkUnitFiles() links unit files (that are located outside of the + usual unit search paths) into the unit search path. + + Similarly, PresetUnitFiles() enables/disables one or more units file + according to the preset policy. See + systemd.preset7 for more + information. + + Similarly, MaskUnitFiles() masks unit files, and + UnmaskUnitFiles() unmasks them again. + + SetDefaultTarget() changes the default.target link. See + bootup7 for more + information + + GetDefaultTarget() retrieves the name of the unit to which + default.target is aliased + + SetUnitProperties() may be used to modify certain unit properties at + runtime. Not all properties may be changed at runtime, but many resource management settings (primarily + those listed in + systemd.cgroup5) + may. The changes are applied instantly, and stored on disk for future boots, unless + runtime is true, in which case the settings only apply until the next + reboot. name is the name of the unit to modify. properties are + the settings to set, encoded as an array of property name and value pairs. Note that this is not a + dictionary! Note that when setting array properties with this call this usually results in appending to + the pre-configured array. To reset the configured arrays set the property to an empty array first, then + append to it. + + StartTransientUnit() may be used to create and start a transient unit, which + will be released as soon as it is not running or referenced anymore or the system is + rebooted. name is the unit name including suffix, and must be + unique. mode is the same as in StartUnit(), + properties contains properties of the unit, specified like in + SetUnitProperties(). aux is currently unused and should be + passed as empty array. See the New Control Group + Interface for more information how to make use of this functionality for resource control + purposes. + + + + + Signals + + Note that most signals are sent out only after Subscribe() has been invoked + by at least one client. Make sure to invoke this call when subscribing to these signals! + + UnitNew() and UnitRemoved() are sent out each time a + new unit is loaded or unloaded. Note that this has little to do with whether a unit is available on + disk or not, and simply reflects the units that are currently loaded into memory. The signals take two + parameters: the primary unit name and the object path. + + JobNew() and JobRemoved() are sent out each time a new + job is queued or dequeued. Both signals take the numeric job ID, the bus path and the primary unit name + for this job as argument. JobRemoved() also includes a result string, being one of + done, canceled, timeout, + failed, dependency, + skipped. done indicates successful execution of a + job. canceled indicates that a job has been canceled (via + CancelJob() above) before it finished execution (this doesn't necessarily mean + though that the job operation is actually cancelled too, see above). timeout + indicates that the job timeout was reached. failed indicates that the job + failed. dependency indicates that a job this job has been depending on failed and + the job hence has been removed too. skipped indicates that a job was skipped because + it didn't apply to the units current state. + + StartupFinished() is sent out when startup finished. It carries six + microsecond timespan values each indicating how much boot time has been spent in the firmware (if + known), in the boot loader (if known), in the kernel initialization phase, in the initrd (if known), in + userspace and in total. These values may also be calculated from the + FirmwareTimestampMonotonic, LoaderTimestampMonotonic, + InitRDTimestampMonotonic, UserspaceTimestampMonotonic, + FinishTimestampMonotonic properties (see below). + + UnitFilesChanged() is sent out each time the list of enabled or masked unit + files on disk have changed. + + Reloading() is sent out immediately before a daemon reload is done (with the + boolean parameter set to True) and after a daemon reload is completed (with the boolean parameter set + to False). This may be used by UIs to optimize UI updates + + + + Properties + + Most properties simply reflect the respective options in + /etc/systemd/system.conf and the kernel command line. + + The others: + + Version encodes the version string of the running systemd instance. Note that + the version string is purely informational, it should not be parsed, one may not assume the version to + be formatted in any particular way. We take the liberty to change the versioning scheme at any time and + it is not part of the API. + + Features encodes the features that have been enabled and disabled for this + build. Enabled options are prefixed with +, disabled options with -. + + Tainted encodes a couple of taint flags, as a colon-separated list. When + systemd detects it is run on a system with certain problems it will set an appropriate taint + flag. Taints may be used to lower the chance of bogus bug reports. The following taints are currently + known: split-usr, mtab-not-symlink, + cgroups-missing, local-hwclock. split-usr is + set if /usr is not pre-mounted when systemd is first invoked. See + + Booting Without /usr is Broken + for details why this is bad. mtab-not-symlink indicates that + /etc/mtab is not a symlink to /proc/self/mounts as + required. cgroups-missing indicates that control groups have not been enabled in the + kernel. local-hwclock indicates that the local RTC is configured to be in local time + rather than UTC. + + FirmwareTimestamp, FirmwareTimestampMonotonic, + LoaderTimestamp, LoaderTimestampMonotonic, + KernelTimestamp, KernelTimestampMonotonic, + InitRDTimestamp, InitRDTimestampMonotonic, + UserspaceTimestamp, UserspaceTimestampMonotonic, + FinishTimestamp, FinishTimestampMonotonic encode + CLOCK_REALTIME and CLOCK_MONOTONIC microsecond timestamps + taken when the firmware first began execution, when the boot loader first began execution, when the + kernel first began execution, when the initrd first began execution, when the main systemd instance + began execution and finally, when all queued startup jobs finished execution. These values are useful + for determining boot-time performance. Note that as monotonic time begins with the kernel startup the + KernelTimestampMonotonic timestamp will always be 0, and FirmwareTimestampMonotonic and + LoaderTimestampMonotonic are to be read as negative values. Also, not all fields are available, + depending on the used firmware, boot loader or initrd implementation. In these cases the respective + pairs of timestamps are both 0, indicating that no data is available. + + Similarly, the SecurityStartTimestamp, + GeneratorsStartTimestamp and LoadUnitTimestamp (plus their + monotonic and stop counterparts) expose performance data for uploading the security policies to the + kernel (such as the SELinux, IMA, or SMACK policies), for running the generator tools and for loading + the unit files + + NNames encodes how many unit names are currently known. This only includes + names of units that are currently loaded and can be more than actually loaded units since units may + have more than one name. + + NJobs encodes how many jobs are currently queued. + + NInstalledJobs encodes how many jobs have ever been queued in total. + + NFailedJobs encodes how many jobs have ever failed in total. + + Progress encodes boot progress as floating point value between 0.0 and + 1.0. This value begins at 0.0 at early-boot and ends at 1.0 when boot is finished and is based on the + number of executed and queued jobs. After startup this field is always 1.0 indicating a finished + boot. + + Environment encodes the environment block passed to all executed services. It + may be altered with bus calls such as SetEnvironment() (see above). + + UnitPath encodes the currently active unit file search path. It is an array of + strings, each being one file system path + + Virtualization contains a short ID string describing the virtualization + technology the system runs in. On bare-metal hardware this is the empty string, otherwise an identifier + such as kvm, vmware and so on. For a full list of IDs see + systemd-detect-virt1. + Note that only the "innermost" virtualization technology is exported here. This detects both + full-machine virtualizations (VMs) and shared-kernel virtualization (containers). + + Architecture contains a short ID string describing the architecture the + systemd instance is running on. This follows the same vocabulary as + ConditionArchitectures=. + + ControlGroup contains the root control group path of this system manager. Note + that the root path is encoded as empty string here (not as /!), so that it can be + appended to /sys/fs/cgroup/systemd easily. This value will be set to the empty + string for the host instance, and some other string for container instances + + + + + Unit Objects + + +$ gdbus introspect --system --dest org.freedesktop.systemd1 \ + --object-path /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice + +node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice { + interface org.freedesktop.systemd1.Unit { + methods: + Start(in s mode, + out o job); + Stop(in s mode, + out o job); + Reload(in s mode, + out o job); + Restart(in s mode, + out o job); + TryRestart(in s mode, + out o job); + ReloadOrRestart(in s mode, + out o job); + ReloadOrTryRestart(in s mode, + out o job); + Kill(in s who, + in i signal); + ResetFailed(); + SetProperties(in b runtime, + in a(sv) properties); + signals: + properties: + readonly s Id = 'avahi-daemon.service'; + readonly as Names = ['avahi-daemon.service']; + readonly s Following = ''; + readonly as Requires = ['avahi-daemon.socket', 'dbus.socket', 'basic.target']; + readonly as RequiresOverridable = []; + readonly as Requisite = []; + readonly as RequisiteOverridable = []; + readonly as Wants = []; + readonly as BindsTo = []; + readonly as PartOf = []; + readonly as RequiredBy = []; + readonly as RequiredByOverridable = []; + readonly as WantedBy = ['multi-user.target']; + readonly as BoundBy = []; + readonly as ConsistsOf = []; + readonly as Conflicts = ['shutdown.target']; + readonly as ConflictedBy = []; + readonly as Before = ['shutdown.target', 'multi-user.target']; + readonly as After = ['avahi-daemon.socket', 'systemd-journald.socket', 'dbus.socket', 'basic.target']; + readonly as OnFailure = []; + readonly as Triggers = []; + readonly as TriggeredBy = ['avahi-daemon.socket']; + readonly as PropagatesReloadTo = []; + readonly as ReloadPropagatedFrom = []; + readonly as RequiresMountsFor = []; + readonly s Description = 'Avahi mDNS/DNS-SD Stack'; + readonly s SourcePath = ''; + readonly as DropInPaths = []; + readonly as Documentation = []; + readonly s LoadState = 'loaded'; + readonly s ActiveState = 'active'; + readonly s SubState = 'running'; + readonly s FragmentPath = '/usr/lib/systemd/system/avahi-daemon.service'; + readonly s UnitFileState = 'enabled'; + readonly t InactiveExitTimestamp = 1368576738559539; + readonly t InactiveExitTimestampMonotonic = 22561234; + readonly t ActiveEnterTimestamp = 1368576738648314; + readonly t ActiveEnterTimestampMonotonic = 22650009; + readonly t ActiveExitTimestamp = 0; + readonly t ActiveExitTimestampMonotonic = 0; + readonly t InactiveEnterTimestamp = 0; + readonly t InactiveEnterTimestampMonotonic = 0; + readonly b CanStart = true; + readonly b CanStop = true; + readonly b CanReload = true; + readonly b CanIsolate = false; + readonly (uo) Job = (0, '/org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice'); + readonly b StopWhenUnneeded = false; + readonly b RefuseManualStart = false; + readonly b RefuseManualStop = false; + readonly b AllowIsolate = false; + readonly b DefaultDependencies = true; + readonly b OnFailureIsolate = false; + readonly b IgnoreOnIsolate = false; + readonly b IgnoreOnSnapshot = false; + readonly b NeedDaemonReload = false; + readonly t JobTimeoutUSec = 0; + readonly t ConditionTimestamp = 1368576738557978; + readonly t ConditionTimestampMonotonic = 22559674; + readonly b ConditionResult = true; + readonly a(sbbsi) Conditions = [('ConditionVirtualization, false, false, 'no', 1)]; + readonly (ss) LoadError = ('', ''); + readonly b Transient = false; + }; + interface org.freedesktop.systemd1.Service { + ... + }; + interface org.freedesktop.DBus.Properties { + ... + }; + interface org.freedesktop.DBus.Peer { + ... + }; + interface org.freedesktop.DBus.Introspectable { + ... + }; +}; + + + + Methods + + Start(), Stop(), Reload(), + Restart(), TryRestart(), + ReloadOrRestart(), ReloadOrTryRestart(), + Kill(), ResetFailed(), and + SetProperties() implement the same operation as the respective method calls on the + Manager object (see above), however operate on the unit object and hence + do not take a unit name parameter. Invoking the methods directly on the Manager object has the + advantage of not requiring a GetUnit() call to get the unit object for a specific + unit name. Calling the methods on the Manager object is hence a round trip optimization. + + + + Properties + + Id contains the primary name of the unit. + + Names contains all names of the unit, including the primary name that is also + exposed in Id. + + Following either contains the empty string or contains the name of another + unit that this unit follows in state. This is used for some device units which reflect the unit state + machine of another unit, and which other unit this is might possibly change. + + Requires, RequiresOverridable, + Requisite, RequisiteOverridable, Wants, + BindsTo, RequiredBy, RequiredByOverridable, + WantedBy, BoundBy, Conflicts, + ConflictedBy, Before, After, + OnFailure, Triggers, TriggeredBy, + PropagatesReloadTo, RequiresMountsFor contain arrays which encode + the dependencies and their inverse dependencies (where this applies), as configured in the unit file or + determined automatically. + + Description contains the human readable description string for the + unit. + + SourcePath contains the path to a configuration file this unit is + automatically generated from in case it is not a native unit (in which case it contains the empty + string). For example, all mount units generated from /etc/fstab have this field + set to this value. + + Documentation contains a string array with URLs of documentation for this + unit. + + LoadState contains a state value that reflects whether the configuration file + of this unit has been loaded. The following states are currently defined: loaded, + error, masked. loaded indicates that the + configuration was successfully loaded. error indicates that the configuration failed + to load, the LoadError field (see below) contains information about the cause of + this failure. masked indicates that the unit is currently masked out (i.e. symlinked + to /dev/null or empty). Note that the LoadState is fully + orthogonal to the ActiveState (see below) as units without valid loaded + configuration might be active (because configuration might have been reloaded at a time where a unit + was already active). + + ActiveState contains a state value that reflects whether the unit is currently + active or not. The following states are currently defined: active, + reloading, inactive, failed, + activating, deactivating. active indicates + that unit is active (obviously...). reloading indicates that the unit is active and + currently reloading its configuration. inactive indicates that it is inactive and + the previous run was successful or no previous run has taken place yet. failed + indicates that it is inactive and the previous run was not successful (more information about the + reason for this is available on the unit type specific interfaces, for example for services in the + Result property, see below). activating indicates that the unit + has previously been inactive but is currently in the process of entering an active state. Conversely + deactivating indicates that the unit is currently in the process of + deactivation. + + SubState encodes states of the same state machine that + ActiveState covers, but knows more fine-grained states that are + unit-type-specific. Where ActiveState only covers six high-level states, + SubState covers possibly many more low-level unit-type-specific states that are + mapped to the six high-level states. Note that multiple low-level states might map to the same + high-level state, but not vice versa. Not all high-level states have low-level counterparts on all unit + types. At this point the low-level states are not documented here, and are more likely to be extended + later on than the common high-level states explained above. + + FragmentPath contains the unit file path this unit was read from, if there is + any (if not this contains the empty string). + + UnitFileState encodes the install state of the unit file of + FragmentPath. It currently knows the following states: enabled, + enabled-runtime, linked, linked-runtime, + masked, masked-runtime, static, + disabled, invalid. enabled indicates that a + unit file is permanently enabled. enable-runtime indicates the unit file is only + temporarily enabled, and will no longer be enabled after a reboot (that means, it is enabled via + /run symlinks, rather than /etc). linked + indicates that a unit is linked into /etc permanently, linked + indicates that a unit is linked into /run temporarily (until the next + reboot). masked indicates that the unit file is masked permanently, + masked-runtime indicates that it is only temporarily masked in + /run, until the next reboot. static indicates that the unit is + statically enabled, i.e. always enabled and doesn't need to be enabled + explicitly. invalid indicates that it could not be determined whether the unit file + is enabled. + + InactiveExitTimestamp, InactiveExitTimestampMonotonic, + ActiveEnterTimestamp, ActiveEnterTimestampMonotonic, + ActiveExitTimestamp, ActiveExitTimestampMonotonic, + InactiveEnterTimestamp, InactiveEnterTimestampMonotonic contain + CLOCK_REALTIME and CLOCK_MONOTONIC 64-bit microsecond + timestamps of the last time a unit left the inactive state, entered the active state, exited the active + state, or entered an inactive state. These are the points in time where the unit transitioned + inactive/failed → activating, + activating → active, active → + deactivating, and finally deactivating → + inactive/failed. The fields are 0 in case such a transition has + not been recording on this boot yet. + + CanStart, CanStop, CanReload encodes as + booleans whether the unit supports the start, stop or reload operations. Even if a unit supports such + an operation the client might not necessary have the right privileges to execute them. + + CanIsolate encodes as boolean whether the unit may be started in isolation + mode. + + Job encodes the job ID and job object path of the job currently scheduled or + executed for this unit, if there is any. If no job is scheduled or executed the job id field will be + 0. + + StopWhenUnneeded, RefuseManualStart, + RefuseManualStop, AllowIsolate, + DefaultDependencies, OnFailureIsolate, + IgnoreOnIsolate, IgnoreOnSnapshot map directly to the + corresponding configuration booleans in the unit file. + + DefaultControlGroup contains the main control group of this unit as a + string. This refers to a group in systemd's own name=systemd hierarchy, which + systemd uses to watch and manipulate the unit and all its processes. + + NeedDaemonReload is a boolean that indicates whether the configuration file + this unit is loaded from (i.e. FragmentPath or SourcePath) has + changed since the configuration was read and hence whether a configuration reload is + recommended. + + JobTimeoutUSec maps directly to the corresponding configuration setting in the + unit file. + + ConditionTimestamp and ConditionTimestampMonotonic contain + the CLOCK_REALTIME/CLOCK_MONOTONIC microsecond timestamps of + the last time the configured conditions of the unit have been checked, or 0 if they have never been + checked. Conditions are checked when a unit is requested to start. + + ConditionResult contains the condition result of the last time the configured + conditions of this unit were checked. + + Conditions contains all configured conditions of the unit. For each condition + five fields are given: condition type (e.g. ConditionPathExists), whether the + condition is a trigger condition, whether the condition is reversed, the right hand side of the + condtion (e.g. the path in case of ConditionPathExists), and the status. The status + can be 0, in which case the condition hasn't been checked yet, a positive value, in which case the + condition passed, or a negative value, in which case the condition failed. Currently only 0, +1, and -1 + are used, but additional values may be used in the future, retaining the meaning of + zero/positive/negative values + + LoadError contains a pair of strings. If the unit failed to load (as encoded + in LoadState, see above), then this will include a D-Bus error pair consisting of + the error ID and an explanatory human readable string of what happened. If it succeeded to load this + will be a pair of empty strings. + + Transient contains a boolean that indicates whether the unit was created as + transient unit (i.e. via CreateTransientUnit() on the manager object) + + + + + Service Unit Objects + + All service unit objects implement the + org.freedesktop.systemd1.Service interface (described here) in addition to + the generic org.freedesktop.systemd1.Unit interface (see above). + + +$ gdbus introspect --system --dest org.freedesktop.systemd1 \ + --object-path /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice + + interface org.freedesktop.systemd1.Unit { + ... + }; + interface org.freedesktop.systemd1.Service { + methods: + signals: + properties: + readonly s Type = 'dbus'; + readonly s Restart = 'no'; + readonly s PIDFile = ''; + readonly s NotifyAccess = 'main'; + readonly t RestartUSec = 100000; + readonly t TimeoutUSec = 90000000; + readonly t WatchdogUSec = 0; + readonly t WatchdogTimestamp = 0; + readonly t WatchdogTimestampMonotonic = 0; + readonly t StartLimitInterval = 10000000; + readonly u StartLimitBurst = 5; + readwrite s StartLimitAction = 'none + readonly s Slice = 'system.slice'; + readonly s ControlGroup = '/system.slice/avahi-daemon.service'; + readonly a(sasbttuii) ExecStartPre = []; + readonly a(sasbttuii) ExecStart = [('/usr/sbin/avahi-daemon', ['/usr/sbin/avahi-daemon', '-s'], false, 0, 0, 0, 0, 0, 0, 0)]; + readonly a(sasbttuii) ExecStartPost = []; + readonly a(sasbttuii) ExecReload = [('/usr/sbin/avahi-daemon', ['/usr/sbin/avahi-daemon', '-r'], false, 0, 0, 0, 0, 0, 0, 0)]; + readonly a(sasbttuii) ExecStop = []; + readonly a(sasbttuii) ExecStopPost = []; + readonly as Environment = []; + readonly a(sb) EnvironmentFiles = []; + readonly u UMask = 18; + readonly t LimitCPU = 18446744073709551615; + readonly t LimitFSIZE = 18446744073709551615; + readonly t LimitDATA = 18446744073709551615; + readonly t LimitSTACK = 18446744073709551615; + readonly t LimitCORE = 18446744073709551615; + readonly t LimitRSS = 18446744073709551615; + readonly t LimitNOFILE = 4096; + readonly t LimitAS = 18446744073709551615; + readonly t LimitNPROC = 256963; + readonly t LimitMEMLOCK = 65536; + readonly t LimitLOCKS = 18446744073709551615; + readonly t LimitSIGPENDING = 256963; + readonly t LimitMSGQUEUE = 819200; + readonly t LimitNICE = 0; + readonly t LimitRTPRIO = 0; + readonly t LimitRTTIME = 18446744073709551615; + readonly s WorkingDirectory = ''; + readonly s RootDirectory = ''; + readonly i OOMScoreAdjust = 0; + readonly i Nice = 0; + readonly i IOScheduling = 0; + readonly i CPUSchedulingPolicy = 0; + readonly i CPUSchedulingPriority = 0; + readonly ay CPUAffinity = []; + readonly t TimerSlackNSec = 50000; + readonly b CPUSchedulingResetOnFork = false; + readonly b NonBlocking = false; + readonly s StandardInput = 'null'; + readonly s StandardOutput = 'journal'; + readonly s StandardError = 'inherit'; + readonly s TTYPath = ''; + readonly b TTYReset = false; + readonly b TTYVHangup = false; + readonly b TTYVTDisallocate = false; + readonly i SyslogPriority = 30; + readonly s SyslogIdentifier = ''; + readonly b SyslogLevelPrefix = true; + readonly s Capabilities = ''; + readonly i SecureBits = 0; + readonly t CapabilityBoundingSet = 18446744073709551615; + readonly s User = ''; + readonly s Group = ''; + readonly as SupplementaryGroups = []; + readonly s TCPWrapName = ''; + readonly s PAMName = ''; + readonly as ReadWriteDirectories = []; + readonly as ReadOnlyDirectories = []; + readonly as InaccessibleDirectories = []; + readonly t MountFlags = 0; + readonly b PrivateTmp = false; + readonly b PrivateNetwork = false; + readonly b SameProcessGroup = false; + readonly s UtmpIdentifier = ''; + readonly b IgnoreSIGPIPE = true; + readonly b NoNewPrivileges = false; + readonly au SystemCallFilter = []; + readonly s KillMode = 'control-group'; + readonly i KillSignal = 15; + readonly b SendSIGKILL = true; + readonly b SendSIGHUP = false; + readonly b CPUAccounting = false; + readonly t CPUShares = 1024; + readonly b BlockIOAccounting = false; + readonly t BlockIOWeight = 1000; + readonly a(st) BlockIODeviceWeight = []; + readonly a(st) BlockIOReadBandwidth=; + readonly a(st) BlockIOWriteBandwidth=; + readonly b MemoryAccounting = false; + readonly t MemoryLimit = 18446744073709551615; + readonly s DevicePolicy = 'auto'; + readonly a(ss) DeviceAllow = []; + readonly b PermissionsStartOnly = false; + readonly b RootDirectoryStartOnly = false; + readonly b RemainAfterExit = false; + readonly t ExecMainStartTimestamp = 1368576738559537; + readonly t ExecMainStartTimestampMonotonic = 22561233; + readonly t ExecMainExitTimestamp = 1368576738559537; + readonly t ExecMainExitTimestampMonotonic = 22561233; + readonly u ExecMainPID = 666; + readonly i ExecMainCode = 0; + readonly i ExecMainStatus = 0; + readonly u MainPID = 666; + readonly u ControlPID = 0; + readonly s BusName = 'org.freedesktop.Avahi'; + readonly s StatusText = 'Server startup complete. Host name is fedora.local. Local service cookie is 2431121142.'; + readonly s Result = 'success'; + }; + interface org.freedesktop.DBus.Properties { + ... + }; + interface org.freedesktop.DBus.Peer { + ... + }; + interface org.freedesktop.DBus.Introspectable { + ... + }; +}; + + + + Properties + + Most properties of the Service interface map directly to the corresponding settings in service + unit files. For the sake of brevity, here's a list of all exceptions only: + + WatchdogTimestamp and WatchdogTimestampMonotonic contain + CLOCK_REALTIME/CLOCK_MONOTONIC microsecond timestamps of the + last watchdog ping received from the service, or 0 if none was ever received. + + ExecStartPre, ExecStart, ExecStartPost, + ExecReload, ExecStop, ExecStop each are arrays + of structures each containing: the binary path to execute; an array with all arguments to pass to the + executed command, starting with argument 0; a boolean whether it should be considered a failure if the + process exits uncleanly; two pairs of + CLOCK_REALTIME/CLOCK_MONOTONIC microsecond timestamps when + the process began and finished running the last time, or 0 if it never ran or never finished running; + the PID of the process, or 0 if it has not run yet; the exit code and status of the last run. This + field hence maps more or less to the corresponding setting in the service unit file but is augmented + with runtime data. + + LimitCPU (and related properties) map more or less directly to the + corresponding settings in the service unit files, however are set to 18446744073709551615 (i.e. -1) if + they aren't set. + + Capabilities contains the configured capabilities, as formatted with + cap_to_text3. + + + SecureBits, CapabilityBoundingSet, + MountFlags also correspond to the configured settings of the unit files, but are + encoded as the actual binary flag fields they are, rather than formatted as string. + + ExecMainStartTimestamp, ExecMainStartTimestampMonotonic, + ExecMainExitTimestamp, ExecMainExitTimestampMonotonic, + ExecMainPID, ExecMainCode, ExecMainStatus + contain information about the main process of the service as far as it is known. This is often the same + runtime information that is stored in ExecStart. However, it deviates for + Type=forking services where the main process of the service is not forked off + systemd directly. These fields either contain information of the last run of the process or of the + current running process. + + MainPID and ControlPID contain the main and control PID of + the service. The main PID is the current main PID of the service and is 0 when the service currently + has no main PID. The control PID is the PID of the current start/stop/reload process running and is 0 + if no such process is currently running. That means that ExecMainPID and + MainPID differ in the way that the latter immediately reflects whether a main + process is currently running while the latter possible contains information collected from the last run + even if the process is no longer around. + + StatusText contains the status text passed to the service manager via a call + to + sd_notify3. + This may be used by services to inform the service manager about its internal state with a nice + explanatory string. + + Result encodes the execution result of the last run of the service. It is + useful to determine the reason a service failed if it is in failed state (see + ActiveState above). The following values are currently known: + success is set if the unit didn't fail. resources indicates that + not enough resources have been available to fork off and execute the service + processes. timeout indicates that a time-out occurred while executing a service + operation. exit-code indicates that a service process exited with an unclean exit + code. signal indicates that a service process exited with an uncaught + signal. core-dump indicates that a service process exited uncleanly and dumped + core. watchdog indicates that a service did not send out watchdog ping messages + often enough. start-limit indicates that a service has been started too frequently + in a time frame (as configured in StartLimitInterval, + StartLimitBurst). + + ControlGroup indicates the control group path the processes of this service + unit are placed in. + + + + + Socket Unit Objects + + +$ gdbus introspect --system --dest org.freedesktop.systemd1 \ + --object-path /org/freedesktop/systemd1/unit/avahi_2ddaemon_2esocket + +node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2esocket { + interface org.freedesktop.systemd1.Unit { + ... + }; + interface org.freedesktop.systemd1.Socket { + methods: + signals: + properties: + readonly b BindIPv6Only = 'default'; + readonly u Backlog = 128; + readonly t TimeoutUSec = 90000000; + readonly s Slice = 'system.slice'; + readonly s ControlGroup = '/system.slice/avahi-daemon.socket'; + readonly a(sasbttuii) ExecStartPre = []; + readonly a(sasbttuii) ExecStartPost = []; + readonly a(sasbttuii) ExecStopPre = []; + readonly a(sasbttuii) ExecStopPost = []; + readonly as Environment = []; + readonly a(sb) EnvironmentFiles = []; + readonly u UMask = 18; + readonly t LimitCPU = 18446744073709551615; + readonly t LimitFSIZE = 18446744073709551615; + readonly t LimitDATA = 18446744073709551615; + readonly t LimitSTACK = 18446744073709551615; + readonly t LimitCORE = 18446744073709551615; + readonly t LimitRSS = 18446744073709551615; + readonly t LimitNOFILE = 4096; + readonly t LimitAS = 18446744073709551615; + readonly t LimitNPROC = 61434; + readonly t LimitMEMLOCK = 65536; + readonly t LimitLOCKS = 18446744073709551615; + readonly t LimitSIGPENDING = 61434; + readonly t LimitMSGQUEUE = 819200; + readonly t LimitNICE = 0; + readonly t LimitRTPRIO = 0; + readonly t LimitRTTIME = 18446744073709551615; + readonly s WorkingDirectory = ''; + readonly s RootDirectory = ''; + readonly i OOMScoreAdjust = 0; + readonly i Nice = 0; + readonly i IOScheduling = 0; + readonly i CPUSchedulingPolicy = 0; + readonly i CPUSchedulingPriority = 0; + readonly ay CPUAffinity = []; + readonly t TimerSlackNSec = 50000; + readonly b CPUSchedulingResetOnFork = false; + readonly b NonBlocking = false; + readonly s StandardInput = 'null'; + readonly s StandardOutput = 'journal'; + readonly s StandardError = 'inherit'; + readonly s TTYPath = ''; + readonly b TTYReset = false; + readonly b TTYVHangup = false; + readonly b TTYVTDisallocate = false; + readonly i SyslogPriority = 30; + readonly s SyslogIdentifier = ''; + readonly b SyslogLevelPrefix = true; + readonly s Capabilities = ''; + readonly i SecureBits = 0; + readonly t CapabilityBoundingSet = 18446744073709551615; + readonly s User = ''; + readonly s Group = ''; + readonly as SupplementaryGroups = []; + readonly s TCPWrapName = ''; + readonly s PAMName = ''; + readonly as ReadWriteDirectories = []; + readonly as ReadOnlyDirectories = []; + readonly as InaccessibleDirectories = []; + readonly t MountFlags = 0; + readonly b PrivateTmp = false; + readonly b PrivateNetwork = false; + readonly b SameProcessGroup = false; + readonly s UtmpIdentifier = ''; + readonly b IgnoreSIGPIPE = true; + readonly b NoNewPrivileges = false; + readonly au SystemCallFilter = []; + readonly s KillMode = 'control-group'; + readonly i KillSignal = 15; + readonly b SendSIGKILL = true; + readonly b SendSIGHUP = false; + readonly b CPUAccounting = false; + readonly t CPUShares = 1024; + readonly b BlockIOAccounting = false; + readonly t BlockIOWeight = 1000; + readonly a(st) BlockIODeviceWeight = []; + readonly a(st) BlockIOReadBandwidth=; + readonly a(st) BlockIOWriteBandwidth=; + readonly b MemoryAccounting = false; + readonly t MemoryLimit = 18446744073709551615; + readonly s DevicePolicy = 'auto'; + readonly a(ss) DeviceAllow = []; + readonly u ControlPID = 0; + readonly s BindToDevice = ''; + readonly u DirectoryMode = 493; + readonly u SocketMode = 438; + readonly b Accept = false; + readonly b KeepAlive = false; + readonly i Priority = -1; + readonly t ReceiveBuffer = 0; + readonly t SendBuffer = 0; + readonly i IPTOS = -1; + readonly i IPTTL = -1; + readonly t PipeSize = 0; + readonly b FreeBind = false; + readonly b Transparent = false; + readonly b Broadcast = false; + readonly b PassCredentials = false; + readonly b PassSecurity = false; + readonly i Mark = -1; + readonly u MaxConnections = 64; + readonly u NAccepted = 0; + readonly u NConnections = 0; + readonly x MessageQueueMaxMessages = 0; + readonly x MessageQueueMessageSize = 0; + readonly a(ss) Listen = [('Stream', '/var/run/avahi-daemon/socket')]; + readonly s Result = 'success'; + readonly b ReusePort = false; + readonly s SmackLabel = ''; + readonly s SmackLabelIPIn = ''; + readonly s SmackLabelIPOut = ''; + }; + interface org.freedesktop.DBus.Properties { + ... + }; + interface org.freedesktop.DBus.Peer { + ... + }; + interface org.freedesktop.DBus.Introspectable { + ... + }; +}; + + + + Properties + + Most of the properties map directly to the corresponding settings in socket unit files. As socket + units can include ExecStartPre (and similar) fields which contain information about + processes to execute. They also share most of the fields related to the execution context that Service + objects expose (see above). + + In addition to these properties there are the following: + + NAccepted contains the accumulated number of connections ever accepted on this + socket. This only applies to sockets with Accept set to true, + i.e. those where systemd is responsible for accepted connections. + + Similarly NConnections contains the number of currently open connections on + this socket, and also applies only to socket with Accept set to + true. + + Result encodes the reason why a socket unit failed if it is in + failed state (see ActiveState above). The values + success, resources, timeout, + exit-code, signal and core-dump have the same + meaning as they have for the corresponding field of service units (see above). In addition to that the + value service-failed-permanent indicates that the service of this socket failed + continuously. + + + + + Target Unit Objects + + +$ gdbus introspect --system --dest org.freedesktop.systemd1 \ + --object-path /org/freedesktop/systemd1/unit/basic_2etarget + +node /org/freedesktop/systemd1/unit/basic_2etarget { + interface org.freedesktop.systemd1.Unit { + ... + }; + interface org.freedesktop.systemd1.Target { + methods: + signals: + properties: + }; + interface org.freedesktop.DBus.Properties { + ... + }; + interface org.freedesktop.DBus.Peer { + ... + }; + interface org.freedesktop.DBus.Introspectable { + ... + }; +}; + + + Target units have neither type-specific methods nor properties. + + + + + Device Unit Objects + + All device unit objects implement the org.freedesktop.systemd1.Device interface (described here) + in addition to the generic org.freedesktop.systemd1.Unit interface (see above). + + +$ gdbus introspect --system --dest org.freedesktop.systemd1 \ + --object-path /org/freedesktop/systemd1/unit/dev_2ddisk_2dby_5cx2did_2data_5cx2dSAMSUNG_5fHD501LJ_5fS0MUJ1KQ161445_2edevice + +node /org/freedesktop/systemd1/unit/dev_2ddisk_2dby_5cx2did_2data_5cx2dSAMSUNG_5fHD501LJ_5fS0MUJ1KQ161445_2edevice { + interface org.freedesktop.systemd1.Unit { + ... + }; + interface org.freedesktop.systemd1.Device { + methods: + signals: + properties: + readonly s SysFSPath = '/sys/devices/pci0000:00/0000:00:1f.2/ata2/host1/target1:0:0/1:0:0:0/block/sdb'; + }; + interface org.freedesktop.DBus.Properties { + ... + }; + interface org.freedesktop.DBus.Peer { + ... + }; + interface org.freedesktop.DBus.Introspectable { + ... + }; +}; + + + + Properties + + Device units only expose a single type-specific property: + + SysFSPath contains the sysfs path of the kernel device this object corresponds + to. + + + + + + Mount Unit Objects + + All mount unit objects implement the org.freedesktop.systemd1.Mount + interface (described here) in addition to the generic + org.freedesktop.systemd1.Unit interface (see above) + + +$ gdbus introspect --system --dest org.freedesktop.systemd1 \ + --object-path /org/freedesktop/systemd1/unit/home_2emount + +node /org/freedesktop/systemd1/unit/home_2emount { + interface org.freedesktop.systemd1.Unit { + ... + }; + interface org.freedesktop.systemd1.Mount { + methods: + signals: + properties: + readonly s Where = '/home'; + readonly s What = '/dev/mapper/home'; + readonly s Options = 'rw,relatime,rw,seclabel,data=ordered'; + readonly s Type = 'ext4'; + readonly t TimeoutUSec = 90000000; + readonly s Slice = 'system.slice'; + readonly s ControlGroup = '/system.slice/home.mount'; + readonly a(sasbttuii) ExecMount = [('/bin/mount', ['/bin/mount', '/dev/disk/by-uuid/59a54df8-d070-4907-a4a7-2e0ce05d5c2a', '/home', '-t', 'ext4'], false, 1357656124168977, 11158027, 1357656124274805, 11263855, 608, 1, 0)]; + readonly a(sasbttuii) ExecUnmount = []; + readonly a(sasbttuii) ExecRemount = []; + readonly as Environment = []; + readonly a(sb) EnvironmentFiles = []; + readonly u UMask = 18; + readonly t LimitCPU = 18446744073709551615; + readonly t LimitFSIZE = 18446744073709551615; + readonly t LimitDATA = 18446744073709551615; + readonly t LimitSTACK = 18446744073709551615; + readonly t LimitCORE = 18446744073709551615; + readonly t LimitRSS = 18446744073709551615; + readonly t LimitNOFILE = 4096; + readonly t LimitAS = 18446744073709551615; + readonly t LimitNPROC = 61434; + readonly t LimitMEMLOCK = 65536; + readonly t LimitLOCKS = 18446744073709551615; + readonly t LimitSIGPENDING = 61434; + readonly t LimitMSGQUEUE = 819200; + readonly t LimitNICE = 0; + readonly t LimitRTPRIO = 0; + readonly t LimitRTTIME = 18446744073709551615; + readonly s WorkingDirectory = ''; + readonly s RootDirectory = ''; + readonly i OOMScoreAdjust = 0; + readonly i Nice = 0; + readonly i IOScheduling = 0; + readonly i CPUSchedulingPolicy = 0; + readonly i CPUSchedulingPriority = 0; + readonly ay CPUAffinity = []; + readonly t TimerSlackNSec = 50000; + readonly b CPUSchedulingResetOnFork = false; + readonly b NonBlocking = false; + readonly s StandardInput = 'null'; + readonly s StandardOutput = 'journal'; + readonly s StandardError = 'inherit'; + readonly s TTYPath = ''; + readonly b TTYReset = false; + readonly b TTYVHangup = false; + readonly b TTYVTDisallocate = false; + readonly i SyslogPriority = 30; + readonly s SyslogIdentifier = ''; + readonly b SyslogLevelPrefix = true; + readonly s Capabilities = ''; + readonly i SecureBits = 0; + readonly t CapabilityBoundingSet = 18446744073709551615; + readonly s User = ''; + readonly s Group = ''; + readonly as SupplementaryGroups = []; + readonly s TCPWrapName = ''; + readonly s PAMName = ''; + readonly as ReadWriteDirectories = []; + readonly as ReadOnlyDirectories = []; + readonly as InaccessibleDirectories = []; + readonly t MountFlags = 0; + readonly b PrivateTmp = false; + readonly b PrivateNetwork = false; + readonly b SameProcessGroup = true; + readonly s UtmpIdentifier = ''; + readonly b IgnoreSIGPIPE = true; + readonly b NoNewPrivileges = false; + readonly au SystemCallFilter = []; + readonly s KillMode = 'control-group'; + readonly i KillSignal = 15; + readonly b SendSIGKILL = true; + readonly b SendSIGHUP = false; + readonly b CPUAccounting = false; + readonly t CPUShares = 1024; + readonly b BlockIOAccounting = false; + readonly t BlockIOWeight = 1000; + readonly a(st) BlockIODeviceWeight = []; + readonly a(st) BlockIOReadBandwidth=; + readonly a(st) BlockIOWriteBandwidth=; + readonly b MemoryAccounting = false; + readonly t MemoryLimit = 18446744073709551615; + readonly s DevicePolicy = 'auto'; + readonly a(ss) DeviceAllow = []; + readonly u ControlPID = 0; + readonly u DirectoryMode = 493; + readonly s Result = 'success'; + }; + interface org.freedesktop.DBus.Properties { + ... + }; + interface org.freedesktop.DBus.Peer { + ... + }; + interface org.freedesktop.DBus.Introspectable { + ... + }; +}; + + + + Properties + + Most of the properties map directly to the corresponding settings in mount unit files. As mount + units invoke the /usr/bin/mount command their bus objects include implicit + ExecMount (and similar) fields which contain information about processes to + execute. They also share most of the fields related to the execution context that Service objects + expose (see above). In addition to these properties there are the following: + + ControlPID contains the PID of the currently running + /usr/bin/mount or /usr/bin/umount command if there is one + running, otherwise 0. + + Result contains a value explaining why a mount unit failed if it failed. It + can take the values success, resources, + timeout, exit-code, signal, + core-dump which have the identical meaning as the corresponding values of the + corresponding field of service unit objects (see above). + + + + + Automount Unit Objects + + All automount unit objects implement the + org.freedesktop.systemd1.Automount interface (described here) in addition + to the generic org.freedesktop.systemd1.Unit interface (see above). + + +$ gdbus introspect --system --dest org.freedesktop.systemd1 \ + --object-path /org/freedesktop/systemd1/unit/proc_2dsys_2dfs_2dbinfmt_5fmisc_2eautomount + +node /org/freedesktop/systemd1/unit/proc_2dsys_2dfs_2dbinfmt_5fmisc_2eautomount { + interface org.freedesktop.systemd1.Unit { + ... + }; + interface org.freedesktop.systemd1.Automount { + methods: + signals: + properties: + readonly s Where = '/proc/sys/fs/binfmt_misc'; + readonly u DirectoryMode = 493; + readonly s Result = 'success'; + }; + interface org.freedesktop.DBus.Properties { + ... + }; + interface org.freedesktop.DBus.Peer { + ... + }; + interface org.freedesktop.DBus.Introspectable { + ... + }; +}; + + + + Properties + + Most of the properties map directly to the corresponding settings in the automount unit + files. + + Result knows the values success and + resources, at this time. They have the same meanings as the corresponding values of + the corresponding field of the Service object. + + + + + + Timer Unit Objects + + All timer unit objects implement the org.freedesktop.systemd1.Timer + interface (described here) in addition to the generic + org.freedesktop.systemd1.Unit interface (see above). + + +$ gdbus introspect --system --dest org.freedesktop.systemd1 \ + --object-path /org/freedesktop/systemd1/unit/systemd_2dtmpfiles_2dclean_2etimer + +node /org/freedesktop/systemd1/unit/systemd_2dtmpfiles_2dclean_2etimer { + interface org.freedesktop.systemd1.Unit { + ... + }; + interface org.freedesktop.systemd1.Timer { + readonly s Unit = 'systemd-tmpfiles-clean.service'; + readonly a(stt) TimersMonotonic = [('OnUnitActiveUSec', 86400000000, 173700033104), ('OnBootUSec', 900000000, 900000000)]; + readonly a(sst) TimersCalendar = []; + readonly t NextElapseUSecRealtime = 0; + readonly t NextElapseUSecMonotonic = 173700033104; + readonly s Result = 'success'; + }; + interface org.freedesktop.DBus.Properties { + ... + }; + interface org.freedesktop.DBus.Peer { + ... + }; + interface org.freedesktop.DBus.Introspectable { + ... + }; +}; + + + + Properties + + Unit contains the name of the unit to activate when the timer elapses. + + TimersMonotonic contains an array of structs that contain information about + all monotonic timers of this timer unit. The structs contain a string identifying the timer base, which + is one of OnActiveUSec, OnBootUSec, + OnStartupUSec, OnUnitActiveUSec, + OnUnitInactiveUSec, which correspond to the settings of the same names in the timer + unit files; the microsecond offset from this timer base in monotonic time; the next elapsation point on + the CLOCK_MONOTONIC clock, relative its epoch. + + TimersCalendar contains an array of structs that contain information about all + realtime/calendar timers of this timer unit. The structs contain a string identifying the timer base, + which may only be OnCalendar for now; the calendar specification string; the next + elapsation point on the CLOCK_REALTIME clock, relative to its epoch. + + NextElapseUSecRealtime contains the next elapsation point on the + CLOCK_REALTIME clock in miscroseconds since the epoch, or 0 if this timer event + does not include at least one calendar event. + + Similarly, NextElapseUSecMonotonic contains the next elapsation point on the + CLOCK_MONOTONIC clock in microseconds since the epoch, or 0 if this timer event + does not include at least one monotonic event. + + Result knows the values success and + resources with the same meanings as the matching values of the corresponding + property of the service interface. + + + + + Swap Unit Objects + + All swap unit objects implement the org.freedesktop.systemd1.Swap + interface (described here) in addition to the generic + org.freedesktop.systemd1.Unit interface (see above). + + +$ gdbus introspect --system --dest org.freedesktop.systemd1 \ + --object-path /org/freedesktop/systemd1/unit/dev_2dsda3_2eswap + +node /org/freedesktop/systemd1/unit/dev_2dsda3_2eswap { + interface org.freedesktop.systemd1.Unit { + ... + }; + interface org.freedesktop.systemd1.Swap { + methods: + signals: + properties: + readonly s What = '/dev/sda3'; + readonly i Priority = -1; + readonly t TimeoutUSec = 90000000; + readonly s Slice = 'system.slice'; + readonly s ControlGroup = ''; + readonly a(sasbttuii) ExecActivate = []; + readonly a(sasbttuii) ExecDeactivate = []; + readonly as Environment = []; + readonly a(sb) EnvironmentFiles = []; + readonly u UMask = 18; + readonly t LimitCPU = 18446744073709551615; + readonly t LimitFSIZE = 18446744073709551615; + readonly t LimitDATA = 18446744073709551615; + readonly t LimitSTACK = 18446744073709551615; + readonly t LimitCORE = 18446744073709551615; + readonly t LimitRSS = 18446744073709551615; + readonly t LimitNOFILE = 4096; + readonly t LimitAS = 18446744073709551615; + readonly t LimitNPROC = 61434; + readonly t LimitMEMLOCK = 65536; + readonly t LimitLOCKS = 18446744073709551615; + readonly t LimitSIGPENDING = 61434; + readonly t LimitMSGQUEUE = 819200; + readonly t LimitNICE = 0; + readonly t LimitRTPRIO = 0; + readonly t LimitRTTIME = 18446744073709551615; + readonly s WorkingDirectory = ''; + readonly s RootDirectory = ''; + readonly i OOMScoreAdjust = 0; + readonly i Nice = 0; + readonly i IOScheduling = 0; + readonly i CPUSchedulingPolicy = 0; + readonly i CPUSchedulingPriority = 0; + readonly ay CPUAffinity = []; + readonly t TimerSlackNS = 50000; + readonly b CPUSchedulingResetOnFork = false; + readonly b NonBlocking = false; + readonly s StandardInput = 'null'; + readonly s StandardOutput = 'journal'; + readonly s StandardError = 'inherit'; + readonly s TTYPath = ''; + readonly b TTYReset = false; + readonly b TTYVHangup = false; + readonly b TTYVTDisallocate = false; + readonly i SyslogPriority = 30; + readonly s SyslogIdentifier = ''; + readonly b SyslogLevelPrefix = true; + readonly s Capabilities = ''; + readonly i SecureBits = 0; + readonly t CapabilityBoundingSet = 18446744073709551615; + readonly s User = ''; + readonly s Group = ''; + readonly as SupplementaryGroups = []; + readonly s TCPWrapName = ''; + readonly s PAMName = ''; + readonly as ReadWriteDirectories = []; + readonly as ReadOnlyDirectories = []; + readonly as InaccessibleDirectories = []; + readonly t MountFlags = 0; + readonly b PrivateTmp = false; + readonly b PrivateNetwork = false; + readonly b SameProcessGroup = false; + readonly s KillMode = 'control-group'; + readonly i KillSignal = 15; + readonly s UtmpIdentifier = ''; + readonly b IgnoreSIGPIPE = true; + readonly b NoNewPrivileges = false; + readonly au SystemCallFilter = []; + readonly s KillMode = 'control-group'; + readonly i KillSignal = 15; + readonly b SendSIGKILL = true; + readonly b SendSIGHUP = false; + readonly b CPUAccounting = false; + readonly t CPUShares = 1024; + readonly b BlockIOAccounting = false; + readonly t BlockIOWeight = 1000; + readonly a(st) BlockIODeviceWeight = []; + readonly a(st) BlockIOReadBandwidth=; + readonly a(st) BlockIOWriteBandwidth=; + readonly b MemoryAccounting = false; + readonly t MemoryLimit = 18446744073709551615; + readonly s DevicePolicy = 'auto'; + readonly a(ss) DeviceAllow = []; + readonly u ControlPID = 0; + readonly s Result = 'success'; + }; + interface org.freedesktop.DBus.Properties { + ... + }; + interface org.freedesktop.DBus.Peer { + ... + }; + interface org.freedesktop.DBus.Introspectable { + ... + }; +}; + + + + Properties + + Most of the properties map directly to the corresponding settings in swap unit files. As mount + units invoke the + swapon8 command + their bus objects include implicit ExecActivate (and similar) fields which contain + information about processes to execute. They also share most of the fields related to the execution + context that Service objects expose (see above). In addition to these properties there are the + following: + + ControlPID contains the PID of the currently running + swapon8 or + swapoff8 command if + there is one running, otherwise 0. + + Result contains a value explaining why a mount unit failed if it failed. It + can take the values success, resources, + timeout, exit-code, signal, + core-dump which have the identical meanings as the corresponding values of the + corresponding field of service unit objects (see above). + + + + + + Path Unit Objects + + +$ gdbus introspect --system --dest org.freedesktop.systemd1 \ + --object-path /org/freedesktop/systemd1/unit/cups_2epath + +node /org/freedesktop/systemd1/unit/cups_2epath { + interface org.freedesktop.systemd1.Unit { + ... + }; + interface org.freedesktop.systemd1.Path { + methods: + signals: + properties: + readonly s Unit = 'cups.service'; + readonly a(ss) Paths = [('PathExistsGlob', '/var/spool/cups/d*')]; + readonly b MakeDirectory = false; + readonly u DirectoryMode = 493; + readonly s Result = 'success'; + }; + interface org.freedesktop.DBus.Properties { + ... + }; + interface org.freedesktop.DBus.Peer { + ... + }; + interface org.freedesktop.DBus.Introspectable { + ... + }; +}; + + + + Properties + + Most properties correspond directly with the matching settings in path unit files. + + The others: + + Paths contains an array of structs. Each struct contains the condition to + watch, which can be one of PathExists, PathExistsGlob, + PathChanged, PathModified, DirectoryNotEmpty + which correspond directly to the matching settings in the path unit files; and the path to watch, + possibly including glob expressions. + + Result contains a result value which can be success or + resources, which have the same meaning as the corresponding field of the service + interface. + + + + + Slice Unit Objects + + All slice unit objects implement the org.freedesktop.systemd1.Slice + interface (described here) in addition to the generic + org.freedesktop.systemd1.Unit interface (see above). + + +$ gdbus introspect --system --dest org.freedesktop.systemd1 \ + --object-path /org/freedesktop/systemd1/unit/system_2eslice + +node /org/freedesktop/systemd1/unit/system_2eslice { + interface org.freedesktop.systemd1.Unit { + ... + }; + interface org.freedesktop.systemd1.Slice { + methods: + signals: + properties: + readonly s Slice = '-.slice'; + readonly s ControlGroup = '/system.slice'; + readonly b CPUAccounting = false; + readonly t CPUShares = 1024; + readonly b BlockIOAccounting = false; + readonly t BlockIOWeight = 1000; + readonly a(st) BlockIODeviceWeight = []; + readonly a(st) BlockIOReadBandwidth=; + readonly a(st) BlockIOWriteBandwidth=; + readonly b MemoryAccounting = false; + readonly t MemoryLimit = 18446744073709551615; + readonly s DevicePolicy = 'auto'; + readonly a(ss) DeviceAllow = []; + }; + interface org.freedesktop.DBus.Properties { + ... + }; + interface org.freedesktop.DBus.Peer { + ... + }; + interface org.freedesktop.DBus.Introspectable { + ... + }; +}; + + + + Properties + + Most properties correspond directly with the matching settings in slice unit files. + + + + + Scope Unit Objects + + All slice unit objects implement the org.freedesktop.systemd1.Scope + interface (described here) in addition to the generic + org.freedesktop.systemd1.Unit interface (see above). + + +$ gdbus introspect --system --dest org.freedesktop.systemd1 \ + --object-path /org/freedesktop/systemd1/unit/session_2d1_2escope + +node /org/freedesktop/systemd1/unit/session_2d1_2escope { + interface org.freedesktop.systemd1.Unit { + ... + }; + interface org.freedesktop.systemd1.Scope { + methods: + Abandon(); + signals: + RequestStop(); + properties: + readonly s Slice = 'user-1000.slice'; + readonly s ControlGroup = '/user.slice/user-1000.slice/session-1.scope'; + readonly t TimeoutStopUSec = 500000; + readonly s KillMode = 'none'; + readonly i KillSignal = 15; + readonly b SendSIGKILL = true; + readonly b SendSIGHUP = true; + readonly b CPUAccounting = false; + readonly t CPUShares = 1024; + readonly b BlockIOAccounting = false; + readonly t BlockIOWeight = 1000; + readonly a(st) BlockIODeviceWeight = []; + readonly a(st) BlockIOReadBandwidth=; + readonly a(st) BlockIOWriteBandwidth=; + readonly b MemoryAccounting = false; + readonly t MemoryLimit = 18446744073709551615; + readonly s DevicePolicy = 'auto'; + readonly a(ss) DeviceAllow = []; + readonly s Result = 'success'; + readonly s Controller = ''; + + + }; + interface org.freedesktop.DBus.Properties { + ... + }; + interface org.freedesktop.DBus.Peer { + ... + }; + interface org.freedesktop.DBus.Introspectable { + ... + }; +}; + + + + Methods + + Abandon() may be used to place a scope unit in the "abandoned" state. This + may be used to inform the system manager that the manager that created the scope lost interest in the + scope (for example, because it is terminating), without wanting to shut down the scope entirely + + + + Signals + + RequestStop is sent to the peer that is configured in the + Controller property when systemd is requested to terminate the scope unit. A program + registering a scope can use this to cleanly shut down the processes it added to the scope, instead of + letting systemd do it with the usual SIGTERM logic. + + + + Properties + + All properties correspond directly with the matching properties of service units + + Controller contains the bus name (unique or well-known) that is notified when + the scope unit is to be shut down via a RequestStop signal (see below). This is + set when the scope is created. If not set the scope's processes will terminated with + SIGTERM directly. + + + + + + Job Objects + + Job objects encapsulate scheduled or running jobs. Each unit can have none or one jobs in the + execution queue. Each job is attached to exactly one unit. + + +$ gdbus introspect --system --dest org.freedesktop.systemd1 \ + --object-path /org/freedesktop/systemd1/job/1292 + +node /org/freedesktop/systemd1/job/1292 { + interface org.freedesktop.systemd1.Job { + methods: + Cancel(); + signals: + properties: + readonly u Id = 1292; + readonly (so) Unit = ('slow.service', '/org/freedesktop/systemd1/unit/slow_2eservice'); + readonly s JobType = 'start'; + readonly s State = 'running'; + }; + interface org.freedesktop.DBus.Properties { + ... + }; + interface org.freedesktop.DBus.Peer { + ... + }; + interface org.freedesktop.DBus.Introspectable { + ... + }; +}; + + + + Methods + + Cancel() cancels the job. Note that this will remove a job from the queue if + it is not yet executed but generally will not cause a job that is already in the process of being + executed to be aborted. This operation may also be requested via the CancelJob() + method of the Manager object (see above), which is sometimes useful to reduce roundtrips. + + + + Properties + + Id is the numeric Id of the job. During the runtime of a systemd instance each + numeric ID is only assigned once. + + Unit refers to the unit this job belongs two. It is a structure consisting of + the name of the unit and a bus path to the unit's object. + + JobType refers to the job's type and is one of start, + verify-active, stop, reload, + restart, try-restart, reload-or-start. Note + that later versions might define additional values. + + State refers to the job's state and is one of waiting and + running. The former indicates that a job is currently queued but has not begun to + execute yet, the latter indicates that a job is currently being executed. + + + + + Versioning + + These D-Bus interfaces follow + the usual interface versioning guidelines. + + diff --git a/man/rules/meson.build b/man/rules/meson.build index 1552fe2d10..39a3172252 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -50,6 +50,7 @@ manpages = [ ['org.freedesktop.login1', '5', [], 'ENABLE_LOGIND'], ['org.freedesktop.machine1', '5', [], 'ENABLE_MACHINED'], ['org.freedesktop.resolve1', '5', [], 'ENABLE_RESOLVE'], + ['org.freedesktop.systemd1', '5', [], ''], ['org.freedesktop.timedate1', '5', [], 'ENABLE_TIMEDATED'], ['os-release', '5', [], ''], ['pam_systemd', '8', [], 'HAVE_PAM'], diff --git a/man/systemd.xml b/man/systemd.xml index f5e4a9526c..1534027d92 100644 --- a/man/systemd.xml +++ b/man/systemd.xml @@ -280,6 +280,9 @@ files or parameters passed on the kernel command line. For details, see systemd.generator7. + The D-Bus API of systemd is described in + org.freedesktop.systemd15. + Systems which invoke systemd in a container or initrd environment should implement the Container Interface or initrd Interface @@ -1252,6 +1255,7 @@ systemd-notify1, daemon7, sd-daemon3, + org.freedesktop.systemd15, systemd.unit5, systemd.special5, pkg-config1, From dad97f0425c0f7ae2a72531962092563f1a20c65 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 10 Apr 2020 12:50:21 +0200 Subject: [PATCH 16/26] manager: add dbus parameter names --- src/core/dbus-job.c | 16 +- src/core/dbus-manager.c | 640 +++++++++++++++++++++++++++++++++++----- src/core/dbus-unit.c | 130 +++++++- 3 files changed, 689 insertions(+), 97 deletions(-) diff --git a/src/core/dbus-job.c b/src/core/dbus-job.c index 6151326f72..0e952c8757 100644 --- a/src/core/dbus-job.c +++ b/src/core/dbus-job.c @@ -118,9 +118,21 @@ int bus_job_method_get_waiting_jobs(sd_bus_message *message, void *userdata, sd_ const sd_bus_vtable bus_job_vtable[] = { SD_BUS_VTABLE_START(0), + SD_BUS_METHOD("Cancel", NULL, NULL, bus_job_method_cancel, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetAfter", NULL, "a(usssoo)", bus_job_method_get_waiting_jobs, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetBefore", NULL, "a(usssoo)", bus_job_method_get_waiting_jobs, SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetAfter", + NULL,, + "a(usssoo)", + SD_BUS_PARAM(jobs), + bus_job_method_get_waiting_jobs, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetBefore", + NULL,, + "a(usssoo)", + SD_BUS_PARAM(jobs), + bus_job_method_get_waiting_jobs, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_PROPERTY("Id", "u", NULL, offsetof(Job, id), SD_BUS_VTABLE_PROPERTY_CONST), SD_BUS_PROPERTY("Unit", "(so)", property_get_unit, 0, SD_BUS_VTABLE_PROPERTY_CONST), SD_BUS_PROPERTY("JobType", "s", property_get_type, offsetof(Job, type), SD_BUS_VTABLE_PROPERTY_CONST), diff --git a/src/core/dbus-manager.c b/src/core/dbus-manager.c index 60f55aef5f..6faf26c9fc 100644 --- a/src/core/dbus-manager.c +++ b/src/core/dbus-manager.c @@ -2477,87 +2477,569 @@ const sd_bus_vtable bus_manager_vtable[] = { SD_BUS_PROPERTY("TimerSlackNSec", "t", property_get_timer_slack_nsec, 0, SD_BUS_VTABLE_PROPERTY_CONST), SD_BUS_PROPERTY("DefaultOOMPolicy", "s", bus_property_get_oom_policy, offsetof(Manager, default_oom_policy), SD_BUS_VTABLE_PROPERTY_CONST), - SD_BUS_METHOD("GetUnit", "s", "o", method_get_unit, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetUnitByPID", "u", "o", method_get_unit_by_pid, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetUnitByInvocationID", "ay", "o", method_get_unit_by_invocation_id, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetUnitByControlGroup", "s", "o", method_get_unit_by_control_group, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("LoadUnit", "s", "o", method_load_unit, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("StartUnit", "ss", "o", method_start_unit, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("StartUnitReplace", "sss", "o", method_start_unit_replace, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("StopUnit", "ss", "o", method_stop_unit, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ReloadUnit", "ss", "o", method_reload_unit, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("RestartUnit", "ss", "o", method_restart_unit, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("TryRestartUnit", "ss", "o", method_try_restart_unit, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ReloadOrRestartUnit", "ss", "o", method_reload_or_restart_unit, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ReloadOrTryRestartUnit", "ss", "o", method_reload_or_try_restart_unit, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("EnqueueUnitJob", "sss", "uososa(uosos)", method_enqueue_unit_job, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("KillUnit", "ssi", NULL, method_kill_unit, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("CleanUnit", "sas", NULL, method_clean_unit, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ResetFailedUnit", "s", NULL, method_reset_failed_unit, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetUnitProperties", "sba(sv)", NULL, method_set_unit_properties, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("RefUnit", "s", NULL, method_ref_unit, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("UnrefUnit", "s", NULL, method_unref_unit, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("StartTransientUnit", "ssa(sv)a(sa(sv))", "o", method_start_transient_unit, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetUnitProcesses", "s", "a(sus)", method_get_unit_processes, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("AttachProcessesToUnit", "ssau", NULL, method_attach_processes_to_unit, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("AbandonScope", "s", NULL, method_abandon_scope, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetJob", "u", "o", method_get_job, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetJobAfter", "u", "a(usssoo)", method_get_job_waiting, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetJobBefore", "u", "a(usssoo)", method_get_job_waiting, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("CancelJob", "u", NULL, method_cancel_job, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ClearJobs", NULL, NULL, method_clear_jobs, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ResetFailed", NULL, NULL, method_reset_failed, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ListUnits", NULL, "a(ssssssouso)", method_list_units, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ListUnitsFiltered", "as", "a(ssssssouso)", method_list_units_filtered, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ListUnitsByPatterns", "asas", "a(ssssssouso)", method_list_units_by_patterns, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ListUnitsByNames", "as", "a(ssssssouso)", method_list_units_by_names, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ListJobs", NULL, "a(usssoo)", method_list_jobs, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("Subscribe", NULL, NULL, method_subscribe, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("Unsubscribe", NULL, NULL, method_unsubscribe, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("Dump", NULL, "s", method_dump, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("DumpByFileDescriptor", NULL, "h", method_dump_by_fd, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("CreateSnapshot", "sb", "o", method_refuse_snapshot, SD_BUS_VTABLE_UNPRIVILEGED|SD_BUS_VTABLE_HIDDEN), - SD_BUS_METHOD("RemoveSnapshot", "s", NULL, method_refuse_snapshot, SD_BUS_VTABLE_UNPRIVILEGED|SD_BUS_VTABLE_HIDDEN), - SD_BUS_METHOD("Reload", NULL, NULL, method_reload, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("Reexecute", NULL, NULL, method_reexecute, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("Exit", NULL, NULL, method_exit, 0), - SD_BUS_METHOD("Reboot", NULL, NULL, method_reboot, SD_BUS_VTABLE_CAPABILITY(CAP_SYS_BOOT)), - SD_BUS_METHOD("PowerOff", NULL, NULL, method_poweroff, SD_BUS_VTABLE_CAPABILITY(CAP_SYS_BOOT)), - SD_BUS_METHOD("Halt", NULL, NULL, method_halt, SD_BUS_VTABLE_CAPABILITY(CAP_SYS_BOOT)), - SD_BUS_METHOD("KExec", NULL, NULL, method_kexec, SD_BUS_VTABLE_CAPABILITY(CAP_SYS_BOOT)), - SD_BUS_METHOD("SwitchRoot", "ss", NULL, method_switch_root, SD_BUS_VTABLE_CAPABILITY(CAP_SYS_BOOT)), - SD_BUS_METHOD("SetEnvironment", "as", NULL, method_set_environment, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("UnsetEnvironment", "as", NULL, method_unset_environment, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("UnsetAndSetEnvironment", "asas", NULL, method_unset_and_set_environment, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ListUnitFiles", NULL, "a(ss)", method_list_unit_files, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ListUnitFilesByPatterns", "asas", "a(ss)", method_list_unit_files_by_patterns, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetUnitFileState", "s", "s", method_get_unit_file_state, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("EnableUnitFiles", "asbb", "ba(sss)", method_enable_unit_files, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("DisableUnitFiles", "asb", "a(sss)", method_disable_unit_files, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ReenableUnitFiles", "asbb", "ba(sss)", method_reenable_unit_files, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("LinkUnitFiles", "asbb", "a(sss)", method_link_unit_files, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("PresetUnitFiles", "asbb", "ba(sss)", method_preset_unit_files, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("PresetUnitFilesWithMode", "assbb", "ba(sss)", method_preset_unit_files_with_mode, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("MaskUnitFiles", "asbb", "a(sss)", method_mask_unit_files, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("UnmaskUnitFiles", "asb", "a(sss)", method_unmask_unit_files, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("RevertUnitFiles", "as", "a(sss)", method_revert_unit_files, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetDefaultTarget", "sb", "a(sss)", method_set_default_target, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetDefaultTarget", NULL, "s", method_get_default_target, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("PresetAllUnitFiles", "sbb", "a(sss)", method_preset_all_unit_files, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("AddDependencyUnitFiles", "asssbb", "a(sss)", method_add_dependency_unit_files, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetUnitFileLinks", "sb", "as", method_get_unit_file_links, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetExitCode", "y", NULL, method_set_exit_code, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("LookupDynamicUserByName", "s", "u", method_lookup_dynamic_user_by_name, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("LookupDynamicUserByUID", "u", "s", method_lookup_dynamic_user_by_uid, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetDynamicUsers", NULL, "a(us)", method_get_dynamic_users, SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetUnit", + "s", + SD_BUS_PARAM(name), + "o", + SD_BUS_PARAM(unit), + method_get_unit, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetUnitByPID", + "u", + SD_BUS_PARAM(pid), + "o", + SD_BUS_PARAM(unit), + method_get_unit_by_pid, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetUnitByInvocationID", + "ay", + SD_BUS_PARAM(invocation_id), + "o", + SD_BUS_PARAM(unit), + method_get_unit_by_invocation_id, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetUnitByControlGroup", + "s", + SD_BUS_PARAM(cgroup), + "o", + SD_BUS_PARAM(unit), + method_get_unit_by_control_group, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("LoadUnit", + "s", + SD_BUS_PARAM(name), + "o", + SD_BUS_PARAM(unit), + method_load_unit, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("StartUnit", + "ss", + SD_BUS_PARAM(name) + SD_BUS_PARAM(mode), + "o", + SD_BUS_PARAM(job), + method_start_unit, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("StartUnitReplace", + "sss", + SD_BUS_PARAM(old_unit) + SD_BUS_PARAM(new_unit) + SD_BUS_PARAM(mode), + "o", + SD_BUS_PARAM(job), + method_start_unit_replace, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("StopUnit", + "ss", + SD_BUS_PARAM(name) + SD_BUS_PARAM(mode), + "o", + SD_BUS_PARAM(job), + method_stop_unit, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("ReloadUnit", + "ss", + SD_BUS_PARAM(name) + SD_BUS_PARAM(mode), + "o", + SD_BUS_PARAM(job), + method_reload_unit, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("RestartUnit", + "ss", + SD_BUS_PARAM(name) + SD_BUS_PARAM(mode), + "o", + SD_BUS_PARAM(job), + method_restart_unit, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("TryRestartUnit", + "ss", + SD_BUS_PARAM(name) + SD_BUS_PARAM(mode), + "o", + SD_BUS_PARAM(job), + method_try_restart_unit, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("ReloadOrRestartUnit", + "ss", + SD_BUS_PARAM(name) + SD_BUS_PARAM(mode), + "o", + SD_BUS_PARAM(job), + method_reload_or_restart_unit, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("ReloadOrTryRestartUnit", + "ss", + SD_BUS_PARAM(name) + SD_BUS_PARAM(mode), + "o", + SD_BUS_PARAM(job), + method_reload_or_try_restart_unit, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("EnqueueUnitJob", + "sss", + SD_BUS_PARAM(name) + SD_BUS_PARAM(job_type) + SD_BUS_PARAM(job_mode), + "uososa(uosos)", + SD_BUS_PARAM(job_id) + SD_BUS_PARAM(job_path) + SD_BUS_PARAM(unit_id) + SD_BUS_PARAM(unit_path) + SD_BUS_PARAM(job_type) + SD_BUS_PARAM(affected_jobs), + method_enqueue_unit_job, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("KillUnit", + "ssi", + SD_BUS_PARAM(name) + SD_BUS_PARAM(whom) + SD_BUS_PARAM(signal), + NULL,, + method_kill_unit, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("CleanUnit", + "sas", + SD_BUS_PARAM(name) + SD_BUS_PARAM(mask), + NULL,, + method_clean_unit, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("ResetFailedUnit", + "s", + SD_BUS_PARAM(name), + NULL,, + method_reset_failed_unit, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetUnitProperties", + "sba(sv)", + SD_BUS_PARAM(name) + SD_BUS_PARAM(runtime) + SD_BUS_PARAM(properties), + NULL,, + method_set_unit_properties, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("RefUnit", + "s", + SD_BUS_PARAM(name), + NULL,, + method_ref_unit, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("UnrefUnit", + "s", + SD_BUS_PARAM(name), + NULL,, + method_unref_unit, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("StartTransientUnit", + "ssa(sv)a(sa(sv))", + SD_BUS_PARAM(name) + SD_BUS_PARAM(mode) + SD_BUS_PARAM(properties) + SD_BUS_PARAM(aux), + "o", + SD_BUS_PARAM(job), + method_start_transient_unit, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetUnitProcesses", + "s", + SD_BUS_PARAM(name), + "a(sus)", + SD_BUS_PARAM(processes), + method_get_unit_processes, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("AttachProcessesToUnit", + "ssau", + SD_BUS_PARAM(unit_name) + SD_BUS_PARAM(subcgroup) + SD_BUS_PARAM(pids), + NULL,, + method_attach_processes_to_unit, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("AbandonScope", + "s", + SD_BUS_PARAM(name), + NULL,, + method_abandon_scope, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetJob", + "u", + SD_BUS_PARAM(id), + "o", + SD_BUS_PARAM(job), + method_get_job, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetJobAfter", + "u", + SD_BUS_PARAM(id), + "a(usssoo)", + SD_BUS_PARAM(jobs), + method_get_job_waiting, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetJobBefore", + "u", + SD_BUS_PARAM(id), + "a(usssoo)", + SD_BUS_PARAM(jobs), + method_get_job_waiting, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("CancelJob", + "u", + SD_BUS_PARAM(id), + NULL,, + method_cancel_job, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD("ClearJobs", + NULL, + NULL, + method_clear_jobs, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD("ResetFailed", + NULL, + NULL, + method_reset_failed, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("ListUnits", + NULL,, + "a(ssssssouso)", + SD_BUS_PARAM(units), + method_list_units, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("ListUnitsFiltered", + "as", + SD_BUS_PARAM(states), + "a(ssssssouso)", + SD_BUS_PARAM(units), + method_list_units_filtered, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("ListUnitsByPatterns", + "asas", + SD_BUS_PARAM(states) + SD_BUS_PARAM(patterns), + "a(ssssssouso)", + SD_BUS_PARAM(units), + method_list_units_by_patterns, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("ListUnitsByNames", + "as", + SD_BUS_PARAM(names), + "a(ssssssouso)", + SD_BUS_PARAM(units), + method_list_units_by_names, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("ListJobs", + NULL,, + "a(usssoo)", + SD_BUS_PARAM(jobs), + method_list_jobs, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD("Subscribe", + NULL, + NULL, + method_subscribe, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD("Unsubscribe", + NULL, + NULL, + method_unsubscribe, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("Dump", + NULL,, + "s", + SD_BUS_PARAM(output), + method_dump, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("DumpByFileDescriptor", + NULL,, + "h", + SD_BUS_PARAM(fd), + method_dump_by_fd, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("CreateSnapshot", + "sb", + SD_BUS_PARAM(name) + SD_BUS_PARAM(cleanup), + "o", + SD_BUS_PARAM(unit), + method_refuse_snapshot, + SD_BUS_VTABLE_UNPRIVILEGED|SD_BUS_VTABLE_HIDDEN), + SD_BUS_METHOD_WITH_NAMES("RemoveSnapshot", + "s", + SD_BUS_PARAM(name), + NULL,, + method_refuse_snapshot, + SD_BUS_VTABLE_UNPRIVILEGED|SD_BUS_VTABLE_HIDDEN), + SD_BUS_METHOD("Reload", + NULL, + NULL, + method_reload, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD("Reexecute", + NULL, + NULL, + method_reexecute, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD("Exit", + NULL, + NULL, + method_exit, + 0), + SD_BUS_METHOD("Reboot", + NULL, + NULL, + method_reboot, + SD_BUS_VTABLE_CAPABILITY(CAP_SYS_BOOT)), + SD_BUS_METHOD("PowerOff", + NULL, + NULL, + method_poweroff, + SD_BUS_VTABLE_CAPABILITY(CAP_SYS_BOOT)), + SD_BUS_METHOD("Halt", + NULL, + NULL, + method_halt, + SD_BUS_VTABLE_CAPABILITY(CAP_SYS_BOOT)), + SD_BUS_METHOD("KExec", + NULL, + NULL, + method_kexec, + SD_BUS_VTABLE_CAPABILITY(CAP_SYS_BOOT)), + SD_BUS_METHOD_WITH_NAMES("SwitchRoot", + "ss", + SD_BUS_PARAM(new_root) + SD_BUS_PARAM(init), + NULL,, + method_switch_root, + SD_BUS_VTABLE_CAPABILITY(CAP_SYS_BOOT)), + SD_BUS_METHOD_WITH_NAMES("SetEnvironment", + "as", + SD_BUS_PARAM(assignments), + NULL,, + method_set_environment, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("UnsetEnvironment", + "as", + SD_BUS_PARAM(names), + NULL,, + method_unset_environment, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("UnsetAndSetEnvironment", + "asas", + SD_BUS_PARAM(names) + SD_BUS_PARAM(assignments), + NULL,, + method_unset_and_set_environment, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("ListUnitFiles", + NULL,, + "a(ss)", + SD_BUS_PARAM(unit_files), + method_list_unit_files, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("ListUnitFilesByPatterns", + "asas", + SD_BUS_PARAM(states) + SD_BUS_PARAM(patterns), + "a(ss)", + SD_BUS_PARAM(unit_files), + method_list_unit_files_by_patterns, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetUnitFileState", + "s", + SD_BUS_PARAM(file), + "s", + SD_BUS_PARAM(state), + method_get_unit_file_state, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("EnableUnitFiles", + "asbb", + SD_BUS_PARAM(files) + SD_BUS_PARAM(runtime) + SD_BUS_PARAM(force), + "ba(sss)", + SD_BUS_PARAM(carries_install_info) + SD_BUS_PARAM(changes), + method_enable_unit_files, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("DisableUnitFiles", + "asb", + SD_BUS_PARAM(files) + SD_BUS_PARAM(runtime), + "a(sss)", + SD_BUS_PARAM(changes), + method_disable_unit_files, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("ReenableUnitFiles", + "asbb", + SD_BUS_PARAM(files) + SD_BUS_PARAM(runtime) + SD_BUS_PARAM(force), + "ba(sss)", + SD_BUS_PARAM(carries_install_info) + SD_BUS_PARAM(changes), + method_reenable_unit_files, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("LinkUnitFiles", + "asbb", + SD_BUS_PARAM(files) + SD_BUS_PARAM(runtime) + SD_BUS_PARAM(force), + "a(sss)", + SD_BUS_PARAM(changes), + method_link_unit_files, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("PresetUnitFiles", + "asbb", + SD_BUS_PARAM(files) + SD_BUS_PARAM(runtime) + SD_BUS_PARAM(force), + "ba(sss)", + SD_BUS_PARAM(carries_install_info) + SD_BUS_PARAM(changes), + method_preset_unit_files, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("PresetUnitFilesWithMode", + "assbb", + SD_BUS_PARAM(files) + SD_BUS_PARAM(mode) + SD_BUS_PARAM(runtime) + SD_BUS_PARAM(force), + "ba(sss)", + SD_BUS_PARAM(carries_install_info) + SD_BUS_PARAM(changes), + method_preset_unit_files_with_mode, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("MaskUnitFiles", + "asbb", + SD_BUS_PARAM(files) + SD_BUS_PARAM(runtime) + SD_BUS_PARAM(force), + "a(sss)", + SD_BUS_PARAM(changes), + method_mask_unit_files, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("UnmaskUnitFiles", + "asb", + SD_BUS_PARAM(files) + SD_BUS_PARAM(runtime), + "a(sss)", + SD_BUS_PARAM(changes), + method_unmask_unit_files, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("RevertUnitFiles", + "as", + SD_BUS_PARAM(files), + "a(sss)", + SD_BUS_PARAM(changes), + method_revert_unit_files, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetDefaultTarget", + "sb", + SD_BUS_PARAM(name) + SD_BUS_PARAM(force), + "a(sss)", + SD_BUS_PARAM(changes), + method_set_default_target, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetDefaultTarget", + NULL,, + "s", + SD_BUS_PARAM(name), + method_get_default_target, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("PresetAllUnitFiles", + "sbb", + SD_BUS_PARAM(mode) + SD_BUS_PARAM(runtime) + SD_BUS_PARAM(force), + "a(sss)", + SD_BUS_PARAM(changes), + method_preset_all_unit_files, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("AddDependencyUnitFiles", + "asssbb", + SD_BUS_PARAM(files) + SD_BUS_PARAM(target) + SD_BUS_PARAM(type) + SD_BUS_PARAM(runtime) + SD_BUS_PARAM(force), + "a(sss)", + SD_BUS_PARAM(changes), + method_add_dependency_unit_files, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetUnitFileLinks", + "sb", + SD_BUS_PARAM(name) + SD_BUS_PARAM(runtime), + "as", + SD_BUS_PARAM(links), + method_get_unit_file_links, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetExitCode", + "y", + SD_BUS_PARAM(number), + NULL,, + method_set_exit_code, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("LookupDynamicUserByName", + "s", + SD_BUS_PARAM(name), + "u", + SD_BUS_PARAM(uid), + method_lookup_dynamic_user_by_name, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("LookupDynamicUserByUID", + "u", + SD_BUS_PARAM(uid), + "s", + SD_BUS_PARAM(name), + method_lookup_dynamic_user_by_uid, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("GetDynamicUsers", + NULL,, + "a(us)", + SD_BUS_PARAM(users), + method_get_dynamic_users, + SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_SIGNAL("UnitNew", "so", 0), - SD_BUS_SIGNAL("UnitRemoved", "so", 0), - SD_BUS_SIGNAL("JobNew", "uos", 0), - SD_BUS_SIGNAL("JobRemoved", "uoss", 0), - SD_BUS_SIGNAL("StartupFinished", "tttttt", 0), + SD_BUS_SIGNAL_WITH_NAMES("UnitNew", + "so", + SD_BUS_PARAM(id) + SD_BUS_PARAM(unit), + 0), + SD_BUS_SIGNAL_WITH_NAMES("UnitRemoved", + "so", + SD_BUS_PARAM(id) + SD_BUS_PARAM(unit), + 0), + SD_BUS_SIGNAL_WITH_NAMES("JobNew", + "uos", + SD_BUS_PARAM(id) + SD_BUS_PARAM(job) + SD_BUS_PARAM(unit), + 0), + SD_BUS_SIGNAL_WITH_NAMES("JobRemoved", + "uoss", + SD_BUS_PARAM(id) + SD_BUS_PARAM(job) + SD_BUS_PARAM(unit) + SD_BUS_PARAM(result), + 0), + SD_BUS_SIGNAL_WITH_NAMES("StartupFinished", + "tttttt", + SD_BUS_PARAM(firmware) + SD_BUS_PARAM(loader) + SD_BUS_PARAM(kernel) + SD_BUS_PARAM(initrd) + SD_BUS_PARAM(userspace) + SD_BUS_PARAM(total), + 0), SD_BUS_SIGNAL("UnitFilesChanged", NULL, 0), - SD_BUS_SIGNAL("Reloading", "b", 0), + SD_BUS_SIGNAL_WITH_NAMES("Reloading", + "b", + SD_BUS_PARAM(active), + 0), SD_BUS_VTABLE_END }; diff --git a/src/core/dbus-unit.c b/src/core/dbus-unit.c index 496fd5eb6a..7a1f5041f3 100644 --- a/src/core/dbus-unit.c +++ b/src/core/dbus-unit.c @@ -843,20 +843,103 @@ const sd_bus_vtable bus_unit_vtable[] = { SD_BUS_PROPERTY("CollectMode", "s", property_get_collect_mode, offsetof(Unit, collect_mode), SD_BUS_VTABLE_PROPERTY_CONST), SD_BUS_PROPERTY("Refs", "as", property_get_refs, 0, 0), - SD_BUS_METHOD("Start", "s", "o", method_start, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("Stop", "s", "o", method_stop, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("Reload", "s", "o", method_reload, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("Restart", "s", "o", method_restart, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("TryRestart", "s", "o", method_try_restart, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ReloadOrRestart", "s", "o", method_reload_or_restart, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ReloadOrTryRestart", "s", "o", method_reload_or_try_restart, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("EnqueueJob", "ss", "uososa(uosos)", bus_unit_method_enqueue_job, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("Kill", "si", NULL, bus_unit_method_kill, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ResetFailed", NULL, NULL, bus_unit_method_reset_failed, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetProperties", "ba(sv)", NULL, bus_unit_method_set_properties, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("Ref", NULL, NULL, bus_unit_method_ref, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("Unref", NULL, NULL, bus_unit_method_unref, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("Clean", "as", NULL, bus_unit_method_clean, SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("Start", + "s", + SD_BUS_PARAM(mode), + "o", + SD_BUS_PARAM(job), + method_start, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("Stop", + "s", + SD_BUS_PARAM(mode), + "o", + SD_BUS_PARAM(job), + method_stop, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("Reload", + "s", + SD_BUS_PARAM(mode), + "o", + SD_BUS_PARAM(job), + method_reload, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("Restart", + "s", + SD_BUS_PARAM(mode), + "o", + SD_BUS_PARAM(job), + method_restart, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("TryRestart", + "s", + SD_BUS_PARAM(mode), + "o", + SD_BUS_PARAM(job), + method_try_restart, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("ReloadOrRestart", + "s", + SD_BUS_PARAM(mode), + "o", + SD_BUS_PARAM(job), + method_reload_or_restart, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("ReloadOrTryRestart", + "s", + SD_BUS_PARAM(mode), + "o", + SD_BUS_PARAM(job), + method_reload_or_try_restart, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("EnqueueJob", + "ss", + SD_BUS_PARAM(job_type) + SD_BUS_PARAM(job_mode), + "uososa(uosos)", + SD_BUS_PARAM(job_id) + SD_BUS_PARAM(job_path) + SD_BUS_PARAM(unit_id) + SD_BUS_PARAM(unit_path) + SD_BUS_PARAM(job_type) + SD_BUS_PARAM(affected_jobs), + bus_unit_method_enqueue_job, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("Kill", + "si", + SD_BUS_PARAM(whom) + SD_BUS_PARAM(signal), + NULL,, + bus_unit_method_kill, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD("ResetFailed", + NULL, + NULL, + bus_unit_method_reset_failed, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("SetProperties", + "ba(sv)", + SD_BUS_PARAM(runtime) + SD_BUS_PARAM(properties), + NULL,, + bus_unit_method_set_properties, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD("Ref", + NULL, + NULL, + bus_unit_method_ref, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD("Unref", + NULL, + NULL, + bus_unit_method_unref, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_NAMES("Clean", + "as", + SD_BUS_PARAM(mask), + NULL,, + bus_unit_method_clean, + SD_BUS_VTABLE_UNPRIVILEGED), /* For dependency types we don't support anymore always return an empty array */ SD_BUS_PROPERTY("RequiresOverridable", "as", property_get_empty_strv, 0, SD_BUS_VTABLE_HIDDEN), @@ -866,6 +949,7 @@ const sd_bus_vtable bus_unit_vtable[] = { /* Obsolete alias names */ SD_BUS_PROPERTY("StartLimitInterval", "t", bus_property_get_usec, offsetof(Unit, start_ratelimit.interval), SD_BUS_VTABLE_PROPERTY_CONST|SD_BUS_VTABLE_HIDDEN), SD_BUS_PROPERTY("StartLimitIntervalSec", "t", bus_property_get_usec, offsetof(Unit, start_ratelimit.interval), SD_BUS_VTABLE_PROPERTY_CONST|SD_BUS_VTABLE_HIDDEN), + SD_BUS_VTABLE_END }; @@ -1365,8 +1449,22 @@ const sd_bus_vtable bus_unit_cgroup_vtable[] = { SD_BUS_PROPERTY("IOReadOperations", "t", property_get_io_counter, 0, 0), SD_BUS_PROPERTY("IOWriteBytes", "t", property_get_io_counter, 0, 0), SD_BUS_PROPERTY("IOWriteOperations", "t", property_get_io_counter, 0, 0), - SD_BUS_METHOD("GetProcesses", NULL, "a(sus)", bus_unit_method_get_processes, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("AttachProcesses", "sau", NULL, bus_unit_method_attach_processes, SD_BUS_VTABLE_UNPRIVILEGED), + + SD_BUS_METHOD_WITH_NAMES("GetProcesses", + NULL,, + "a(sus)", + SD_BUS_PARAM(processes), + bus_unit_method_get_processes, + SD_BUS_VTABLE_UNPRIVILEGED), + + SD_BUS_METHOD_WITH_NAMES("AttachProcesses", + "sau", + SD_BUS_PARAM(subcgroup) + SD_BUS_PARAM(pids), + NULL,, + bus_unit_method_attach_processes, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_VTABLE_END }; From e5dd26cc200496422a298ad308c08f9defc417e2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Tue, 7 Apr 2020 16:58:58 +0200 Subject: [PATCH 17/26] Add updater for dbus introspection in man pages Compares to gdbus output, the values of properties are replaced by ellipses. For arrays and strings, the outer markers are kept. This is obviously also told by the type string, but it seems a bit easier to read this way. For any elements which are undocumented, a comment is inserted in sources. "Undocumented" means that the expected element was not found. This might require some adjustments if I missed some markup types. Invocation is manual: $ tools/update-dbus-docs.py tools/update-dbus-docs.py man/org.freedesktop.login1.xml $ tools/update-dbus-docs.py tools/update-dbus-docs.py man/org.freedesktop.resolve1.xml $ tools/update-dbus-docs.py tools/update-dbus-docs.py man/org.freedesktop.systemd1.xml ... If some object is not found on the bus, the existing output is retained. So the user needs to make sure that the appropriate objects have been instantiated before calling this. We don't change the dbus interface very often, so I think this manual mode is OK as a starting point. Making this fully automatic later would be nice of course. --- tools/update-dbus-docs.py | 244 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 244 insertions(+) create mode 100755 tools/update-dbus-docs.py diff --git a/tools/update-dbus-docs.py b/tools/update-dbus-docs.py new file mode 100755 index 0000000000..2f69b50b89 --- /dev/null +++ b/tools/update-dbus-docs.py @@ -0,0 +1,244 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: LGPL-2.1+ + +import collections +import sys +import shlex +import subprocess +import io +import pprint +from lxml import etree + +PARSER = etree.XMLParser(no_network=True, + remove_comments=False, + strip_cdata=False, + resolve_entities=False) + +PRINT_ERRORS = True + +class NoCommand(Exception): + pass + +def find_command(lines): + acc = [] + for num, line in enumerate(lines): + # skip empty leading line + if num == 0 and not line: + continue + cont = line.endswith('\\') + if cont: + line = line[:-1].rstrip() + acc.append(line if not acc else line.lstrip()) + if not cont: + break + joined = ' '.join(acc) + if not joined.startswith('$ '): + raise NoCommand + return joined[2:], lines[:num+1] + [''], lines[-1] + +BORING_INTERFACES = [ + 'org.freedesktop.DBus.Peer', + 'org.freedesktop.DBus.Introspectable', + 'org.freedesktop.DBus.Properties', +] + +def print_method(declarations, elem, *, prefix, file, is_signal=False): + name = elem.get('name') + klass = 'signal' if is_signal else 'method' + declarations[klass].append(name) + + print(f'''{prefix}{name}(''', file=file, end='') + lead = ',\n' + prefix + ' ' * len(name) + ' ' + + for num, arg in enumerate(elem.findall('./arg')): + argname = arg.get('name') + + if argname is None: + if PRINT_ERRORS: + print(f'method {name}: argument {num+1} has no name', file=sys.stderr) + argname = 'UNNAMED' + + type = arg.get('type') + if not is_signal: + direction = arg.get('direction') + print(f'''{lead if num > 0 else ''}{direction:3} {type} {argname}''', file=file, end='') + else: + print(f'''{lead if num > 0 else ''}{type} {argname}''', file=file, end='') + + print(f');', file=file) + +ACCESS_MAP = { + 'read' : 'readonly', + 'write' : 'readwrite', +} + +def value_ellipsis(type): + if type == 's': + return "'...'"; + if type[0] == 'a': + inner = value_ellipsis(type[1:]) + return f"[{inner}{', ...' if inner != '...' else ''}]"; + return '...' + +def print_property(declarations, elem, *, prefix, file): + name = elem.get('name') + type = elem.get('type') + access = elem.get('access') + + declarations['property'].append(name) + + # @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + # @org.freedesktop.systemd1.Privileged("true") + # readwrite b EnableWallMessages = false; + + for anno in elem.findall('./annotation'): + anno_name = anno.get('name') + anno_value = anno.get('value') + print(f'''{prefix}@{anno_name}("{anno_value}")''', file=file) + + access = ACCESS_MAP.get(access, access) + print(f'''{prefix}{access} {type} {name} = {value_ellipsis(type)};''', file=file) + +def print_interface(iface, *, prefix, file, print_boring, declarations): + name = iface.get('name') + + is_boring = name in BORING_INTERFACES + if is_boring and print_boring: + print(f'''{prefix}interface {name} {{ ... }};''', file=file) + elif not is_boring and not print_boring: + print(f'''{prefix}interface {name} {{''', file=file) + prefix2 = prefix + ' ' + + for num, elem in enumerate(iface.findall('./method')): + if num == 0: + print(f'''{prefix2}methods:''', file=file) + print_method(declarations, elem, prefix=prefix2 + ' ', file=file) + + for num, elem in enumerate(iface.findall('./signal')): + if num == 0: + print(f'''{prefix2}signals:''', file=file) + print_method(declarations, elem, prefix=prefix2 + ' ', file=file, is_signal=True) + + for num, elem in enumerate(iface.findall('./property')): + if num == 0: + print(f'''{prefix2}properties:''', file=file) + print_property(declarations, elem, prefix=prefix2 + ' ', file=file) + + print(f'''{prefix}}};''', file=file) + +def document_has_elem_with_text(document, elem, item_repr): + predicate = f".//{elem}" # [text() = 'foo'] doesn't seem supported :( + for loc in document.findall(predicate): + if loc.text == item_repr: + return True + else: + return False + +def check_documented(document, declarations): + missing = [] + for klass, items in declarations.items(): + for item in items: + if klass == 'method': + elem = 'function' + item_repr = f'{item}()' + elif klass == 'signal': + elem = 'function' + item_repr = item + elif klass == 'property': + elem = 'varname' + item_repr = item + else: + assert False, (klass, item) + + if not document_has_elem_with_text(document, elem, item_repr): + if PRINT_ERRORS: + print(f'{klass} {item} is not documented :(') + missing.append((klass, item)) + + return missing + +def xml_to_text(destination, xml): + file = io.StringIO() + + declarations = collections.defaultdict(list) + + print(f'''node {destination} {{''', file=file) + + for print_boring in [False, True]: + for iface in xml.findall('./interface'): + print_interface(iface, prefix=' ', file=file, + print_boring=print_boring, + declarations=declarations) + + print(f'''}};''', file=file) + + return file.getvalue(), declarations + +def subst_output(document, programlisting): + try: + cmd, prefix_lines, footer = find_command(programlisting.text.splitlines()) + except NoCommand: + return + + argv = shlex.split(cmd) + argv += ['--xml'] + print(f'COMMAND: {shlex.join(argv)}') + + object_idx = argv.index('--object-path') + object_path = argv[object_idx + 1] + + try: + out = subprocess.check_output(argv, text=True) + except subprocess.CalledProcessError: + print('command failed, ignoring', file=sys.stderr) + return + + xml = etree.fromstring(out, parser=PARSER) + + new_text, declarations = xml_to_text(object_path, xml) + + programlisting.text = '\n'.join(prefix_lines) + '\n' + new_text + footer + + if declarations: + missing = check_documented(document, declarations) + parent = programlisting.getparent() + + # delete old comments + for child in parent: + if (child.tag == etree.Comment + and 'not documented' in child.text): + parent.remove(child) + + # insert comments for undocumented items + for item in reversed(missing): + comment = etree.Comment(f'{item[0]} {item[1]} is not documented!') + comment.tail = programlisting.tail + parent.insert(parent.index(programlisting) + 1, comment) + +def process(page): + src = open(page).read() + xml = etree.fromstring(src, parser=PARSER) + + # print('parsing {}'.format(name), file=sys.stderr) + if xml.tag != 'refentry': + return + + pls = xml.findall('.//programlisting') + for pl in pls: + subst_output(xml, pl) + + out_text = etree.tostring(xml, encoding='unicode') + # massage format to avoid some lxml whitespace handling idiosyncracies + # https://bugs.launchpad.net/lxml/+bug/526799 + out_text = (src[:src.find(' Date: Fri, 10 Apr 2020 14:46:44 +0200 Subject: [PATCH 18/26] update-dbus-docs: add support for settings printing just one selected interface So far the units there were being documented had only one custom interface. But for the pid1 case, something more flexibile is needed. So let's add an annotation in the page what we want to print, and filter in the generator. --- man/org.freedesktop.systemd1.xml | 28 ++++++++++++++-------------- tools/update-dbus-docs.py | 14 ++++++++++---- 2 files changed, 24 insertions(+), 18 deletions(-) diff --git a/man/org.freedesktop.systemd1.xml b/man/org.freedesktop.systemd1.xml index 24fafac272..1f0d1818ca 100644 --- a/man/org.freedesktop.systemd1.xml +++ b/man/org.freedesktop.systemd1.xml @@ -625,7 +625,7 @@ node /org/freedesktop/systemd1 { Unit Objects - + $ gdbus introspect --system --dest org.freedesktop.systemd1 \ --object-path /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice @@ -909,7 +909,7 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice { org.freedesktop.systemd1.Service interface (described here) in addition to the generic org.freedesktop.systemd1.Unit interface (see above). - + $ gdbus introspect --system --dest org.freedesktop.systemd1 \ --object-path /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice @@ -1120,7 +1120,7 @@ $ gdbus introspect --system --dest org.freedesktop.systemd1 \ Socket Unit Objects - + $ gdbus introspect --system --dest org.freedesktop.systemd1 \ --object-path /org/freedesktop/systemd1/unit/avahi_2ddaemon_2esocket @@ -1288,7 +1288,7 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2esocket { Target Unit Objects - + $ gdbus introspect --system --dest org.freedesktop.systemd1 \ --object-path /org/freedesktop/systemd1/unit/basic_2etarget @@ -1323,11 +1323,11 @@ node /org/freedesktop/systemd1/unit/basic_2etarget { All device unit objects implement the org.freedesktop.systemd1.Device interface (described here) in addition to the generic org.freedesktop.systemd1.Unit interface (see above). - + $ gdbus introspect --system --dest org.freedesktop.systemd1 \ - --object-path /org/freedesktop/systemd1/unit/dev_2ddisk_2dby_5cx2did_2data_5cx2dSAMSUNG_5fHD501LJ_5fS0MUJ1KQ161445_2edevice + --object-path /org/freedesktop/systemd1/unit/dev_2dfoo_2edevice -node /org/freedesktop/systemd1/unit/dev_2ddisk_2dby_5cx2did_2data_5cx2dSAMSUNG_5fHD501LJ_5fS0MUJ1KQ161445_2edevice { +node /org/freedesktop/systemd1/unit/dev_2d_foo_2edevice { interface org.freedesktop.systemd1.Unit { ... }; @@ -1367,7 +1367,7 @@ node /org/freedesktop/systemd1/unit/dev_2ddisk_2dby_5cx2did_2data_5cx2dSAMSUNG_5 interface (described here) in addition to the generic org.freedesktop.systemd1.Unit interface (see above) - + $ gdbus introspect --system --dest org.freedesktop.systemd1 \ --object-path /org/freedesktop/systemd1/unit/home_2emount @@ -1507,7 +1507,7 @@ node /org/freedesktop/systemd1/unit/home_2emount { org.freedesktop.systemd1.Automount interface (described here) in addition to the generic org.freedesktop.systemd1.Unit interface (see above). - + $ gdbus introspect --system --dest org.freedesktop.systemd1 \ --object-path /org/freedesktop/systemd1/unit/proc_2dsys_2dfs_2dbinfmt_5fmisc_2eautomount @@ -1555,7 +1555,7 @@ node /org/freedesktop/systemd1/unit/proc_2dsys_2dfs_2dbinfmt_5fmisc_2eautomount interface (described here) in addition to the generic org.freedesktop.systemd1.Unit interface (see above). - + $ gdbus introspect --system --dest org.freedesktop.systemd1 \ --object-path /org/freedesktop/systemd1/unit/systemd_2dtmpfiles_2dclean_2etimer @@ -1622,7 +1622,7 @@ node /org/freedesktop/systemd1/unit/systemd_2dtmpfiles_2dclean_2etimer { interface (described here) in addition to the generic org.freedesktop.systemd1.Unit interface (see above). - + $ gdbus introspect --system --dest org.freedesktop.systemd1 \ --object-path /org/freedesktop/systemd1/unit/dev_2dsda3_2eswap @@ -1760,7 +1760,7 @@ node /org/freedesktop/systemd1/unit/dev_2dsda3_2eswap { Path Unit Objects - + $ gdbus introspect --system --dest org.freedesktop.systemd1 \ --object-path /org/freedesktop/systemd1/unit/cups_2epath @@ -1816,7 +1816,7 @@ node /org/freedesktop/systemd1/unit/cups_2epath { interface (described here) in addition to the generic org.freedesktop.systemd1.Unit interface (see above). - + $ gdbus introspect --system --dest org.freedesktop.systemd1 \ --object-path /org/freedesktop/systemd1/unit/system_2eslice @@ -1868,7 +1868,7 @@ node /org/freedesktop/systemd1/unit/system_2eslice { interface (described here) in addition to the generic org.freedesktop.systemd1.Unit interface (see above). - + $ gdbus introspect --system --dest org.freedesktop.systemd1 \ --object-path /org/freedesktop/systemd1/unit/session_2d1_2escope diff --git a/tools/update-dbus-docs.py b/tools/update-dbus-docs.py index 2f69b50b89..41612947ab 100755 --- a/tools/update-dbus-docs.py +++ b/tools/update-dbus-docs.py @@ -99,12 +99,15 @@ def print_property(declarations, elem, *, prefix, file): access = ACCESS_MAP.get(access, access) print(f'''{prefix}{access} {type} {name} = {value_ellipsis(type)};''', file=file) -def print_interface(iface, *, prefix, file, print_boring, declarations): +def print_interface(iface, *, prefix, file, print_boring, only_interface, declarations): name = iface.get('name') - is_boring = name in BORING_INTERFACES + is_boring = (name in BORING_INTERFACES or + only_interface is not None and name != only_interface) + if is_boring and print_boring: print(f'''{prefix}interface {name} {{ ... }};''', file=file) + elif not is_boring and not print_boring: print(f'''{prefix}interface {name} {{''', file=file) prefix2 = prefix + ' ' @@ -157,7 +160,7 @@ def check_documented(document, declarations): return missing -def xml_to_text(destination, xml): +def xml_to_text(destination, xml, *, only_interface=None): file = io.StringIO() declarations = collections.defaultdict(list) @@ -168,6 +171,7 @@ def xml_to_text(destination, xml): for iface in xml.findall('./interface'): print_interface(iface, prefix=' ', file=file, print_boring=print_boring, + only_interface=only_interface, declarations=declarations) print(f'''}};''', file=file) @@ -180,6 +184,8 @@ def subst_output(document, programlisting): except NoCommand: return + only_interface = programlisting.get('interface', None) + argv = shlex.split(cmd) argv += ['--xml'] print(f'COMMAND: {shlex.join(argv)}') @@ -195,7 +201,7 @@ def subst_output(document, programlisting): xml = etree.fromstring(out, parser=PARSER) - new_text, declarations = xml_to_text(object_path, xml) + new_text, declarations = xml_to_text(object_path, xml, only_interface=only_interface) programlisting.text = '\n'.join(prefix_lines) + '\n' + new_text + footer From 4fb222c4b29ec2a1a451a1e0e99c5d3c520395ab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 10 Apr 2020 15:07:03 +0200 Subject: [PATCH 19/26] man: run dbus api docs through the updater This replaces the api export tables with updated versions, and inserts comments for all "undocumented" items. The slow work of documented them is left for later ;) lxml does some formatting changes that are not significant for lxml processing, but generate spurious difference in the diff (namely: ulinks become one-line, and double quotes are used instead of single quotes for element attribute values). This should be a one-time thing: subsequent renegeration should be idempotent with regards to this. --- man/org.freedesktop.hostname1.xml | 100 +++++-- man/org.freedesktop.import1.xml | 52 ++-- man/org.freedesktop.locale1.xml | 44 +-- man/org.freedesktop.login1.xml | 441 ++++++++++++++++++++++-------- man/org.freedesktop.machine1.xml | 108 +++++--- man/org.freedesktop.resolve1.xml | 178 +++++++++--- man/org.freedesktop.timedate1.xml | 51 +++- 7 files changed, 715 insertions(+), 259 deletions(-) diff --git a/man/org.freedesktop.hostname1.xml b/man/org.freedesktop.hostname1.xml index a381cb8239..b9522a3a08 100644 --- a/man/org.freedesktop.hostname1.xml +++ b/man/org.freedesktop.hostname1.xml @@ -46,33 +46,81 @@ $ gdbus introspect --system \ node /org/freedesktop/hostname1 { interface org.freedesktop.hostname1 { methods: - SetHostname(in s name, - in b user_interaction); - SetStaticHostname(in s name, - in b user_interaction); - SetPrettyHostname(in s name, - in b user_interaction); - SetIconName(in s name, - in b user_interaction); - SetChassis(in s name, - in b user_interaction); - signals: + SetHostname(in s hostname, + in b interactive); + SetStaticHostname(in s hostname, + in b interactive); + SetPrettyHostname(in s hostname, + in b interactive); + SetIconName(in s icon, + in b interactive); + SetChassis(in s chassis, + in b interactive); + SetDeployment(in s deployment, + in b interactive); + SetLocation(in s location, + in b interactive); + GetProductUUID(in b interactive, + out ay uuid); properties: - readonly s Hostname = 'dhcp-192-168-47-11'; - readonly s StaticHostname = 'lennarts-computer'; - readonly s PrettyHostname = 'Lennart’s Computer'; - readonly s IconName = 'computer-laptop'; - readonly s Chassis = 'laptop'; - }; - interface org.freedesktop.DBus.Properties { - }; - interface org.freedesktop.DBus.Introspectable { - }; - interface org.freedesktop.DBus.Peer { + readonly s Hostname = '...'; + readonly s StaticHostname = '...'; + readonly s PrettyHostname = '...'; + readonly s IconName = '...'; + readonly s Chassis = '...'; + readonly s Deployment = '...'; + readonly s Location = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s KernelName = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s KernelRelease = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s KernelVersion = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s OperatingSystemPrettyName = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s OperatingSystemCPEName = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s HomeURL = '...'; }; + interface org.freedesktop.DBus.Peer { ... }; + interface org.freedesktop.DBus.Introspectable { ... }; + interface org.freedesktop.DBus.Properties { ... }; }; + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Whenever the hostname or other meta data is changed via the daemon, PropertyChanged signals are sent out to subscribed clients. Changing a hostname using this interface is authenticated via PolicyKit. @@ -84,13 +132,13 @@ node /org/freedesktop/hostname1 { The static (configured) host name is the one configured in /etc/hostname. It is chosen by the local user. It is not always in sync with the current hostname as returned by the - gethostname3 + gethostname3 system call. If no host name is configured this property will be the empty string. Setting this property to the empty string will remove /etc/hostname. This hostname should be an internet-style hostname, 7-bit lowercase ASCII, no special chars/spaces. The transient (dynamic) host name is the one configured via the kernel's - sethostname3. + sethostname3. It can be different from the static hostname in case DHCP or mDNS have been configured to change the name based on network information. This property is never empty. If no hostname is set this will default to @@ -134,14 +182,14 @@ node /org/freedesktop/hostname1 { assumed to be highly dynamic, and hence should be watched directly, without involving PropertyChanged messages from systemd-hostnamed. For that, open /proc/sys/kernel/hostname and - poll3 + poll3 for SIGHUP which is triggered by the kernel every time the hostname changes. Again: this is special for the transient (dynamic) hostname, and does not apply to the configured (fixed) hostname. Applications may bypass the daemon to read the hostname data if notifications of host name changes are not necessary. Use - gethostname3, + gethostname3, /etc/hostname (possibly with per-distribution fallbacks), and machine-info3 for that. For more information on these files and syscalls see the respective man pages. diff --git a/man/org.freedesktop.import1.xml b/man/org.freedesktop.import1.xml index 9c8498ff7f..6a628f4671 100644 --- a/man/org.freedesktop.import1.xml +++ b/man/org.freedesktop.import1.xml @@ -66,6 +66,12 @@ node /org/freedesktop/import1 { in b read_only, out u transfer_id, out o transfer_path); + ImportFileSystem(in h fd, + in s local_name, + in b force, + in b read_only, + out u transfer_id, + out o transfer_path); ExportTar(in s local_name, in h fd, in s format, @@ -88,7 +94,7 @@ node /org/freedesktop/import1 { in b force, out u transfer_id, out o transfer_path); - ListTransfers(out a(usssdo) list); + ListTransfers(out a(usssdo) transfers); CancelTransfer(in u transfer_id); signals: TransferNew(u transfer_id, @@ -97,14 +103,13 @@ node /org/freedesktop/import1 { o transfer_path, s result); }; - interface org.freedesktop.DBus.Peer { - }; - interface org.freedesktop.DBus.Introspectable { - }; - interface org.freedesktop.DBus.Properties { - }; + interface org.freedesktop.DBus.Peer { ... }; + interface org.freedesktop.DBus.Introspectable { ... }; + interface org.freedesktop.DBus.Properties { ... }; }; - + + + Methods @@ -215,21 +220,26 @@ node /org/freedesktop/import1/transfer/_1 { LogMessage(u priority, s line); properties: - readonly u Id = 1; - readonly s Local = 'xenial-server-cloudimg-amd64-root'; - readonly s Remote = 'https://cloud-images.ubuntu.com/xenial/current/xenial-server-cloudimg-amd64-root.tar.gz'; - readonly s Type = 'pull-tar'; - readonly s Verify = 'signature'; - readonly d Progress = 0.253; - }; - interface org.freedesktop.DBus.Peer { - }; - interface org.freedesktop.DBus.Introspectable { - }; - interface org.freedesktop.DBus.Properties { + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly u Id = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s Local = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s Remote = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s Type = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s Verify = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly d Progress = ...; }; + interface org.freedesktop.DBus.Peer { ... }; + interface org.freedesktop.DBus.Introspectable { ... }; + interface org.freedesktop.DBus.Properties { ... }; }; - + + + Methods diff --git a/man/org.freedesktop.locale1.xml b/man/org.freedesktop.locale1.xml index 7c345acc00..7b2bf2870f 100644 --- a/man/org.freedesktop.locale1.xml +++ b/man/org.freedesktop.locale1.xml @@ -43,36 +43,46 @@ node /org/freedesktop/locale1 { interface org.freedesktop.locale1 { methods: SetLocale(in as locale, - in b user_interaction); + in b interactive); SetVConsoleKeyboard(in s keymap, in s keymap_toggle, in b convert, - in b user_interaction); + in b interactive); SetX11Keyboard(in s layout, in s model, in s variant, in s options, in b convert, - in b user_interaction); - signals: + in b interactive); properties: - readonly as Locale = ['LANG=en_US.UTF-8']; - readonly s VConsoleKeymap = 'de'; - readonly s VConsoleKeymapToggle = ''; - readonly s X11Layout = 'de'; - readonly s X11Model = ''; - readonly s X11Variant = ''; - readonly s X11Options = ''; - }; - interface org.freedesktop.DBus.Properties { - }; - interface org.freedesktop.DBus.Introspectable { - }; - interface org.freedesktop.DBus.Peer { + readonly as Locale = ['...', ...]; + readonly s X11Layout = '...'; + readonly s X11Model = '...'; + readonly s X11Variant = '...'; + readonly s X11Options = '...'; + readonly s VConsoleKeymap = '...'; + readonly s VConsoleKeymapToggle = '...'; }; + interface org.freedesktop.DBus.Peer { ... }; + interface org.freedesktop.DBus.Introspectable { ... }; + interface org.freedesktop.DBus.Properties { ... }; }; + + + + + + + + + + + + + + The system locale consists of an array of environment-variable-assignment-like strings. The following strings are known: LANG=, LC_CTYPE=, LC_NUMERIC=, LC_TIME=, LC_COLLATE=, diff --git a/man/org.freedesktop.login1.xml b/man/org.freedesktop.login1.xml index 2910693865..1c6134f9a6 100644 --- a/man/org.freedesktop.login1.xml +++ b/man/org.freedesktop.login1.xml @@ -42,6 +42,7 @@ $ gdbus introspect --system \ --dest org.freedesktop.login1 \ --object-path /org/freedesktop/login1 + node /org/freedesktop/login1 { interface org.freedesktop.login1.Manager { methods: @@ -55,10 +56,10 @@ node /org/freedesktop/login1 { out o object_path); GetSeat(in s seat_id, out o object_path); - ListSessions(out a(susso) session_list); - ListUsers(out a(uso) user_list); - ListSeats(out a(so) seat_list); - ListInhibitors(out a(ssssuu) inhibitor_list); + ListSessions(out a(susso) sessions); + ListUsers(out a(uso) users); + ListSeats(out a(so) seats); + ListInhibitors(out a(ssssuu) inhibitors); CreateSession(in u uid, in u pid, in s service, @@ -91,29 +92,33 @@ node /org/freedesktop/login1 { UnlockSessions(); KillSession(in s session_id, in s who, - in i signo); + in i signal_number); KillUser(in u uid, - in i signo); + in i signal_number); TerminateSession(in s session_id); TerminateUser(in u uid); TerminateSeat(in s seat_id); SetUserLinger(in u uid, - in b linger, + in b enable, in b interactive); AttachDevice(in s seat_id, - in s sysfs, + in s sysfs_path, in b interactive); FlushDevices(in b interactive); PowerOff(in b interactive); Reboot(in b interactive); + Halt(in b interactive); Suspend(in b interactive); Hibernate(in b interactive); HybridSleep(in b interactive); + SuspendThenHibernate(in b interactive); CanPowerOff(out s result); CanReboot(out s result); + CanHalt(out s result); CanSuspend(out s result); CanHibernate(out s result); CanHybridSleep(out s result); + CanSuspendThenHibernate(out s result); ScheduleShutdown(in s type, in t usec); CancelScheduledShutdown(out b cancelled); @@ -122,8 +127,14 @@ node /org/freedesktop/login1 { in s why, in s mode, out h pipe_fd); + CanRebootParameter(out s result); + SetRebootParameter(in s parameter); CanRebootToFirmwareSetup(out s result); SetRebootToFirmwareSetup(in b enable); + CanRebootToBootLoaderMenu(out s result); + SetRebootToBootLoaderMenu(in t timeout); + CanRebootToBootLoaderEntry(out s result); + SetRebootToBootLoaderEntry(in s boot_loader_entry); SetWallMessage(in s wall_message, in b enable); signals: @@ -142,41 +153,202 @@ node /org/freedesktop/login1 { PrepareForShutdown(b start); PrepareForSleep(b start); properties: - readwrite b EnableWallMessages = false; - readwrite s WallMessage = ''; - readonly u NAutoVTs = 6; - readonly as KillOnlyUsers = []; - readonly as KillExcludeUsers = ['root']; - readonly b KillUserProcesses = false; - readonly b RebootToFirmwareSetup = false; - readonly b IdleHint = false; - readonly t IdleSinceHint = 0; - readonly t IdleSinceHintMonotonic = 0; - readonly s BlockInhibited = 'handle-power-key:handle-suspend-key:handle-hibernate-key'; - readonly s DelayInhibited = 'sleep'; - readonly t InhibitDelayMaxUSec = 5000000; - readonly s HandlePowerKey = 'poweroff'; - readonly s HandleSuspendKey = 'suspend'; - readonly s HandleHibernateKey = 'hibernate'; - readonly s HandleLidSwitch = 'suspend'; - readonly s HandleLidSwitchDocked = 'ignore'; - readonly t HoldoffTimeoutUSec = 30000000; - readonly s IdleAction = 'ignore'; - readonly t IdleActionUSec = 1800000000; - readonly b PreparingForShutdown = false; - readonly b PreparingForSleep = false; - readonly (st) ScheduledShutdown = ('', 0); - readonly b Docked = false; - }; - interface org.freedesktop.DBus.Peer { - }; - interface org.freedesktop.DBus.Introspectable { - }; - interface org.freedesktop.DBus.Properties { + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + @org.freedesktop.systemd1.Privileged("true") + readwrite b EnableWallMessages = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + @org.freedesktop.systemd1.Privileged("true") + readwrite s WallMessage = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly u NAutoVTs = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly as KillOnlyUsers = ['...', ...]; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly as KillExcludeUsers = ['...', ...]; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly b KillUserProcesses = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly s RebootParameter = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly b RebootToFirmwareSetup = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly t RebootToBootLoaderMenu = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly s RebootToBootLoaderEntry = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly as BootLoaderEntries = ['...', ...]; + readonly b IdleHint = ...; + readonly t IdleSinceHint = ...; + readonly t IdleSinceHintMonotonic = ...; + readonly s BlockInhibited = '...'; + readonly s DelayInhibited = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly t InhibitDelayMaxUSec = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly t UserStopDelayUSec = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s HandlePowerKey = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s HandleSuspendKey = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s HandleHibernateKey = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s HandleLidSwitch = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s HandleLidSwitchExternalPower = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s HandleLidSwitchDocked = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly t HoldoffTimeoutUSec = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s IdleAction = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly t IdleActionUSec = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly b PreparingForShutdown = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly b PreparingForSleep = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly (st) ScheduledShutdown = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly b Docked = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly b LidClosed = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly b OnExternalPower = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly b RemoveIPC = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly t RuntimeDirectorySize = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly t InhibitorsMax = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly t NCurrentInhibitors = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly t SessionsMax = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly t NCurrentSessions = ...; }; + interface org.freedesktop.DBus.Peer { ... }; + interface org.freedesktop.DBus.Introspectable { ... }; + interface org.freedesktop.DBus.Properties { ... }; }; + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Security @@ -382,6 +554,7 @@ node /org/freedesktop/login1 { $ gdbus introspect --system --dest org.freedesktop.login1 \ --object-path /org/freedesktop/login1/seat/seat0 + node /org/freedesktop/login1/seat/seat0 { interface org.freedesktop.login1.Seat { methods: @@ -391,25 +564,36 @@ node /org/freedesktop/login1/seat/seat0 { SwitchToNext(); SwitchToPrevious(); properties: - readonly s Id = 'seat0'; - readonly (so) ActiveSession = ('', '/'); - readonly b CanMultiSession = true; - readonly b CanTTY = true; - readonly b CanGraphical = true; - readonly a(so) Sessions = [('c1', '/org/freedesktop/login1/session/c1')]; - readonly b IdleHint = true; - readonly t IdleSinceHint = 1389368976087311; - readonly t IdleSinceHintMonotonic = 48213948; - }; - interface org.freedesktop.DBus.Properties { - }; - interface org.freedesktop.DBus.Peer { - }; - interface org.freedesktop.DBus.Introspectable { + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s Id = '...'; + readonly (so) ActiveSession = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly b CanMultiSession = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly b CanTTY = ...; + readonly b CanGraphical = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly a(so) Sessions = [...]; + readonly b IdleHint = ...; + readonly t IdleSinceHint = ...; + readonly t IdleSinceHintMonotonic = ...; }; + interface org.freedesktop.DBus.Peer { ... }; + interface org.freedesktop.DBus.Introspectable { ... }; + interface org.freedesktop.DBus.Properties { ... }; }; + + + + + + + + + + Methods @@ -457,33 +641,43 @@ node /org/freedesktop/login1/user/_1000 { interface org.freedesktop.login1.User { methods: Terminate(); - Kill(in i signo); + Kill(in i signal_number); properties: - readonly u UID = 1000; - readonly u GID = 1000; - readonly s Name = 'test'; - readonly t Timestamp = 1389368964102424; - readonly t TimestampMonotonic = 36229061; - readonly s RuntimePath = '/run/user/1000'; - readonly s Service = 'user@1000.service'; - readonly s Slice = 'user-1000.slice'; - readonly (so) Display = ('', '/'); - readonly s State = 'active'; - readonly a(so) Sessions = [('28', '/org/freedesktop/login1/session/_328'), ('3', '/org/freedesktop/login1/session/_33')]; - readonly b IdleHint = false; - readonly t IdleSinceHint = 0; - readonly t IdleSinceHintMonotonic = 0; - readonly b Linger = false; - }; - interface org.freedesktop.DBus.Properties { - }; - interface org.freedesktop.DBus.Peer { - }; - interface org.freedesktop.DBus.Introspectable { + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly u UID = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly u GID = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s Name = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly t Timestamp = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly t TimestampMonotonic = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s RuntimePath = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s Service = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s Slice = '...'; + readonly (so) Display = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly s State = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly a(so) Sessions = [...]; + readonly b IdleHint = ...; + readonly t IdleSinceHint = ...; + readonly t IdleSinceHintMonotonic = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly b Linger = ...; }; + interface org.freedesktop.DBus.Peer { ... }; + interface org.freedesktop.DBus.Introspectable { ... }; + interface org.freedesktop.DBus.Properties { ... }; }; + + Methods @@ -547,9 +741,9 @@ node /org/freedesktop/login1/user/_1000 { $ gdbus introspect --system --dest org.freedesktop.login1 \ - --object-path /org/freedesktop/login1/session/3 + --object-path /org/freedesktop/login1/session/45 -node /org/freedesktop/login1/session/3 { +node /org/freedesktop/login1/session/45 { interface org.freedesktop.login1.Session { methods: Terminate(); @@ -557,8 +751,9 @@ node /org/freedesktop/login1/session/3 { Lock(); Unlock(); SetIdleHint(in b idle); + SetLockedHint(in b locked); Kill(in s who, - in i signo); + in i signal_number); TakeControl(in b force); ReleaseControl(); TakeDevice(in u major, @@ -569,6 +764,9 @@ node /org/freedesktop/login1/session/3 { in u minor); PauseDeviceComplete(in u major, in u minor); + SetBrightness(in s subsystem, + in s name, + in u brightness); signals: PauseDevice(u major, u minor, @@ -579,40 +777,65 @@ node /org/freedesktop/login1/session/3 { Lock(); Unlock(); properties: - readonly s Id = '3'; - readonly (uo) User = (1000, '/org/freedesktop/login1/user/_1000'); - readonly s Name = 'test'; - readonly t Timestamp = 1389370644734067; - readonly t TimestampMonotonic = 72063381; - readonly u VTNr = 0; - readonly (so) Seat = ('', '/'); - readonly s TTY = ''; - readonly s Display = ''; - readonly b Remote = true; - readonly s RemoteHost = '129.174.150.217'; - readonly s RemoteUser = ''; - readonly s Service = 'sshd'; - readonly s Desktop = ''; - readonly s Scope = 'session-3.scope'; - readonly u Leader = 1854; - readonly u Audit = 3; - readonly s Type = 'tty'; - readonly s Class = 'user'; - readonly b Active = true; - readonly s State = 'active'; - readonly b IdleHint = false; - readonly t IdleSinceHint = 0; - readonly t IdleSinceHintMonotonic = 0; - }; - interface org.freedesktop.DBus.Properties { - }; - interface org.freedesktop.DBus.Peer { - }; - interface org.freedesktop.DBus.Introspectable { + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s Id = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly (uo) User = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s Name = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly t Timestamp = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly t TimestampMonotonic = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly u VTNr = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly (so) Seat = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s TTY = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s Display = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly b Remote = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s RemoteHost = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s RemoteUser = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s Service = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s Desktop = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s Scope = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly u Leader = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly u Audit = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s Type = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s Class = '...'; + readonly b Active = ...; + readonly s State = '...'; + readonly b IdleHint = ...; + readonly t IdleSinceHint = ...; + readonly t IdleSinceHintMonotonic = ...; + readonly b LockedHint = ...; }; + interface org.freedesktop.DBus.Peer { ... }; + interface org.freedesktop.DBus.Introspectable { ... }; + interface org.freedesktop.DBus.Properties { ... }; }; + + + + + + + + Methods diff --git a/man/org.freedesktop.machine1.xml b/man/org.freedesktop.machine1.xml index f26829ee45..1c9c41f04c 100644 --- a/man/org.freedesktop.machine1.xml +++ b/man/org.freedesktop.machine1.xml @@ -49,7 +49,7 @@ node /org/freedesktop/machine1 { GetMachineByPID(in u pid, out o machine); ListMachines(out a(ssso) machines); - ListImages(out a(ssbttto) machines); + ListImages(out a(ssbttto) images); CreateMachine(in s name, in ay id, in s service, @@ -82,10 +82,11 @@ node /org/freedesktop/machine1 { in s root_directory, in ai ifindices, out o path); + UnregisterMachine(in s name); + TerminateMachine(in s id); KillMachine(in s name, in s who, - in s signal); - TerminateMachine(in s id); + in i signal); GetMachineAddresses(in s name, out a(iay) addresses); GetMachineOSRelease(in s name, @@ -114,6 +115,10 @@ node /org/freedesktop/machine1 { CopyToMachine(in s name, in s source, in s destination); + OpenMachineRootDirectory(in s name, + out h fd); + GetMachineUIDShift(in s name, + out u shift); RemoveImage(in s name); RenameImage(in s name, in s new_name); @@ -122,16 +127,26 @@ node /org/freedesktop/machine1 { in b read_only); MarkImageReadOnly(in s name, in b read_only); + GetImageHostname(in s name, + out s hostname); + GetImageMachineID(in s name, + out ay id); + GetImageMachineInfo(in s name, + out a{ss} machine_info); + GetImageOSRelease(in s name, + out a{ss} os_release); SetPoolLimit(in t size); SetImageLimit(in s name, in t size); + CleanPool(in s mode, + out a(st) images); MapFromMachineUser(in s name, in u uid_inner, out u uid_outer); MapToMachineUser(in u uid_outer, out s machine_name, out o machine_path, - out u uid_inner; + out u uid_inner); MapFromMachineGroup(in s name, in u gid_inner, out u gid_outer); @@ -145,16 +160,16 @@ node /org/freedesktop/machine1 { MachineRemoved(s machine, o path); properties: - readonly s PoolPath = '/var/lib/machines'; - readonly t PoolUsage = 18446744070652059648; - readonly t PoolLimit = 2160721920; - }; - interface org.freedesktop.DBus.Properties { - }; - interface org.freedesktop.DBus.Peer { - }; - interface org.freedesktop.DBus.Introspectable { + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly s PoolPath = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly t PoolUsage = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly t PoolLimit = ...; }; + interface org.freedesktop.DBus.Peer { ... }; + interface org.freedesktop.DBus.Introspectable { ... }; + interface org.freedesktop.DBus.Properties { ... }; }; @@ -317,34 +332,61 @@ $ gdbus introspect --system \ --dest org.freedesktop.machine1 \ --object-path /org/freedesktop/machine1/machine/rawhide -node /org/freedesktop/machine1/machine/fedora_2dtree { +node /org/freedesktop/machine1/machine/rawhide { interface org.freedesktop.machine1.Machine { methods: Terminate(); Kill(in s who, - in s signal); + in i signal); GetAddresses(out a(iay) addresses); GetOSRelease(out a{ss} fields); - signals: + GetUIDShift(out u shift); + OpenPTY(out h pty, + out s pty_path); + OpenLogin(out h pty, + out s pty_path); + OpenShell(in s user, + in s path, + in as args, + in as environment, + out h pty, + out s pty_path); + BindMount(in s source, + in s destination, + in b read_only, + in b mkdir); + CopyFrom(in s source, + in s destination); + CopyTo(in s source, + in s destination); + OpenRootDirectory(out h fd); properties: - readonly s Name = 'fedora-tree'; - readonly ay Id = [0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]; - readonly t Timestamp = 1374193370484284; - readonly t TimestampMonotonic = 128247251308; - readonly s Service = 'nspawn'; - readonly s Unit = 'machine-fedora\\x2dtree.scope'; - readonly u Leader = 30046; - readonly s Class = 'container'; - readonly s RootDirectory = '/home/lennart/fedora-tree'; - readonly ai NetworkInterfaces = [7]; - readonly s State = 'running'; - }; - interface org.freedesktop.DBus.Properties { - }; - interface org.freedesktop.DBus.Peer { - }; - interface org.freedesktop.DBus.Introspectable { + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s Name = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly ay Id = [...]; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly t Timestamp = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly t TimestampMonotonic = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s Service = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s Unit = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly u Leader = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s Class = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s RootDirectory = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly ai NetworkInterfaces = [...]; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly s State = '...'; }; + interface org.freedesktop.DBus.Peer { ... }; + interface org.freedesktop.DBus.Introspectable { ... }; + interface org.freedesktop.DBus.Properties { ... }; }; diff --git a/man/org.freedesktop.resolve1.xml b/man/org.freedesktop.resolve1.xml index f0cf668f19..d150ee2a5f 100644 --- a/man/org.freedesktop.resolve1.xml +++ b/man/org.freedesktop.resolve1.xml @@ -87,40 +87,100 @@ node /org/freedesktop/resolve1 { out s canonical_type, out s canonical_domain, out t flags); - ResetStatistics(); GetLink(in i ifindex, out o path); SetLinkDNS(in i ifindex, in a(iay) addresses); SetLinkDomains(in i ifindex, in a(sb) domains); + SetLinkDefaultRoute(in i ifindex, + in b enable); SetLinkLLMNR(in i ifindex, in s mode); SetLinkMulticastDNS(in i ifindex, in s mode); + SetLinkDNSOverTLS(in i ifindex, + in s mode); SetLinkDNSSEC(in i ifindex, in s mode); SetLinkDNSSECNegativeTrustAnchors(in i ifindex, in as names); RevertLink(in i ifindex); + RegisterService(in s name, + in s name_template, + in s type, + in q service_port, + in q service_priority, + in q serwise_weight, + in aa{say} txt_datas, + out o service_path); + UnregisterService(in o service_path); + ResetStatistics(); + FlushCaches(); + ResetServerFeatures(); properties: - readonly s LLMNRHostname = 'delta'; - readonly a(iiay) DNS = [(0, 2, [0xac, 0x1f, 0x00, 0x01])]; - readonly a(isb) Domains = [(0, 'fritz.box', false)]; - readonly (tt) TransactionStatistics = (0, 846); - readonly (ttt) CacheStatistics = (55, 406, 439); - readonly (tttt) DNSSECStatistics = (0, 0, 0, 0); - readonly b DNSSECSupported = false; - }; - interface org.freedesktop.DBus.Peer { - }; - interface org.freedesktop.DBus.Introspectable { - }; - interface org.freedesktop.DBus.Properties { + readonly s LLMNRHostname = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly s LLMNR = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly s MulticastDNS = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly s DNSOverTLS = '...'; + readonly a(iiay) DNS = [...]; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly a(iiay) FallbackDNS = [...]; + readonly (iiay) CurrentDNSServer = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly a(isb) Domains = [...]; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly (tt) TransactionStatistics = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly (ttt) CacheStatistics = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly s DNSSEC = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly (tttt) DNSSECStatistics = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly b DNSSECSupported = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly as DNSSECNegativeTrustAnchors = ['...', ...]; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly s DNSStubListener = '...'; }; + interface org.freedesktop.DBus.Peer { ... }; + interface org.freedesktop.DBus.Introspectable { ... }; + interface org.freedesktop.DBus.Properties { ... }; }; + + + + + + + + + + + + + + + + + + + + + + + + + + + + Methods @@ -165,7 +225,7 @@ node /org/freedesktop/resolve1 { ANY). Finally, a flags field may be passed in to alter behaviour of the look-up (see below). On return an array of RR items is returned. Each array entry consists of the network interface index the RR was discovered on, the type and class field of the RR found, and a byte array of the raw - RR discovered. The raw RR data starts with the RR's domain name, in the original casing, followed + RR discovered. The raw RR data starts with the RR's domain name, in the original casing, followed by the RR type, class, TTL and RDATA, in the binary format documented in RFC 1035. For RRs that support name compression in the payload (such as MX or PTR), the compression is expanded in the returned @@ -185,7 +245,7 @@ node /org/freedesktop/resolve1 { name, a service type and a service domain. The call may be invoked in three different modes: - To resolve a DNS-SD service, specify the service name (e.g. Lennart's + To resolve a DNS-SD service, specify the service name (e.g. Lennart's Files), the service type (e.g. _webdav._tcp) and the domain to search in (e.g. local) in the three service parameters. The service name must be in UTF-8 format, and no IDNA conversion is applied to it in this mode (as mandated by the DNS-SD @@ -351,7 +411,7 @@ node /org/freedesktop/resolve1 { LLMNRHostname contains the hostname currently exposed on the network via LLMNR. It usually follows the system hostname as may be queried via - gethostname3, + gethostname3, but may differ if a conflict is detected on the network. DNS contains an array containing all DNS servers currently used by @@ -417,33 +477,75 @@ $ gdbus introspect --system \ node /org/freedesktop/resolve1/link/_34 { interface org.freedesktop.resolve1.Link { methods: - SetDNS(in a(iay) arg_0); - SetDomains(in a(sb) arg_0); - SetLLMNR(in s arg_0); - SetMulticastDNS(in s arg_0); - SetDNSSEC(in s arg_0); - SetDNSSECNegativeTrustAnchors(in as arg_0); + SetDNS(in a(iay) addresses); + SetDomains(in a(sb) domains); + SetDefaultRoute(in b enable); + SetLLMNR(in s mode); + SetMulticastDNS(in s mode); + SetDNSOverTLS(in s mode); + SetDNSSEC(in s mode); + SetDNSSECNegativeTrustAnchors(in as names); Revert(); - signals: properties: - readonly t ScopesMask = 6; - readonly a(iay) DNS = []; - readonly a(sb) Domains = []; - readonly s LLMNR = 'yes'; - readonly s MulticastDNS = 'no'; - readonly s DNSSEC = ''; - readonly as DNSSECNegativeTrustAnchors = []; - readonly b DNSSECSupported = true; - }; - interface org.freedesktop.DBus.Peer { - }; - interface org.freedesktop.DBus.Introspectable { - }; - interface org.freedesktop.DBus.Properties { + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly t ScopesMask = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly a(iay) DNS = [...]; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly (iay) CurrentDNSServer = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly a(sb) Domains = [...]; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly b DefaultRoute = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly s LLMNR = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly s MulticastDNS = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly s DNSOverTLS = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly s DNSSEC = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly as DNSSECNegativeTrustAnchors = ['...', ...]; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly b DNSSECSupported = ...; }; + interface org.freedesktop.DBus.Peer { ... }; + interface org.freedesktop.DBus.Introspectable { ... }; + interface org.freedesktop.DBus.Properties { ... }; }; + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + For each Linux network interface a "Link" object is created, which exposes per-link DNS configuration and state. Use GetLink() on the Manager interface to retrieve the object path for a link object given the network interface index (see above). diff --git a/man/org.freedesktop.timedate1.xml b/man/org.freedesktop.timedate1.xml index 65a5f5b2fb..8852512906 100644 --- a/man/org.freedesktop.timedate1.xml +++ b/man/org.freedesktop.timedate1.xml @@ -44,29 +44,50 @@ node /org/freedesktop/timedate1 { methods: SetTime(in x usec_utc, in b relative, - in b user_interaction); + in b interactive); SetTimezone(in s timezone, - in b user_interaction); + in b interactive); SetLocalRTC(in b local_rtc, in b fix_system, - in b user_interaction); + in b interactive); SetNTP(in b use_ntp, - in b user_interaction); - signals: + in b interactive); + ListTimezones(out as timezones); properties: - readonly s Timezone = 'Europe/Berlin'; - readonly b LocalRTC = false; - readonly b NTP = true; - }; - interface org.freedesktop.DBus.Properties { - }; - interface org.freedesktop.DBus.Introspectable { - }; - interface org.freedesktop.DBus.Peer { + readonly s Timezone = '...'; + readonly b LocalRTC = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly b CanNTP = ...; + readonly b NTP = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly b NTPSynchronized = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly t TimeUSec = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly t RTCTimeUSec = ...; }; + interface org.freedesktop.DBus.Peer { ... }; + interface org.freedesktop.DBus.Introspectable { ... }; + interface org.freedesktop.DBus.Properties { ... }; }; + + + + + + + + + + + + + + + + Methods @@ -100,7 +121,7 @@ node /org/freedesktop/timedate1 { time settings using this interface is authenticated via PolicyKit. Note that this service will not inform you about system time changes. Use - timerfd3 + timerfd3 with CLOCK_REALTIME and TFD_TIMER_CANCEL_ON_SET for that. From 8024ac43b9085702b7be38ead7c14def283b1f22 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sat, 11 Apr 2020 17:08:04 +0200 Subject: [PATCH 20/26] man: various tweaks to org.freedesktop.hostname1(5) Co-Authored-By: Daan De Meyer --- man/org.freedesktop.hostname1.xml | 83 ++++++++++++++++--------------- 1 file changed, 42 insertions(+), 41 deletions(-) diff --git a/man/org.freedesktop.hostname1.xml b/man/org.freedesktop.hostname1.xml index b9522a3a08..fc7b32a83b 100644 --- a/man/org.freedesktop.hostname1.xml +++ b/man/org.freedesktop.hostname1.xml @@ -29,7 +29,7 @@ systemd-hostnamed.service8 - is a system service that can be used to control the host name and related machine meta data from user + is a system service that can be used to control the hostname and related machine metadata from user programs. This page describes the hostname semantics and the D-Bus interface. @@ -121,7 +121,7 @@ node /org/freedesktop/hostname1 { - Whenever the hostname or other meta data is changed via the daemon, + Whenever the hostname or other metadata is changed via the daemon, PropertyChanged signals are sent out to subscribed clients. Changing a hostname using this interface is authenticated via PolicyKit. @@ -129,73 +129,73 @@ node /org/freedesktop/hostname1 { Semantics - The static (configured) host name is the one configured in + The static (configured) hostname is the one configured in /etc/hostname. It is chosen by the local user. It is not always in sync with the current hostname as returned by the gethostname3 - system call. If no host name is configured this property will be the empty string. Setting this property - to the empty string will remove /etc/hostname. This hostname should be an + system call. If no hostname is configured this property will be the empty string. Setting this property + to the empty string will remove /etc/hostname. This property should be an internet-style hostname, 7-bit lowercase ASCII, no special chars/spaces. - The transient (dynamic) host name is the one configured via the kernel's + The transient (dynamic) hostname is the one configured via the kernel's sethostname3. - It can be different from the static hostname in case DHCP or mDNS have been configured to change the name + It can be different from the static hostname if DHCP or mDNS have been configured to change the name based on network information. This property is never empty. If no hostname is set this will default to &FALLBACK_HOSTNAME; (configurable at compilation time). Setting this property to the - empty string will reset the dynamic hostname to the static host name. If no static host name is - configured the dynamic host name will be reset to &FALLBACK_HOSTNAME;. This hostname + empty string will reset the dynamic hostname to the static hostname. If no static hostname is + configured the dynamic hostname will be reset to &FALLBACK_HOSTNAME;. This property should be an internet-style hostname, 7-bit lowercase ASCII, no special chars/spaces. - The pretty host name is a free-form UTF-8 host name for presentation to the + The pretty hostname is a free-form UTF-8 hostname for presentation to the user. User interfaces should ensure that the pretty hostname and the static hostname stay in sync. I.e. when the former is Lennart’s Computer the latter should be - lennarts-computer. If no pretty host name is set this setting will be the empty + lennarts-computer. If no pretty hostname is set this setting will be the empty string. Applications should then find a suitable fallback, such as the dynamic hostname. The icon name is a name following the XDG icon naming spec. If not set, information such as the chassis type (see below) is used to find a suitable fallback icon name (i.e. computer-laptop vs. computer-desktop is picked based on the - chassis information). If no such data is available, returns the empty string. In that case an application + chassis information). If no such data is available, the empty string is returned. In that case an application should fall back to a replacement icon, for example computer. If this property is set - to the empty string, this automatic fallback name selection is enabled again. + to the empty string, the automatic fallback name selection is enabled again. - The chassis type should be one of the following that are currently defined: + The chassis type should be one of the currently defined chassis types: desktop, laptop, server, tablet, handset, as well as the special chassis types vm and container for virtualized systems. Note that in most cases the chassis type will be determined automatically from DMI/SMBIOS/ACPI firmware information. Writing to - this setting is hence useful only to override misdetected chassis types, or configure a chassis type if - none could be auto-detected. Set this property to the empty string to reenable the automatic detection of + this setting is hence useful only to override misdetected chassis types, or to configure the chassis type if + it could not be auto-detected. Set this property to the empty string to reenable the automatic detection of the chassis type from firmware information. - A client which wants to change the local host name for DHCP/mDNS should invoke + A client that wants to change the local hostname for DHCP/mDNS should invoke SetHostname("newname", false) as soon as the name is available and afterwards reset it via SetHostname(""). Note that systemd-hostnamed starts only on request and terminates after a short idle period. This effectively means that PropertyChanged messages are not sent out for changes made directly on the files (as in: administrator edits the files with vi). This is - actually intended behavior: manual configuration changes should require manual reloading of them. + the intended behavior: manual configuration changes should require manual reloading. - The transient (dynamic) hostname directly maps to the kernel hostname. This hostname should be - assumed to be highly dynamic, and hence should be watched directly, without involving - PropertyChanged messages from systemd-hostnamed. For that, open - /proc/sys/kernel/hostname and + The transient (dynamic) hostname maps directly to the kernel hostname. This hostname should be + assumed to be highly dynamic, and hence should be watched directly, without depending on + PropertyChanged messages from systemd-hostnamed. To accomplish + this, open /proc/sys/kernel/hostname and poll3 for SIGHUP which is triggered by the kernel every time the hostname changes. Again: this is special for the transient (dynamic) hostname, and does not apply to the configured (fixed) hostname. - Applications may bypass the daemon to read the hostname data if notifications of host name changes + Applications may read the hostname data directly if hostname change notifications are not necessary. Use gethostname3, /etc/hostname (possibly with per-distribution fallbacks), and machine-info3 for that. For more information on these files and syscalls see the respective man pages. - The user_interaction boolean parameters can be used to control whether PolicyKit should - interactively ask the user for authentication credentials if it needs to. + The user_interaction boolean parameters can be used to control whether PolicyKit + should interactively ask the user for authentication credentials if required. The PolicyKit action for SetHostname() is org.freedesktop.hostname1.set-hostname. For @@ -204,20 +204,20 @@ node /org/freedesktop/hostname1 { SetIconName() and SetChassis() it is org.freedesktop.hostname1.set-machine-info. - Here are three examples how the pretty hostname and the icon name should be used: + Here are three examples show how the pretty hostname and the icon name should be used: - When registering DNS-SD services: use the pretty host name in the service name, and + When registering DNS-SD services: use the pretty hostname in the service name, and pass the icon name in the TXT data, if there is an icon name. Browsing clients can then show the server - icon on each service. Especially useful for WebDAV stuff. Similar for UPnP media - sharing. + icon on each service. This is especially useful for WebDAV applications or UPnP media sharing. + - Set the bluetooth name to the pretty host name. + Set the bluetooth name to the pretty hostname. When your file browser has a "Computer" icon, replace the name with the pretty hostname if set, and the icon with the icon name, if it is set. To properly handle name lookups with changing local hostnames without having to edit - /etc/hosts for them, we recommend using systemd-hostnamed in + /etc/hosts, we recommend using systemd-hostnamed in combination with nss-myhostname3. @@ -225,13 +225,13 @@ node /org/freedesktop/hostname1 { name: Generate a single DNS label only, not an FQDN. That means no dots allowed. Strip them, - or replace them by -. + or replace them with -. - It's probably safer not to use any non-ASCII chars, even if DNS allows this in some way + It's probably safer to not use any non-ASCII chars, even if DNS allows this in some way these days. In fact, restrict your charset to a-zA-Z0-9 and -. Strip other chars, or try to replace them in some smart way with chars from this set, for example - ä → ae, and use - as replacement for all kinds - of punctuation chars or spaces. + ä → ae, and use - as the replacement for all + punctuation characters and whitespace. Try to avoid creating repeated -, as well as - as the first or last char. @@ -239,17 +239,18 @@ node /org/freedesktop/hostname1 { Limit the hostname to 63 chars, which is the length of a DNS label. If after stripping special chars the empty string is the result, you can pass this - as-is to systemd-hostnamed in which case it will automatically make - &FALLBACK_HOSTNAME; out of this. + as-is to systemd-hostnamed in which case it will automatically use + &FALLBACK_HOSTNAME;. - It probably is a good idea to replace uppercase by lowercase chars. + Uppercase charaacters should be replaced with their lowercase equivalents. + Note that while systemd-hostnamed applies some checks to the hostname you pass they are much looser than the recommendations above. For example, systemd-hostnamed - will also accept _ in the hostname, but I'd recommend not using this to avoid clashes + will also accept _ in the hostname, but we recommend not using this to avoid clashes with DNS-SD service types. Also systemd-hostnamed allows longer hostnames, but - because of the DNS label limitations, I'd recommend not making use of this. + because of the DNS label limitations, we recommend not making use of this. Here are a couple of example conversions: @@ -262,7 +263,7 @@ node /org/freedesktop/hostname1 { ...zack!!! zack!... → zack-zack - Oh, and of course, an already valid internet hostname label you enter and pass through this + Of course, an already valid internet hostname label you enter and pass through this conversion should stay unmodified, so that users have direct control of it, if they want -- by simply ignoring the fact that the pretty hostname is pretty and just edit it as if it was the normal internet name. From b441a1d4bc3102bf7571b53f9f27f5f1e36e7548 Mon Sep 17 00:00:00 2001 From: Daan De Meyer Date: Sun, 12 Apr 2020 19:39:51 +0200 Subject: [PATCH 21/26] man: review of import1(5) --- man/org.freedesktop.import1.xml | 87 +++++++++++++++++---------------- 1 file changed, 44 insertions(+), 43 deletions(-) diff --git a/man/org.freedesktop.import1.xml b/man/org.freedesktop.import1.xml index 6a628f4671..71469a9c5e 100644 --- a/man/org.freedesktop.import1.xml +++ b/man/org.freedesktop.import1.xml @@ -25,18 +25,18 @@ systemd-importd.service8 - is a system service which may be used to import, export and download additional system images, for - running them as local containers using tools such as - systemd-nspawn1 The - service is used as backend for machinectl pull-raw and machinectl - pull-tar and related commands. - This page describes the D-Bus interface. + is a system service which may be used to import, export and download additional system images. These + images can be used by tools such as + systemd-nspawn1 + to run local containers. The service is used as the backend for machinectl pull-raw, + machinectl pull-tar and related commands. This page describes the D-Bus interface. + Note that systemd-importd.service8 is mostly a small companion service for systemd-machined.service8. - Many operations to manipulate local container and VM images are hence available via the systemd-machined bus API, c.f. + Many operations to manipulate local container and VM images are hence available via the systemd-machined D-Bus API, c.f. org.freedesktop.machine1.service5. @@ -116,8 +116,8 @@ node /org/freedesktop/import1 { ImportTar() and ImportRaw() import a system image and place it into /var/lib/machines/. The first argument should be a file descriptor - (opened for reading) referring to the tar or raw file to import. It should reference either a file on - disk or a pipe or socket. When ImportTar() is used the file descriptor should + (opened for reading) referring to the tar or raw file to import. It should reference a file on disk, + a pipe or a socket. When ImportTar() is used the file descriptor should refer to a tar file, optionally compressed with gzip1, bzip21, @@ -126,58 +126,59 @@ node /org/freedesktop/import1 { systemd-importd will detect the used compression scheme (if any) automatically. When ImportRaw() is used the file descriptor should refer to a raw or qcow2 disk image containing an MBR or GPT disk label, also optionally compressed with gzip, bzip2 or xz. In either case, - if the file is specified as file descriptor on disk, progress information is generated for the import - operation (since the size on disk is known then), if a socket or pipe is specified this is not + if the file is specified as a file descriptor on disk, progress information is generated for the import + operation (as in that case we know the total size on disk). If a socket or pipe is specified, progress information is not available. The file descriptor argument is followed by a local name for the image. This should be a name suitable as a hostname and will be used to name the imported image below - /var/lib/machines. A tar import is placed as directory tree or + /var/lib/machines. A tar import is placed as a directory tree or a btrfs8 - subvolume below /var/lib/machines/, under the name specified with no suffix - appended. A raw import is placed as file in /var/lib/machines/ with the - .raw suffix appended. The argument controls whether any - pre-existing image with the same name shall be removed for the operation. If true, it is removed, if - false the operation fails on a name conflict. Finally, the argument controls - whether to create a writable or read-only image. The two calls return immediately after invocation, + subvolume below /var/lib/machines/ under the specified name with no suffix + appended. A raw import is placed as a file in /var/lib/machines/ with the + .raw suffix appended. If the argument is true, any + pre-existing image with the same name is removed before starting the operation. Otherwise, the + operation fails if an image with the same name already exists. Finally, the + argument controls + whether to create a writable or read-only image. Both methods return immediately after starting the import, with the import transfer ongoing. They return a pair of transfer identifier and object path, which may - be used to retrieve progress information about the transfer, or cancel it. The transfer identifier is a + be used to retrieve progress information about the transfer or to cancel it. The transfer identifier is a simple numeric identifier, the object path references an org.freedesktop.import1.Transfer object, see below. Listen for a - TransferRemoved signal for the transfer ID it order to detect when a transfer is + TransferRemoved signal for the transfer ID in order to detect when a transfer is complete. The returned transfer object is useful to determine the current progress or log output of the ongoing import operation. ExportTar() and ExportRaw() implement the reverse operation, and may be used to export a system image in order to place it in a tar or raw image. They - take the machine name to export as first parameter, followed by a file descriptor (opened for writing) + take the machine name to export as their first parameter, followed by a file descriptor (opened for writing) where the tar or raw file will be written. It may either reference a file on disk or a pipe/socket. The third argument specifies in which compression format to write the image. It takes one of uncompressed, xz, bzip2 or gzip, depending on which compression scheme is required. The image written to the specified file descriptor will be a tar file in case of ExportTar() or a raw disk image in case of ExportRaw(). Note that currently raw disk images may not be - exported as tar files, and vice versa, however this restriction might be lifted eventually. The call - returns a transfer identifier and object path for canceling or tracking the export operation, similar - to ImportTar() or ImportRaw() described above. + exported as tar files, and vice versa. This restriction might be lifted eventually. The call + returns a transfer identifier and object path for cancelling or tracking the export operation, similar + to ImportTar() or ImportRaw() as described above. PullTar() and PullRaw() may be used to download, verify - and import a system image from a web site. They take an URL argument, that should reference a tar or + and import a system image from a URL. They take an URL argument which should point to a tar or raw file on the http:// or https:// protocols, possibly compressed with xz, bzip2 or gzip. The second argument is a local name for the image. It should be - suitable as hostname, similar to the matching argument of the ImportTar() and - ImportRaw() calls above. The third argument indicates the verification mode for + suitable as a hostname, similar to the matching argument of the ImportTar() and + ImportRaw() methods above. The third argument indicates the verification mode for the image. It may be one of no, checksum, - signature. no turns of any kind of verification of the image; + signature. no turns off any kind of verification of the image; checksum looks for a SHA256SUM file next to the downloaded - image, and verifies any SHA256 hash value in that file again the image; signature + image and verifies any SHA256 hash value in that file against the image; signature does the same but also tries to authenticate the SHA256SUM file via gpg8 first. The last argument indicates whether to replace a possibly pre-existing image with the same local name (if true), or whether to fail (if false). Like the import - and export calls above these calls return a pair of transfer identifier and object path for the ongoing + and export calls above, these calls return a pair of transfer identifier and object path for the ongoing download. ListTransfers() returns a list of ongoing import, export or download - operations, as created with the six calls described above. It returns an array of structures, which + operations as created with the six calls described above. It returns an array of structures which consist of the numeric transfer identifier, a string indicating the operation (one of import-tar, import-raw, export-tar, export-raw, pull-tar or pull-raw), a string @@ -187,18 +188,18 @@ node /org/freedesktop/import1 { the transfer object path. CancelTransfer() may be used to cancel an ongoing import, export or download - operation. Simply specify the transfer identifier to cancel. + operation. Simply specify the transfer identifier to cancel the ongoing operation. Signals - The TransferNew signal is generated each time a new transfer is added with - the import, export or download calls described above. It carries the transfer ID and object path just - created. + The TransferNew signal is generated each time a new transfer is started with + the import, export or download calls described above. It carries the transfer ID and object path that + have just been created. - The TransferRemoved signal is sent each time a transfer was completed, - canceled or failed. It also carries the transfer ID and object path, followed by a string indicating + The TransferRemoved signal is sent each time a transfer finishes, + is canceled or fails. It also carries the transfer ID and object path, followed by a string indicating the result of the operation, which is one of done (on success), canceled or failed. @@ -255,17 +256,17 @@ node /org/freedesktop/import1/transfer/_1 { The Id property exposes the numeric transfer ID of the transfer object. - The Local, Remote, Type properties + The Local, Remote and Type properties expose the local container name of this transfer, the remote source (in case of download: the URL, in - case of import/export a string describing the file descriptor passed in), and the type of operation - (see the Manager's ListTransfer() call above for an explanation of the possible + case of import/export: a string describing the file descriptor passed in), and the type of operation + (see the Manager's ListTransfer() method above for an explanation of the possible values). - The Verify property exposes the selected verification setting, and is only + The Verify property exposes the selected verification setting and is only defined for download operations (see above). - The Progress property exposes the current progress of the transfer, as a value - between 0.0 and 1.0. To show a progress bar on screen it recommend to query this value in regular + The Progress property exposes the current progress of the transfer as a value + between 0.0 and 1.0. To show a progress bar on screen we recommend to query this value in regular intervals, for example every 500 ms or so. From 7592871e26554fb67baf5e18fe4fd9b053224490 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sun, 12 Apr 2020 15:05:08 +0200 Subject: [PATCH 22/26] =?UTF-8?q?man:=20login1(5)=20=E2=80=94=20fix=20mark?= =?UTF-8?q?up=20and=20fill=20in=20the=20missing=20descriptions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Partially fixes #1042. --- man/org.freedesktop.login1.xml | 416 ++++++++++++++++----------------- 1 file changed, 204 insertions(+), 212 deletions(-) diff --git a/man/org.freedesktop.login1.xml b/man/org.freedesktop.login1.xml index 1c6134f9a6..ff944b2d1c 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. From c4b01de48208279809e7a152c47530d484f8b3d3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sun, 12 Apr 2020 16:24:14 +0200 Subject: [PATCH 23/26] =?UTF-8?q?man:=20locale1(5)=20=E2=80=94=20adjust=20?= =?UTF-8?q?page=20structure=20and=20fill=20in=20the=20missing=20parts?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- man/org.freedesktop.locale1.xml | 67 ++++++++++++++++++--------------- 1 file changed, 37 insertions(+), 30 deletions(-) diff --git a/man/org.freedesktop.locale1.xml b/man/org.freedesktop.locale1.xml index 7b2bf2870f..94c96456f9 100644 --- a/man/org.freedesktop.locale1.xml +++ b/man/org.freedesktop.locale1.xml @@ -69,37 +69,13 @@ node /org/freedesktop/locale1 { }; - - - - - - - - - - - - - - - The system locale consists of an array of environment-variable-assignment-like strings. The - following strings are known: LANG=, LC_CTYPE=, - LC_NUMERIC=, LC_TIME=, LC_COLLATE=, - LC_MONETARY=, LC_MESSAGES=, LC_PAPER=, - LC_NAME=, LC_ADDRESS=, LC_TELEPHONE=, - LC_MEASUREMENT=, LC_IDENTIFICATION=. - - Whenever the system locale or keymap is changed via the daemon PropertyChanged - signals are sent out to which clients can subscribe. - Methods If you set a new system locale all old system locale settings will be dropped, and the new settings will be saved to disk. It will also be passed to the system manager, and subsequently started - daemons will inherit the new system locale from it. Note that already running daemons will not learn - about the new system locale. + daemons will inherit the new system locale. Note that already running daemons will not learn about the + new value. The SetVConsoleKeyboard() call may be used to set the key mapping on the virtual console. Similarly, SetX11Keyboard() may be used to set the default key @@ -110,7 +86,7 @@ node /org/freedesktop/locale1 { sessions. The boolean argument convert may be set to optionally convert the console - keyboard configuration to X11 keyboard mappings, resp. vice versa. If true and + keyboard configuration to X11 keyboard mappings and vice versa. If true and SetVConsoleKeyboard() is used the nearest X11 keyboard setting for the chosen console setting is set. If true and SetX11Keyboard() is used, the nearest console keyboard setting for the chosen X11 setting is set. Usually it is hence sufficient to call one of the @@ -122,14 +98,45 @@ node /org/freedesktop/locale1 { Use the empty string for the keymap parameters you wish not to set. + The interactive boolean parameters can be used to control whether PolicyKit + should interactively ask the user for authentication credentials if it needs to. + + + + Signals + + Whenever the system locale or keymap is changed via the daemon, + PropertyChanged signals are sent out to which clients can subscribe. + + + + Properties + + The system locale is shown in the Locale property. It is an array containing + environment-variable-assignment-like strings. The following strings are known: + LANG=, LC_CTYPE=, LC_NUMERIC=, + LC_TIME=, LC_COLLATE=, LC_MONETARY=, + LC_MESSAGES=, LC_PAPER=, LC_NAME=, + LC_ADDRESS=, LC_TELEPHONE=, LC_MEASUREMENT=, + LC_IDENTIFICATION=. + + The X11Layout, X11Model, X11Variant, and + X11Options properties show values configurable with + SetX11Keyboard() described above (or SetVConsoleKeyboard() + with convert=true). The VConsoleKeymap and + VConsoleKeymapToggle propries sohw values configurable with + SetVConsoleKeyboard() (or SetX11Keyboard() with + convert=true). + + + + Security + Changing the system locale or keymap using this interface is authenticated via PolicyKit. The PolicyKit action for SetLocale() is org.freedesktop.locale1.set-locale. The PolicyKit action for SetX11Keyboard() and SetVConsoleKeyboard() is org.freedesktop.locale1.set-keyboard. - - The user_interaction boolean parameters can be used to control whether - PolicyKit should interactively ask the user for authentication credentials if it needs to. From b9a1ee32c4f2ebe0a21f8348b9de344b23c58711 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sun, 12 Apr 2020 18:43:28 +0200 Subject: [PATCH 24/26] shared/reboot-util: indentation update --- src/shared/reboot-util.c | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/src/shared/reboot-util.c b/src/shared/reboot-util.c index 5d76299179..888f685aed 100644 --- a/src/shared/reboot-util.c +++ b/src/shared/reboot-util.c @@ -55,12 +55,12 @@ int read_reboot_parameter(char **parameter) { int reboot_with_parameter(RebootFlags flags) { int r; - /* Reboots the system with a parameter that is read from /run/systemd/reboot-param. Returns 0 if REBOOT_DRY_RUN - * was set and the actual reboot operation was hence skipped. If REBOOT_FALLBACK is set and the reboot with - * parameter doesn't work out a fallback to classic reboot() is attempted. If REBOOT_FALLBACK is not set, 0 is - * returned instead, which should be considered indication for the caller to fall back to reboot() on its own, - * or somehow else deal with this. If REBOOT_LOG is specified will log about what it is going to do, as well as - * all errors. */ + /* Reboots the system with a parameter that is read from /run/systemd/reboot-param. Returns 0 if + * REBOOT_DRY_RUN was set and the actual reboot operation was hence skipped. If REBOOT_FALLBACK is + * set and the reboot with parameter doesn't work out a fallback to classic reboot() is attempted. If + * REBOOT_FALLBACK is not set, 0 is returned instead, which should be considered indication for the + * caller to fall back to reboot() on its own, or somehow else deal with this. If REBOOT_LOG is + * specified will log about what it is going to do, as well as all errors. */ if (detect_container() == 0) { _cleanup_free_ char *parameter = NULL; @@ -71,7 +71,6 @@ int reboot_with_parameter(RebootFlags flags) { "Failed to read reboot parameter file, ignoring: %m"); if (!isempty(parameter)) { - log_full(flags & REBOOT_LOG ? LOG_INFO : LOG_DEBUG, "Rebooting with argument '%s'.", parameter); From ae53ea522600b1fc9a25347632299048f4f4c600 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sun, 12 Apr 2020 19:14:20 +0200 Subject: [PATCH 25/26] man: update description of polkit rules for systemd1 Fixes #2562. v2: the erroneous part about CAP_SYS_ADMIN is removed --- man/org.freedesktop.systemd1.xml | 41 ++++++++++++++++++++++++-------- 1 file changed, 31 insertions(+), 10 deletions(-) diff --git a/man/org.freedesktop.systemd1.xml b/man/org.freedesktop.systemd1.xml index 1f0d1818ca..a3b86d3f1c 100644 --- a/man/org.freedesktop.systemd1.xml +++ b/man/org.freedesktop.systemd1.xml @@ -242,14 +242,6 @@ node /org/freedesktop/systemd1 { }; - - Security - - Read access is generally granted to all clients, but changes may only be made by privileged - clients. PolicyKit is not used by this service, and access is controlled exclusively via the D-Bus - policy. - - Methods @@ -487,7 +479,6 @@ node /org/freedesktop/systemd1 { url="http://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/">New Control Group Interface for more information how to make use of this functionality for resource control purposes. - @@ -620,6 +611,26 @@ node /org/freedesktop/systemd1 { appended to /sys/fs/cgroup/systemd easily. This value will be set to the empty string for the host instance, and some other string for container instances + + + Security + + Read access is generally granted to all clients. Additionally, for unprivileged clients, some + operations are allowed through the PolicyKit privilege system. Operations which modify unit state + (StartUnit(), StopUnit(), KillUnit(), + RestartUnit() and similar, SetProperty) require + org.freedesktop.systemd1.manage-units. Operations which modify unit file + enablement state (EnableUnitFiles(), DisableUnitFiles(), + ReenableUnitFiles(), LinkUnitFiles(), + PresetUnitFiles, MaskUnitFiles, and similar) require + org.freedesktop.systemd1.manage-unit-files). Operations which modify the + exported environment ( SetEnvironment(), UnsetEnvironment(), + UnsetAndSetEnvironment()) require + org.freedesktop.systemd1.set-environment. Reload() + and Reexecute() require + org.freedesktop.systemd1.reload-daemon. + + @@ -886,7 +897,7 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice { Conditions contains all configured conditions of the unit. For each condition five fields are given: condition type (e.g. ConditionPathExists), whether the condition is a trigger condition, whether the condition is reversed, the right hand side of the - condtion (e.g. the path in case of ConditionPathExists), and the status. The status + condition (e.g. the path in case of ConditionPathExists), and the status. The status can be 0, in which case the condition hasn't been checked yet, a positive value, in which case the condition passed, or a negative value, in which case the condition failed. Currently only 0, +1, and -1 are used, but additional values may be used in the future, retaining the meaning of @@ -900,6 +911,16 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice { Transient contains a boolean that indicates whether the unit was created as transient unit (i.e. via CreateTransientUnit() on the manager object) + + + Security + + Similarly to methods on the Manager object, read-only access is + allowed for everyone. All operations are allowed for clients with the + CAP_SYS_ADMIN capability or when the + org.freedesktop.systemd1.manage-units privilege is granted by + PolicyKit. + From ca264f7d96df3c33ad808b5ca4c4fc8acadc0067 Mon Sep 17 00:00:00 2001 From: Daan De Meyer Date: Tue, 14 Apr 2020 13:43:11 +0200 Subject: [PATCH 26/26] man: fixes from online review Also includes the issues pointed out by @boucman. --- man/org.freedesktop.locale1.xml | 18 +-- man/org.freedesktop.login1.xml | 228 +++++++++++++++--------------- man/org.freedesktop.machine1.xml | 124 ++++++++-------- man/org.freedesktop.resolve1.xml | 211 ++++++++++++++------------- man/org.freedesktop.systemd1.xml | 83 ++++++----- man/org.freedesktop.timedate1.xml | 20 +-- man/systemd-hostnamed.service.xml | 10 +- man/systemd-localed.service.xml | 2 +- man/systemd-logind.service.xml | 4 +- man/systemd-machined.service.xml | 2 +- 10 files changed, 349 insertions(+), 353 deletions(-) diff --git a/man/org.freedesktop.locale1.xml b/man/org.freedesktop.locale1.xml index 94c96456f9..12a82c1db5 100644 --- a/man/org.freedesktop.locale1.xml +++ b/man/org.freedesktop.locale1.xml @@ -72,24 +72,24 @@ node /org/freedesktop/locale1 { Methods - If you set a new system locale all old system locale settings will be dropped, and the new - settings will be saved to disk. It will also be passed to the system manager, and subsequently started + If you set a new system locale all old system locale settings will be dropped and the new + settings will be saved to disk. The locale will also be passed to the system manager, and subsequently started daemons will inherit the new system locale. Note that already running daemons will not learn about the new value. - The SetVConsoleKeyboard() call may be used to set the key mapping on the + The SetVConsoleKeyboard() call may be used to set the key mapping for the virtual console. Similarly, SetX11Keyboard() may be used to set the default key - mapping of the X11 servers. + mapping of any X11 servers. - Note that SetVConsoleKeyboard() instantly applies the new keymapping to the + Note that SetVConsoleKeyboard() instantly applies the new key mapping to the console, while SetX11Keyboard() simply sets a default that may be used by later sessions. The boolean argument convert may be set to optionally convert the console keyboard configuration to X11 keyboard mappings and vice versa. If true and - SetVConsoleKeyboard() is used the nearest X11 keyboard setting for the chosen + SetVConsoleKeyboard() is used, the nearest X11 keyboard setting for the chosen console setting is set. If true and SetX11Keyboard() is used, the nearest console - keyboard setting for the chosen X11 setting is set. Usually it is hence sufficient to call one of the + keyboard setting for the chosen X11 setting is set. Hence, it is usually sufficient to call only one of the two functions. For graphical UIs that need to set the system keyboard mapping simply invoke @@ -99,7 +99,7 @@ node /org/freedesktop/locale1 { Use the empty string for the keymap parameters you wish not to set. The interactive boolean parameters can be used to control whether PolicyKit - should interactively ask the user for authentication credentials if it needs to. + should interactively ask the user for authentication credentials if required. @@ -124,7 +124,7 @@ node /org/freedesktop/locale1 { X11Options properties show values configurable with SetX11Keyboard() described above (or SetVConsoleKeyboard() with convert=true). The VConsoleKeymap and - VConsoleKeymapToggle propries sohw values configurable with + VConsoleKeymapToggle properties show values configurable with SetVConsoleKeyboard() (or SetX11Keyboard() with convert=true). diff --git a/man/org.freedesktop.login1.xml b/man/org.freedesktop.login1.xml index ff944b2d1c..84dded3849 100644 --- a/man/org.freedesktop.login1.xml +++ b/man/org.freedesktop.login1.xml @@ -24,11 +24,11 @@ Introduction systemd-logind.service8 - is a system service that keeps track of user logins and seats in various ways. + is a system service that keeps track of user logins and seats. The daemon provides both a C library interface as well as a D-Bus interface. The library interface may be used to introspect and watch the state of user logins and seats. The bus interface provides the - same, but in addition may also be used to make changes to system state. For more information please + same functionality but in addition may also be used to make changes to the system state. For more information please consult sd-login3. @@ -244,19 +244,19 @@ node /org/freedesktop/login1 { GetUserByPID() get the session/user object the specified PID belongs to if there is any. - ListSessions() returns an array with all current sessions. The structures in + ListSessions() returns an array of all current sessions. The structures in the array consist of the following fields: session id, user id, user name, seat id, session object - path. If a session does not have a seat attached the seat id field will be an empty string. + path. If a session does not have a seat attached, the seat id field will be an empty string. - ListUsers() returns an array with all currently logged in users. The + ListUsers() returns an array of all currently logged in users. The structures in the array consist of the following fields: user id, user name, user object path. - ListSeats() returns an array with all currently available seats. The + ListSeats() returns an array of 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 + ListInhibitors() lists all currently active inhibitors. It returns an array of structures consisting of what, who, why, - mode, user ID uid, and process ID pid. + mode, uid (user ID), and pid (process ID). CreateSession() and ReleaseSession() may be used to open or close login sessions. These calls should never be invoked directly by @@ -273,8 +273,8 @@ node /org/freedesktop/login1 { screen lock, if there is any. This is implemented by sending out the Lock() and Unlock() signals from the respective session object which session managers are supposed to listen on. - LockSessions() asks all sessions to activate the screen locks. This may be - used to lock any access to the machine in one action. Similarly, UnlockSessions() + LockSessions() asks all sessions to activate their screen locks. This may be + used to lock access to the entire machine in one action. Similarly, UnlockSessions() asks all sessions to deactivate their screen locks. KillSession() may be used to send a Unix signal to one or all processes of a @@ -284,45 +284,46 @@ node /org/freedesktop/login1 { are killed. KillUser() may be used to send a Unix signal to all processes of a user. As - argument it takes the user id and a signal number. + arguments it takes the user id and a signal number. TerminateSession(), TerminateUser(), TerminateSeat() may be used to forcibly terminate one specific session, all processes of a user, and all sessions attached to a specific seat, respectively. The session, user, and seat are identified by their respective IDs. - SetUserLinger() enables or disables user lingering. If enabled the runtime + SetUserLinger() enables or disables user lingering. If enabled, the runtime directory of a user is kept around and he may continue to run processes while he is logged out. If - disabled the runtime directory goes away as soon as he logs out. Expects three arguments: the UID, a - boolean whether to enable/disable and a boolean controlling the PolicyKit authorization interactivity - (see above). Note that the user linger state is persistently stored on disk. + disabled, the runtime directory goes away as soon as they log out. SetUserLinger() + expects three arguments: the UID, a boolean whether to enable/disable and a boolean controlling the + PolicyKit authorization interactivity (see below). Note that the user linger state is persistently + stored on disk. AttachDevice() may be used to assign a specific device to a specific - seat. The device is identified by its /sys path, and must be eligible for seat assignments. Takes three + seat. The device is identified by its /sys path and must be eligible for seat assignments. AttachDevice() takes three arguments: the seat id, the sysfs path, and a boolean for controlling PolicyKit interactivity (see - above). Device assignments are persistently stored to disk. To create a new seat, simply specify a + below). Device assignments are persistently stored on disk. To create a new seat, simply specify a previously unused seat id. For more information about the seat assignment logic see Multi-Seat for Linux. FlushDevices() removes all explicit seat assignments for devices, resetting - all assignments to the automatic defaults. The only argument this takes is the PolicyKit interactivity - boolean (see above). + all assignments to the automatic defaults. The only argument it takes is the PolicyKit interactivity + boolean (see below). 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 + Suspend(), and Hibernate() result in the system being powered + off, rebooted, halted (shut down without turning off power), suspended (the system state is + saved to RAM and the CPU is turned off), or hibernated (the system state 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 + using an RTC timer and hibernated. The only argument is the PolicyKit interactivity boolean + interactive (see below). 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 + users. They also enforce inhibition locks. UIs should expose these calls as the primary mechanism to poweroff/reboot/suspend/hibernate the machine. - SetRebootParameter() sets the parameter for the subsequent reboot operation. + SetRebootParameter() sets a parameter for a subsequent reboot operation. See the description of reboot in systemctl1 and reboot2 @@ -331,23 +332,23 @@ node /org/freedesktop/login1 { 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 + setup mode, the boot loader menu, or a specific boot loader entry. See systemctl1 for the - command line interface. + corresponding command line interface. CanPowerOff(), CanReboot(), 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, + CanRebootToBootLoaderEntry() test whether the system supports the respective + operation and whether the calling user is allowed to execute 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 + 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 + challenge is returned, the operation is available but only after authorization. ScheduleShutdown() schedules a shutdown operation type at @@ -359,7 +360,7 @@ node /org/freedesktop/login1 { 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 + all terminals and stored in a 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 @@ -377,7 +378,7 @@ node /org/freedesktop/login1 { 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 + descriptor and all its duplicates are closed. For more information on the inhibition logic see Inhibitor Locks. @@ -385,21 +386,21 @@ node /org/freedesktop/login1 { Signals - Whenever the inhibition state or idle hint changes daemon PropertyChanged + Whenever the inhibition state or idle hint changes, PropertyChanged signals are sent out to which clients can subscribe. The SessionNew, SessionRemoved, - UserNew, UserRemoved, SeatNew, + UserNew, UserRemoved, SeatNew, and 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. The PrepareForShutdown() and PrepareForSleep() signals - are sent right before (with the argument true) and after (with the argument + are sent right before (with the argument true) or after (with the argument false) the system goes down for reboot/poweroff and suspend/hibernate, - respetively. This may be used by applications to save data on disk, release memory, or do other jobs - that shall be done shortly before shutdown/sleep, in conjunction with delay inhibitor locks. After - completion of this work they should release their inhibition locks in order not to delay the operation + respectively. This may be used by applications to save data on disk, release memory, or do other jobs + that should be done shortly before shutdown/sleep, in conjunction with delay inhibitor locks. After + completion of this work they should release their inhibition locks in order to not delay the operation any further. For more information see Inhibitor Locks. @@ -424,7 +425,7 @@ node /org/freedesktop/login1 { 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. + system is idle it might get into automatic suspend or shutdown depending on the configuration. IdleSinceHint and IdleSinceHintMonotonic encode the timestamps of the last change of the idle hint boolean, in CLOCK_REALTIME and @@ -432,26 +433,26 @@ node /org/freedesktop/login1 { 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). + shutdown, sleep, and idle (see above). 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 + 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 + properties are true during the interval between the two PrepareForShutdown and + PrepareForSleep signals respectively. Note that these properties do not send out PropertyChanged signals. - The RebootParameter property shows the value set with + The RebootParameter property shows the value set with the SetRebootParameter() method described above. - The ScheduledShutdown shows the value pair set with + ScheduledShutdown shows the value pair set with the ScheduleShutdown() method described above. RebootToFirmwareSetup, RebootToBootLoaderMenu, and @@ -460,11 +461,11 @@ node /org/freedesktop/login1 { 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. + The WallMessage and EnableWallMessages properties reflect the + shutdown reason and wall message enablement switch which can be set with the + SetWallMessage() method described above. - Docked is true if the machine is connected to dock. + Docked is true if the machine is connected to a 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. @@ -478,7 +479,7 @@ node /org/freedesktop/login1 { org.freedesktop.login1.set-user-linger privilege. AttachDevice() requires org.freedesktop.login1.attach-device and - FlushDevices() + FlushDevices() requires org.freedesktop.login1.flush-devices. PowerOff(), Reboot(), Halt(), Suspend(), Hibernate() require @@ -497,7 +498,7 @@ node /org/freedesktop/login1 { 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. + respectively depending on whether there are other sessions around or active inhibits are present. HybridSleep() and SuspendThenHibernate() use the same privileges as Hibernate(). SetRebootParameter() requires @@ -514,7 +515,7 @@ node /org/freedesktop/login1 { ScheduleShutdown and CancelScheduledShutdown require the same privileges (listed above) as the immediate poweroff/reboot/halt operations. - Inhibit() is protected via either one of + Inhibit() is protected via one of org.freedesktop.login1.inhibit-block-shutdown, org.freedesktop.login1.inhibit-delay-shutdown, org.freedesktop.login1.inhibit-block-sleep, @@ -527,7 +528,7 @@ node /org/freedesktop/login1 { 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. + should interactively ask the user for authentication credentials if required. @@ -585,7 +586,7 @@ node /org/freedesktop/login1/seat/seat0 { Whenever ActiveSession, Sessions, CanGraphical, CanMultiSession and CanTTY - or the idle state changes PropertyChanged signals are sent out to which clients + or the idle state changes, PropertyChanged signals are sent out to which clients can subscribe. @@ -595,7 +596,7 @@ node /org/freedesktop/login1/seat/seat0 { The Id property encodes the ID of the seat. ActiveSession encodes the currently active session if there is one. It is a - structure consisting of session id and object path. + structure consisting of the session id and the object path. CanMultiSession encodes whether the session is multi-session capable, CanTTY whether it is suitable for text logins, CanGraphical @@ -604,7 +605,7 @@ node /org/freedesktop/login1/seat/seat0 { 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, + The IdleHint, IdleSinceHint, and IdleSinceHint properties encode the idle state, similar to the one exposed on the Manager object, but specific for this seat. @@ -660,14 +661,14 @@ node /org/freedesktop/login1/user/_1000 { Methods Terminate() and Kill() work similar to the - TerminateUser() and KillUser() calls on the manager + TerminateUser() and KillUser() methods on the manager object. Signals - Whenever Sessions or the idle state changes + Whenever Sessions or the idle state changes, PropertyChanged signals are sent out to which clients can subscribe. @@ -680,39 +681,39 @@ node /org/freedesktop/login1/user/_1000 { The Name property encodes the user name. Timestamp and TimestampMonotonic encode the login time of - the user in usec since the epoch, in the CLOCK_REALTIME and + the user in microseconds since the epoch, in the CLOCK_REALTIME and CLOCK_MONOTONIC clocks, respectively. RuntimePath encodes the runtime path of the user, - i.e. $XDG_RUNTIME_DIR, for details see the + i.e. $XDG_RUNTIME_DIR. For details see the XDG Basedir Specification . - Service contains the name of the user systemd service unit name of this - user. Each logged in user gets a user service unit assigned that runs a user systemd instance. This is + Service contains the unit name of the user systemd service of this + user. Each logged in user is assigned a user service that runs a user systemd instance. This is usually an instance of user@.service. - Slice contains the name of the user systemd slice unit name of this user. Each + Slice contains the unit name of the user systemd slice of this user. Each logged in user gets a private slice. - Display encodes which graphical session should be used as primary UI display - for the use. It is a structure encoding session ID and object path of the session to use. + Display encodes which graphical session should be used as the primary UI display + for the user. It is a structure encoding the session ID and the object path of the session to use. - State encodes the user state, one of offline, - lingering, online, active, + State encodes the user state and is one of offline, + lingering, online, active, or closing. See sd_uid_get_state3 for more information about the states. Sessions is an array of structures encoding all current sessions of the - user. Each structure consists of ID and object path. + user. Each structure consists of the ID and object path. - The IdleHint, IdleSinceHint, + The IdleHint, IdleSinceHint, and 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. + The Linger property shows whether lingering is enabled for this user. @@ -812,41 +813,41 @@ node /org/freedesktop/login1/session/45 { Methods Terminate(), Activate(), Lock(), - Unlock(), Kill() work similarly to the respective calls on + Unlock(), and Kill() work similarly to the respective calls on the Manager object. - SetIdleHint() shall be called by the session object to update the idle state - of the session, whenever it changes. + SetIdleHint() is called by the session object to update the idle state + of the session whenever it changes. TakeControl() allows a process to take exclusive managed device - access-control for that session. Only one dbus-connection can be a controller for a given session at a - time. If the force argument is set (root only), an existing controller is kicked - out and replaced. Otherwise, this call fails if there is already a controller. Note that this call is - limited to dbus-users with the effective UID set to the User of the Session or root. + access-control for that session. Only one D-Bus connection can be a controller for a given session at any + time. If the force argument is set (root only), an existing controller is kicked + out and replaced. Otherwise, this call fails if there is already a controller. Note that this call is + limited to D-Bus users with the effective UID set to the user of the session or root. - ReleaseControl() drops control of a given session again. Closing the - dbus-connection implicitly releases control, too. See TakeControl() for more. This - also releases all devices for the controller that were requested via TakeDevice(). + ReleaseControl() drops control of a given session. Closing the + D-Bus connection implicitly releases control as well. See TakeControl() for more information. This + method also releases all devices for which the controller requested ownership via TakeDevice(). - TakeDevice() allows a session-controller to get a file-descriptor for a - specific device. Pass in the major and minor numbers of the character-device and - systemd-logind will return a file-descriptor for the device. Only a limited set of + TakeDevice() allows a session controller to get a file descriptor for a + specific device. Pass in the major and minor numbers of the character device and + systemd-logind will return a file descriptor for the device. Only a limited set of device-types is currently supported (but may be extended). systemd-logind - automatically mutes the file-descriptor if the session is inactive and resumes it once the session gets - active again. This guarantees that a session can only access session-devices if the session is + automatically mutes the file descriptor if the session is inactive and resumes it once the session is + activated again. This guarantees that a session can only access session devices if the session is active. Note that this revoke/resume mechanism is asynchronous and may happen at any given time. This only works on devices that are attached to the seat of the given session. A process is not required to - have direct access to the device-node. systemd-logind only requires you to be the + have direct access to the device node. systemd-logind only requires you to be the active session controller (see TakeControl()). Also note that any device can only be requested once. As long as you don't release it, further TakeDevice() calls will fail. ReleaseDevice() releases a device again (see TakeDevice()). This is also implicitly done by - ReleaseControl() or when closing the dbus-connection. + ReleaseControl() or when closing the D-Bus connection. - PauseDeviceComplete() allows a session-controller to synchronously pause a + PauseDeviceComplete() allows a session controller to synchronously pause a device after receiving a PauseDevice(pause) signal. Forced signals (or after an internal timeout) are automatically completed by systemd-logind asynchronously. @@ -857,7 +858,7 @@ node /org/freedesktop/login1/session/45 { 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 + 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 @@ -869,34 +870,33 @@ node /org/freedesktop/login1/session/45 { Signals - The active session-controller exclusively gets PauseDevice and + The active session controller exclusively gets PauseDevice and ResumeDevice events for any device it requested via TakeDevice(). They notify the controller whenever a device is paused or resumed. A - device is never resumed if a session is inactive. Also note that PauseDevice + device is never resumed if its session is inactive. Also note that PauseDevice signals are sent before the PropertyChanged signal for the Active state. The inverse is true for ResumeDevice. A device may remain paused for unknown reasons even though the Session is active. - A PauseDevice signal carries the major and minor and a string describing the - type as arguments. force means the device got paused by - systemd-logind already and this is only an asynchronous - notification. pause means systemd-logind tries to pause the - device and grants you limited amount of time to pause it. You must respond to this via - PauseDeviceComplete(). This synchronous pausing-mechanism is used for + A PauseDevice signal carries the major and minor numbers and a string describing the + type as arguments. force means the device was already paused by + systemd-logind and the signal is only an asynchronous + notification. pause means systemd-logind grants you a limited amount of time to pause the device. You must respond to this via + PauseDeviceComplete(). This synchronous pausing mechanism is used for backwards-compatibility to VTs and systemd-logind is free to not make use of it. It is also free to send a forced PauseDevice if you don't respond in a timely manner (or for any other reason). gone means the device was unplugged from the - system and you will no longer get any notifications about it. There is no reason to call + system and you will no longer get any notifications about it. There is no need to call ReleaseDevice(). You may call TakeDevice() again if a new - device gets the major+minor combination assigned. + device is assigned the major+minor combination. ResumeDevice is sent whenever a session is active and a device is - resumed. It carries the major/minor as arguments and provides a new open file-descriptor. You should + resumed. It carries the major/minor numbers as arguments and provides a new open file descriptor. You should switch to the new descriptor and close the old one. They are not guaranteed to have the same underlying - open-file-descriptor in the kernel (except for a limited set of device types). + open file descriptor in the kernel (except for a limited set of device types). - Whenever Active or the idle state changes + Whenever Active or the idle state changes, PropertyChanged signals are sent out to which clients can subscribe. Lock/Unlock is sent when the session is asked to be @@ -911,18 +911,18 @@ node /org/freedesktop/login1/session/45 { Id encodes the session ID. User encodes the user ID of the user this session belongs to. This is a - structure encoding the Unix UID and the object path. + structure consisting of the Unix UID and the object path. Name encodes the user name. - Timestamp and TimestampMonotonic encode the usec timestamp + Timestamp and TimestampMonotonic encode the microseconds since the epoch when the session was created, in CLOCK_REALTIME or CLOCK_MONOTONIC, respectively. VTNr encodes the virtual terminal number of the session if there is any, 0 otherwise. - Seat encodes the seat this session belongs to, if there is any. This is a + Seat encodes the seat this session belongs to if there is any. This is a structure consisting of the ID and the seat object path. TTY encodes the kernel TTY path of the session if this is a text login. If not @@ -945,7 +945,7 @@ node /org/freedesktop/login1/session/45 { Leader encodes the PID of the process that registered the session. - Audit encodes the Kernel Audit session ID of the session, if auditing is + Audit encodes the Kernel Audit session ID of the session if auditing is available. Type encodes the session type. It's one of unspecified (for @@ -953,23 +953,23 @@ node /org/freedesktop/login1/session/45 { x11/mir/wayland (for graphical logins). Class encodes the session class. It's one of user (for - normal user sessions), greeter (for display manager pseudo-sessions), + normal user sessions), greeter (for display manager pseudo-sessions), or lock-screen (for display lock screens). Active is a boolean that is true if the session is active, i.e. currently in the - foreground. This field is semi-redundant due to State. + foreground. This field is semi-redundant due to State. State encodes the session state and one of online, - active, closing. See + active, or closing. See sd_session_get_state3 for more information about the states. - IdleHint, IdleSinceHint, + IdleHint, IdleSinceHint, and 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. + LockedHint shows the locked hint state of this session, as set by the + SetLockedHint() method described above. diff --git a/man/org.freedesktop.machine1.xml b/man/org.freedesktop.machine1.xml index 1c9c41f04c..0b35ab4313 100644 --- a/man/org.freedesktop.machine1.xml +++ b/man/org.freedesktop.machine1.xml @@ -177,27 +177,27 @@ node /org/freedesktop/machine1 { Methods GetMachine() may be used to get the machine object path for the machine with - the specified name. Similarly, GetMachineByPID() get the machine object the + the specified name. Similarly, GetMachineByPID() gets the machine object the specified PID belongs to if there is any. - GetImage() may be used to the the image object path for the image with the + GetImage() may be used to get the image object path of the image with the specified name. - ListMachines() returns an array with all currently registered machines. The + ListMachines() returns an array of all currently registered machines. The structures in the array consist of the following fields: machine name, machine class, an identifier for the service that registered the machine and the machine object path. - ListImages() returns an array with all currently known images. The + ListImages() returns an array of all currently known images. The structures in the array consist of the following fields: image name, type, read-only flag, creation - time, modification time, current disk space, image object path. + time, modification time, current disk space, and image object path. CreateMachine() may be used to register a new virtual machine or container - with systemd-machined, creating a scope unit for it. This takes as arguments: a - machine name chosen by the registrar, an optional UUID as 32 byte array, a string that identifies the + with systemd-machined, creating a scope unit for it. It accepts the following arguments: a + machine name chosen by the registrar, an optional UUID as a 32 byte array, a string that identifies the service that registers the machine, a class string, the PID of the leader process of the machine, an optional root directory of the container, and an array of additional properties to use for the scope - registration. The virtual machine name must be suitable as hostname, and hence should follow the usual - DNS hostname rules, as well as Linux hostname restrictions. Specifically: only 7 Bit ASCII is + registration. The virtual machine name must be suitable as a hostname, and hence should follow the usual + DNS hostname rules, as well as the Linux hostname restrictions. Specifically, only 7 bit ASCII is permitted, a maximum length of 64 characters is enforced, only characters from the set a-zA-Z0-9-_. are allowed, the name may not begin with a dot, and it may not contain two dots immediately following each other. Container and VM managers should ideally use the hostname @@ -206,51 +206,51 @@ node /org/freedesktop/machine1 { nss-mymachines8. If a container manager needs to embed characters outside of the indicated range, escaping is required, possibly using _ as the escape character. Another (somewhat natural) option would be - to utilize Internet IDNA encoding. The UUID is passed as 32 byte array, or if no suitable UUID is - available an empty array (zero length) or zeroed out array shall be passed. The UUID should identify - the virtual machine/container uniquely, and should ideally be the same one as + to utilize Internet IDNA encoding. The UUID is passed as a 32 byte array or, if no suitable UUID is + available, an empty array (zero length) or zeroed out array shall be passed. The UUID should identify + the virtual machine/container uniquely and should ideally be the same UUID that /etc/machine-id in the VM/container is initialized from. The service string can be free-form, but it is recommended to pass a short lowercase identifier like systemd-nspawn, libvirt-lxc or similar. The class string should be either container or vm indicating whether the machine to register is of the respective class. The leader PID should be the host PID of the init process of the - container, or the encapsulating process of the VM. If the root directory of the container is known and - available in the host's hierarchy, it should be passed, otherwise use the empty string. Finally, the + container or the encapsulating process of the VM. If the root directory of the container is known and + available in the host's hierarchy, it should be passed. Otherwise, pass the empty string instead. Finally, the scope properties are passed as array in the same way as to PID1's - StartTransientUnit(). This method call will internally register a transient scope - unit for the calling client (utilizing the passed scope_properties), and move the leader PID into - it. The call returns an object path for the registered machine object, implementing the + StartTransientUnit() method. Calling this method will internally register a transient scope + unit for the calling client (utilizing the passed scope_properties) and move the leader PID into + it. The call returns an object path for the registered machine object that implements the org.freedesktop.machine1.Machine interface (see below). Also see the New Control Group - Interfaces for details about scope units, and how to alter resource control settings on the + Interfaces for details about scope units and how to alter resource control settings on the created machine at runtime. - RegisterMachine() is similar to CreateMachine(), - however only registers a machine, but does not create a scope unit for it. The caller's unit will be - registered instead. This call is only recommended to be used for container or VM managers that are run + RegisterMachine() is similar to CreateMachine(). + However, it only registers a machine and does not create a scope unit for it. Instead, the caller's unit is + registered. We recommend to only use this method for container or VM managers that are run multiple times, one instance for each container/VM they manage, and are invoked as system services. CreateMachineWithNetwork() and RegisterMachineWithNetwork() are similar to CreateMachine() and RegisterMachine() but take an extra argument: an array of network interface - indexes that point towards the virtual machine or container. The interface indexes should reference one - or more network interfaces on the host that can be used to communicate with the guest. Commonly the - passed interface index refers to the host side of a "veth" link (in case of containers), or a - "tun"/"tap" link (in case of VMs) or the host side of a bridge interface that bridges access to the + indices that point towards the virtual machine or container. The interface indices should reference one + or more network interfaces on the host that can be used to communicate with the guest. Commonly, the + passed interface index refers to the host side of a "veth" link (in case of containers), a + "tun"/"tap" link (in case of VMs), or the host side of a bridge interface that bridges access to the VM/container interfaces. Specifying this information is useful to enable support for link-local IPv6 - communication to the machines, since the scope field of sockaddr_in6 can be initialized by the + communication to the machines since the scope field of sockaddr_in6 can be initialized by the specified ifindex. nss-mymachines8 makes use of this information. - KillMachine() sends a UNIX signal to the machine's processes. It takes a + KillMachine() sends a UNIX signal to the machine's processes. As its arguments, it takes a machine name (as originally passed to CreateMachine() or returned by - ListMachines()). An identifier what precisely to send the signal to being either - leader or all, plus a numeric UNIX signal integer. + ListMachines()), an identifier that specifies what precisely to send the signal to (either + leader or all), and a numeric UNIX signal integer. TerminateMachine() terminates a virtual machine, killing its processes. It - takes a machine name as argument. + takes a machine name as its only argument. GetMachineAddresses() retrieves the IP addresses of a container. This call returns an array of pairs consisting of an address family specifier (AF_INET or @@ -258,41 +258,41 @@ node /org/freedesktop/machine1 { containers that make use of network namespacing. GetMachineOSRelease() retrieves the OS release information of a - container. This call returns an array of key value pairs read from the + container. This method returns an array of key value pairs read from the os-release5 file in - the container, and is useful to identify the operating system used in a container. + the container and is useful to identify the operating system used in a container. OpenMachinePTY() allocates a pseudo TTY in the container and returns a file descriptor and its path. This is equivalent to transitioning into the container and invoking posix_openpt3. OpenMachineLogin() allocates a pseudo TTY in the container and ensures that - a getty loging prompt of the container is running on the other end. It returns the file descriptor of - the PTY plus the PTY path. This is useful for acquiring a pty with a login prompt from the + a getty login prompt of the container is running on the other end. It returns the file descriptor of + the PTY and the PTY path. This is useful for acquiring a pty with a login prompt from the container. OpenMachineShell() allocates a pseudo TTY in the container, as the specified - user, and invokes an executable of the specified path, with a list of arguments (starting from - argv[0]), and an environment block. It then returns the file descriptor of the PTY plus the PTY + user, and invokes the executable at the specified path with a list of arguments (starting from + argv[0]) and an environment block. It then returns the file descriptor of the PTY and the PTY path. BindMountMachine() bind mounts a file or directory from the host into the - container. Takes a machine name, the source directory on the host, and the destination directory in the - container as argument. Also takes two booleans, one indicating whether the bind mount shall be + container. Its arguments consist of a machine name, the source directory on the host, the destination directory in the + container, and two booleans, one indicating whether the bind mount shall be read-only, the other indicating whether the destination mount point shall be created first, if it is missing. CopyFromMachine() copies files or directories from a container into the - host. Takes a container name, a source directory in the container and a destination directory on the - host as argument. CopyToMachine() does the opposite and copies files from a source + host. It takes a container name, a source directory in the container and a destination directory on the + host as arguments. CopyToMachine() does the opposite and copies files from a source directory on the host into a destination directory in the container. - RemoveImage() removes the image by the specified name. + RemoveImage() removes the image with the specified name. - RenameImage() renames the specified image to a new name. + RenameImage() renames the specified image. - CloneImage() clones the specified image under a new name. Also takes a - boolean argument indicating whether the resuling image shall be read-only or not. + CloneImage() clones the specified image under a new name. It also takes a + boolean argument indicating whether the resulting image shall be read-only or not. MarkImageReadOnly() toggles the read-only flag of an image. @@ -301,15 +301,15 @@ node /org/freedesktop/machine1 { SetImageLimit() sets a per-image quota limit. MapFromMachineUser(), MapToMachineUser(), - MapFromMachineGroup(), MapToMachineGroup() may be used to map - UIDs/GIDs from the host user namespace to a container namespace or back. + MapFromMachineGroup(), and MapToMachineGroup() may be used to map + UIDs/GIDs from the host user namespace to a container user namespace or vice versa. Signals MachineNew and MachineRemoved are sent whenever a new - machine is registered or removed. These signals carry the machine name plus the object path to the + machine is registered or removed. These signals carry the machine name and the object path to the corresponding org.freedesktop.machine1.Machine interface (see below). @@ -393,47 +393,47 @@ node /org/freedesktop/machine1/machine/rawhide { Methods - Terminate() and Kill() terminate/kill the machine, and + Terminate() and Kill() terminate/kill the machine. These methods take the same arguments as TerminateMachine() and - KillMachine() on the Manager interface. + KillMachine() on the Manager interface, respectively. - GetAddresses() and GetOSRelease() get IP address and OS - release information from the machine, and take the same arguments as + GetAddresses() and GetOSRelease() get the IP address and OS + release information from the machine. These methods take the same arguments as GetMachineAddresses() and GetMachineOSRelease() of the - Manager interface, described above. + Manager interface, respectively. Properties - Name is the machine name, as it was passed in during registration with + Name is the machine name as it was passed in during registration with CreateMachine() on the manager object. Id is the machine UUID. Timestamp and TimestampMonotonic are the realtime and - monotonic timestamps when the virtual machines where created. + monotonic timestamps when the virtual machines where created in microseconds since the epoch. - Service contains a short string identifying the registering service, as passed + Service contains a short string identifying the registering service as passed in during registration of the machine. Unit is the systemd scope or service unit name for the machine. Leader is the PID of the leader process of the machine. - Class is the class of the machine and either the string "vm" (for real VMs + Class is the class of the machine and is either the string "vm" (for real VMs based on virtualized hardware) or "container" (for light-weight userspace virtualization sharing the same kernel as the host). - RootDirectory is the root directory of the container if that is known and - applicable, or the empty string. + RootDirectory is the root directory of the container if it is known and + applicable or the empty string. - NetworkInterfaces contains an array of network interface indexes that point - towards the container or VM or the host. For details about this information see the description of + NetworkInterfaces contains an array of network interface indices that point + towards the container, the VM or the host. For details about this information see the description of CreateMachineWithNetwork() above. - State is the state of the machine, and one of opening, - running, closing. Note that the state machine is not considered + State is the state of the machine and is one of opening, + running, or closing. Note that the state machine is not considered part of the API and states might be removed or added without this being considered API breakage. diff --git a/man/org.freedesktop.resolve1.xml b/man/org.freedesktop.resolve1.xml index d150ee2a5f..83ab0ed3d9 100644 --- a/man/org.freedesktop.resolve1.xml +++ b/man/org.freedesktop.resolve1.xml @@ -29,14 +29,13 @@ systemd-resolved.service8 - is a system service that provides host name resolution and caching using DNS, LLMNR, and mDNS. It also + is a system service that provides hostname resolution and caching using DNS, LLMNR, and mDNS. It also does DNSSEC validation. This page describes the resolve semantics and the D-Bus interface. This page contains an API reference only. If you are looking for a longer explanation how to use this API, please consult - Writing Network Configuration Managers - and + Writing Network Configuration Managers and Writing Resolver Clients. @@ -184,37 +183,35 @@ node /org/freedesktop/resolve1 { Methods - ResolveHostname() takes a hostname and acquires one or more IP addresses for - it. As parameters it takes the Linux network interface index to execute the query on, or 0 if it may be + ResolveHostname() takes a hostname and resolves it to one or more IP addresses. + As parameters it takes the Linux network interface index to execute the query on, or 0 if it may be done on any suitable interface. The name parameter specifies the hostname to - resolve. Note that IDNA conversion is applied to this name when necessary, and when it is resolved via - Unicast DNS, but not for resolution via LLMNR or MulticastDNS. The family parameter - specifies the address family of the IP address to retrieve. It may be AF_INET, - AF_INET6 or AF_UNSPEC, to request addresses of a specific - family. If AF_UNSPEC is specified (recommended), both kinds are retrieved, subject + resolve. Note that if required, IDNA conversion is applied to this name unless it is resolved via LLMNR or MulticastDNS. The family parameter + limits the results to a specific address family. It may be AF_INET, + AF_INET6 or AF_UNSPEC. If AF_UNSPEC is specified (recommended), both kinds are retrieved, subject to local network configuration (i.e. if no local, routable IPv6 address is found, no IPv6 address is - retrieved; and similarly for IPv4). A 64-bit flags field may be used to alter + retrieved; and similarly for IPv4). A 64-bit flags field may be used to alter the behaviour of the resolver operation (see below). The method returns an array of address records. Each - address record consists of an interface index the address belongs to, an address family as well as a + address record consists of the interface index the address belongs to, an address family as well as a byte array with the actual IP address data (which either has 4 or 16 elements, depending on the address family). The returned address family will be one of AF_INET or AF_INET6. For IPv6, the returned address interface index should be used to - initialize the .sin6_scope_id field of a struct sockaddr_in6, to permit + initialize the .sin6_scope_id field of a struct sockaddr_in6 instance to permit support for resolution to link-local IP addresses. The address array is followed by the canonical name - of the host, which may or may not be identical to the name looked up. Finally, a 64-bit - flags field is returned, that is defined similarly to the flags + of the host, which may or may not be identical to the resolved hostname. Finally, a 64-bit + flags field is returned that is defined similarly to the flags field that was passed in, but contains information about the resolved data (see below). If the hostname - passed in is an IPv4 or IPv6 address formatted as string, it is parsed, and the result returned. In - this case no network communication is done. + passed in is an IPv4 or IPv6 address formatted as string, it is parsed, and the result is returned. In + this case, no network communication is done. ResolveAddress() executes the reverse operation: it takes an IP address and acquires one or more hostnames for it. As parameters it takes the interface index to execute the query on, or 0 if all suitable interfaces are OK. The family - parameter indicates the address family of the IP address to resolve, it may be either + parameter indicates the address family of the IP address to resolve. It may be either AF_INET or AF_INET6. The address parameter - takes the raw IP address data (as either 4 or 16 byte array). The flags input - parameter may be used to alter the resolver operation (see below). The call returns an array of name - records, consisting of an interface index plus the name each. The flags output + takes the raw IP address data (as either a 4 or 16 byte array). The flags input + parameter may be used to alter the resolver operation (see below). The method returns an array of name + records, each consisting of an interface index and a hostname. The flags output field contains additional information about the resolver operation (see below). ResolveRecord() takes a DNS resource record (RR) type, class and name, and @@ -223,7 +220,7 @@ node /org/freedesktop/resolve1 { any suitable interface. The name parameter specifies the RR domain name to look up (no IDNA conversion is applied), followed by the 16-bit class and type fields (which may be ANY). Finally, a flags field may be passed in to alter behaviour of the look-up (see - below). On return an array of RR items is returned. Each array entry consists of the network interface + below). On completion, an array of RR items is returned. Each array entry consists of the network interface index the RR was discovered on, the type and class field of the RR found, and a byte array of the raw RR discovered. The raw RR data starts with the RR's domain name, in the original casing, followed by the RR type, class, TTL and RDATA, in the binary format documented in @@ -231,91 +228,91 @@ node /org/freedesktop/resolve1 { compression in the payload (such as MX or PTR), the compression is expanded in the returned data. - Note that the class field has to be specified as IN or ANY currently, and specifying a different + Note that currently, the class field has to be specified as IN or ANY. Specifying a different class will return an error indicating that look-ups of this kind are unsupported. Similarly, some - special types are not supported either (AXFR, OPT, …). While systmed-resolved parses and validates resource - record of many types, it is crucial that clients using this API understand that the RR data originates + special types are not supported either (AXFR, OPT, …). While systemd-resolved parses and validates resource + records of many types, it is crucial that clients using this API understand that the RR data originates from the network and should be thoroughly validated before use. - ResolveService() may be used to resolve a DNS SRV service record, as the + ResolveService() may be used to resolve a DNS SRV service record, as well as the hostnames referenced in it, and possibly an accompanying DNS-SD TXT record containing additional - service metadata. The primary benefit of using this call over ResolveRecord() + service metadata. The primary benefit of using this method over ResolveRecord() specifying the SRV type is that it will resolve the SRV and TXT RRs as well as the hostnames referenced in the SRV in a single operation. As parameters it takes a Linux network interface index, a service - name, a service type and a service domain. The call may be invoked in three different modes: + name, a service type and a service domain. This method may be invoked in three different modes: To resolve a DNS-SD service, specify the service name (e.g. Lennart's Files), the service type (e.g. _webdav._tcp) and the domain to search in - (e.g. local) in the three service parameters. The service name must be in UTF-8 + (e.g. local) as the three service parameters. The service name must be in UTF-8 format, and no IDNA conversion is applied to it in this mode (as mandated by the DNS-SD - specifications). However, if necessary IDNA conversion is applied to the domain parameter. + specifications). However, if necessary, IDNA conversion is applied to the domain parameter. - To resolve a plain SRV record, set the service name parameter to the empty string, + To resolve a plain SRV record, set the service name parameter to the empty string and set the service type and domain properly. (IDNA conversion is applied to the domain, if necessary.) - Alternatively, leave both the service name and type empty, and specify the full + Alternatively, leave both the service name and type empty and specify the full domain name of the SRV record (i.e. prefixed with the service type) in the domain parameter. (No IDNA coversion is applied in this mode.) - The family parameter of the ResolveService() call encodes + The family parameter of the ResolveService() method encodes the desired family of the addresses to resolve (use AF_INET, - AF_INET6, AF_UNSPEC), if this is enabled (Use the + AF_INET6, or AF_UNSPEC). If this is enabled (Use the NO_ADDRESS flag to turn address resolution off, see below). The flags parameter takes a couple of flags that may be used to alter the resolver operation. - On return, ResolveService() returns an array of SRV record structures. Each - item consists of the priority, weight and port fields and the hostname to contact, as encoded in the SRV - record. Immediately following is an array with the addresses of this hostname, with each item consisting + On completion, ResolveService() returns an array of SRV record structures. Each + items consisting of the priority, weight and port fields as well as the hostname to contact, as encoded in the SRV + record. Immediately following is an array of the addresses of this hostname, with each item consisting of the interface index, the address family and the address data in a byte array. This address array is - followed with the canonicalized hostname. After this array of SRV record structures an array of byte - arrays follows, that encodes the TXT RR strings, in case DNS-SD look-ups are enabled. The next parameters + followed by the canonicalized hostname. After this array of SRV record structures an array of byte + arrays follows that encodes the TXT RR strings, in case DNS-SD look-ups are enabled. The next parameters are the canonical service name, type and domain. This may or may not be identical to the parameters passed in. Finally, a flags field is returned that contains information about the resolver operation performed. - The ResetStatistics() method resets to zero the various statistics counters - systmed-resolved maintains. (For details, see the statistics properties below.) + The ResetStatistics() method resets the various statistics counters that + systemd-resolved maintains to zero. (For details, see the statistics properties below.) The GetLink() method takes a network interface index and returns the object path to the org.freedesktop.resolve1.Link object corresponding to it. The SetLinkDNS() method sets the DNS servers to use on a specific - interface. This call (and the following ones) may be used by network management software to configure + interface. This method (and the following ones) may be used by network management software to configure per-interface DNS settings. It takes a network interface index as well as an array of DNS server IP address records. Each array item consists of an address family (either AF_INET or AF_INET6), followed by a 4-byte or 16-byte array with the raw address data. This - call is a one-call shortcut for retrieving the Link object for a network interface using - GetLink() (see above) and then invoking the SetDNS() call + method is a one-step shortcut for retrieving the Link object for a network interface using + GetLink() (see above) and then invoking the SetDNS() method (see below) on it. - Network management software integrating with systmed-resolved is recommended - to invoke this method (and the five below) after the interface appeared in the kernel (and thus after a - network interface index has been assigned), but before the network interfaces is activated (set - IFF_UP on) so that all settings take effect during the full time the network - interface is up. It is safe to alter settings while the interface is up, however. Use the + Network management software integrating with systemd-resolved should + call this method (and the five below) after the interface appeared in the kernel (and thus after a + network interface index has been assigned), but before the network interfaces is activated + (IFF_UP set) so that all settings take effect during the full time the network + interface is up. It is safe to alter settings while the interface is up, however. Use RevertLink() (described below) to reset all per-interface settings. The SetLinkDomains() method sets the search and routing domains to use on a - specific network interface for DNS look-ups. It take a network interface index plus an array of domains, - each with a boolean parameter indicating whether the specified domain shall be used as search domain - (false), or just as routing domain (true). Search domains are used for qualifying single-label names into + specific network interface for DNS look-ups. It takes a network interface index and an array of domains, + each with a boolean parameter indicating whether the specified domain shall be used as a search domain + (false), or just as a routing domain (true). Search domains are used for qualifying single-label names into FQDN when looking up hostnames, as well as for making routing decisions on which interface to send - queries ending in the domain to. Routing domains are not used for single-label name qualification, and - are only used for routing decisions. Pass the search domains in the order they shall be used. + queries ending in the domain to. Routing domains are only used for routing decisions and not used for single-label + name qualification. Pass the search domains in the order they should be used. The SetLinkLLMNR() method enables or disables LLMNR support on a specific - network interface. It takes a network interface index as well as a string that either may be empty, + network interface. It takes a network interface index as well as a string that may either be empty or one of yes, no or resolve. If empty, the systemd-wide - default LLMNR setting is used. If yes LLMNR is used for resolution of single-label - names, and the local hostname is registered on all local LANs for LLMNR resolution by peers. If - no LLMNR is turned off fully on this interface. If resolve LLMNR + default LLMNR setting is used. If yes, LLMNR is used for resolution of single-label + names and the local hostname is registered on all local LANs for LLMNR resolution by peers. If + no, LLMNR is turned off fully on this interface. If resolve, LLMNR is only enabled for resolving names, but the local host name is not registered for other peers to use. @@ -324,26 +321,26 @@ node /org/freedesktop/resolve1 { described above. The SetLinkDNSSEC() method enables or disables DNSSEC validation on a - specific network interface. It takes a network interface index as well as a string that either may be - empty, yes, no or allow-downgrade. If empty, - the system-wide default DNSSEC setting is used. If yes full DNSSEC validation is - done for all look-ups. If the selected DNS server does not support DNSSEC, look-ups will fail if this - mode is used. If no DNSSEC validation is fully disabled. If - allow-downgrade DNSSEC validation is enabled, but is turned off automatically if the + specific network interface. It takes a network interface index as well as a string that may either be + empty or one of yes, no, or allow-downgrade. When + empty, the system-wide default DNSSEC setting is used. If yes, full DNSSEC validation + is done for all look-ups. If the selected DNS server does not support DNSSEC, look-ups will fail if this + mode is used. If no, DNSSEC validation is fully disabled. If + allow-downgrade, DNSSEC validation is enabled, but is turned off automatically if the selected server does not support it (thus opening up behaviour to downgrade attacks). Note that DNSSEC only applies to traditional DNS, not to LLMNR or MulticastDNS. The SetLinkDNSSECNegativeTrustAnchors() method may be used to configure DNSSEC Negative Trust Anchors (NTAs) for a specific network interface. It takes a network interface index and a - list of domains as parameters. + list of domains as arguments. The RevertLink() method may be used to revert all per-link settings done with - the six calls described above to the defaults again. + the six methods described above to the defaults again. The Flags Parameter - The four calls above accept and return a 64-bit flags value. In most cases passing 0 is sufficient + The four methods above accept and return a 64-bit flags value. In most cases passing 0 is sufficient and recommended. However, the following flags are defined to alter the look-up: @@ -363,33 +360,33 @@ node /org/freedesktop/resolve1 { classic unicast DNS, LLMNR via IPv4/UDP and IPv6/UDP respectively, as well as MulticastDNS via IPv4/UDP and IPv6/UDP. If all of these five bits are off on input (which is strongly recommended) the look-up will be done via all suitable protocols for the specific look-up. Note that these flags - operate as filter only, but cannot force a look-up to be done via a protocol. Specifically, systmed-resolved + operate as filter only, but cannot force a look-up to be done via a protocol. Specifically, systemd-resolved will only route look-ups within the .local TLD to MulticastDNS (plus some reverse look-up address domains), and single-label names to LLMNR (plus some reverse address lookup domains). It will route neither of these to Unicast DNS servers. Also, it will do LLMNR and Multicast DNS only on interfaces - suitable for multicasting. + suitable for multicast. - On output these five flags indicate which protocol was used to execute the operation, and hence + On output, these five flags indicate which protocol was used to execute the operation, and hence where the data was found. - The primary use case for these five flags are follow-up look-ups based on DNS data retrieved + The primary use cases for these five flags are follow-up look-ups based on DNS data retrieved earlier. In this case it is often a good idea to limit the follow-up look-up to the protocol that was - used to discover the first DNS data look-up. + used to discover the first DNS result. The NO_CNAME flag controls whether CNAME/DNAME resource records shall be followed during the look-up. This flag is only available at input, none of the functions will return it on output. If a - CNAME/DNAME RR is discovered while resolving a hostname an error is returned instead. By default, + CNAME/DNAME RR is discovered while resolving a hostname, an error is returned instead. By default, when the flag is off, CNAME/DNAME RRs are followed. - The NO_TXT and NO_ADDRESS flags influence operation of the - ResolveService() call only. They are only defined for input, not output. If - NO_TXT set, the DNS-SD TXT RR look-up is not done in the same operation. If NO_ADDRESS is specified + The NO_TXT and NO_ADDRESS flags only influence operation of the + ResolveService() method. They are only defined for input, not output. If + NO_TXT set, the DNS-SD TXT RR look-up is not done in the same operation. If NO_ADDRESS is specified, the hostnames discovered are not implicitly translated to their addresses. The NO_SEARCH flag turns off the search domain logic. It is only defined for input in ResolveHostname(). When specified, single-label hostnames are not qualified using defined search domains, if any are configured. Note that ResolveRecord() - will not qualify single-label domain names using search domains in any case. Also note that + will never qualify single-label domain names using search domains. Also note that multi-label hostnames are never subject to search list expansion. The AUTHENTICATED bit is defined only in the output flags of the four functions. If set, the @@ -398,7 +395,7 @@ node /org/freedesktop/resolve1 { synthesized data, such as localhost or data from /etc/hosts. Moreover, it is set for all LLMNR or mDNS RRs which originate from the local host. Applications that require authenticated RR data for operation should check this flag before - trusting the data. Not that systmed-resolved will not return invalidated data in any case, hence this flag + trusting the data. Note that systemd-resolved will never return invalidated data, hence this flag simply allows to discern the cases where data is known to be trustable, or where there is proof that the data is "rightfully" unauthenticated (which includes cases where the underlying protocol or server does not support authenticating data). @@ -414,8 +411,8 @@ node /org/freedesktop/resolve1 { gethostname3, but may differ if a conflict is detected on the network. - DNS contains an array containing all DNS servers currently used by - systmed-resolved. It contains similar information as the DNS server data written to + DNS contains an array of all DNS servers currently used by + systemd-resolved. It contains similar information as the DNS server data written to /run/systemd/resolve/resolv.conf. Each structure in the array consists of a numeric network interface index, an address family, and a byte array containing the DNS server address (either 4 bytes in length for IPv4 or 16 bytes in lengths for IPv6). The array contains DNS servers configured system-wide, @@ -424,26 +421,26 @@ node /org/freedesktop/resolve1 { per-interface DNS server information either retrieved from systemd-networkd8, or configured by external software via SetLinkDNS() (see above). The network - interface index will be 0 for the system-wide configured services, and non-zero for the per-link + interface index will be 0 for the system-wide configured services and non-zero for the per-link servers. - Similarly, the Domains property contains an array containing all search and - routing domains currently used by systmed-resolved. Each entry consists of a network interface index (again, 0 + Similarly, the Domains property contains an array of all search and + routing domains currently used by systemd-resolved. Each entry consists of a network interface index (again, 0 encodes system-wide entries), the actual domain name, and whether the entry is used only for routing - (true), or for both routing and searching (false). + (true) or for both routing and searching (false). The TransactionStatistics property contains information about the number of - transactions systmed-resolved has been processing. It contains a pair of unsigned 64-bit counters, the first + transactions systemd-resolved has processed. It contains a pair of unsigned 64-bit counters, the first containing the number of currently ongoing transactions, the second the number of total transactions - systmed-resolved is processing or has processed. The latter value may be reset using the - ResetStatistics() call described above. Note that the number of transaction does - not directly map to the number of resolver bus calls issued. While simple look-ups usually require a + systemd-resolved is processing or has processed. The latter value may be reset using the + ResetStatistics() method described above. Note that the number of transactions does + not directly map to the number of issued resolver bus method calls. While simple look-ups usually require a single transaction only, more complex look-ups might result in more, for example when CNAMEs or DNSSEC are in use. The CacheStatistics property contains information about the executed cache operations so far. It exposes three 64-bit counters: the first being the total number of current cache - entries (both positive and negative), the second number of cache hits, and the third the number of + entries (both positive and negative), the second the number of cache hits, and the third the number of cache misses. The latter counters may be reset using ResetStatistics() (see above). @@ -453,15 +450,15 @@ node /org/freedesktop/resolve1 { each non-existance proof. The secure counter is increased for each operation that successfully verified a signed reply, the insecure counter is increased for each operation that successfully verified that an unsigned reply is rightfully unsigned. The bogus counter is increased for each operation where the - validation did not check out, and the data is likely to have been tempered with. Finally the + validation did not check out and the data is likely to have been tempered with. Finally the indeterminate counter is increased for each operation which did not complete because the necessary keys could not be acquired or the cryptographic algorithms were unknown. The DNSSECSupported boolean property reports whether DNSSEC is enabled and the selected DNS servers support it. It combines information about system-wide and per-link DNS settings (see below), and only reports true if DNSSEC is enabled and supported on every interface for - which DNS is configured and for the system-wide settings if there are any. Note that systmed-resolved assumes - DNSSEC is supported by DNS servers until it verified that this is not the case. Thus, the reported + which DNS is configured and for the system-wide settings if there are any. Note that systemd-resolved assumes + DNSSEC is supported by DNS servers until it verifies that this is not the case. Thus, the reported value may initially be true, until the first transactions are executed. @@ -546,7 +543,7 @@ node /org/freedesktop/resolve1/link/_34 { - For each Linux network interface a "Link" object is created, which exposes per-link DNS + For each Linux network interface a "Link" object is created which exposes per-link DNS configuration and state. Use GetLink() on the Manager interface to retrieve the object path for a link object given the network interface index (see above). @@ -556,32 +553,32 @@ node /org/freedesktop/resolve1/link/_34 { The various methods exposed by the Link interface are equivalent to their similarly named counterparts on the Manager interface. e.g. SetDNS() on the Link object maps to SetLinkDNS() on the Manager object, the main difference being that the later - expects an interface index to be speicified. Invoking the calls on the Manager interface has the + expects an interface index to be specified. Invoking the methods on the Manager interface has the benefit of reducing roundtrips, as it is not necessary to first request the Link object path via - GetLink() before invoking the methods. For further details on these calls see the - Manager documentation above. + GetLink() before invoking the methods. For further details on these methods see + the Manager documentation above. Properties ScopesMask defines which resolver scopes are currently active on this - interface. This 64-bit unsigned integer field is a bit mask, consisting of a subset of the bits as the + interface. This 64-bit unsigned integer field is a bit mask consisting of a subset of the bits of the flags parameter describe above. Specifically, it may have the DNS, LLMNR and MDNS bits (the latter in IPv4 and IPv6 flavours) set. Each individual bit is set when the protocol applies to a specific interface and is enabled for it. It is unset otherwise. Specifically, a multicast-capable interface in - "UP" state with an IP address is suitable for LLMNR or MulticastDNS, and any interface that is UP and + the "UP" state with an IP address is suitable for LLMNR or MulticastDNS, and any interface that is UP and has an IP address is suitable for DNS. Note the relationship of the bits exposed here with the LLMNR and MulticastDNS properties also exposed on the Link interface. The latter expose what is *configured* to be used on the interface, the former expose what is actually used on the interface, taking into account the abilities of the interface. DNSSECSupported exposes a boolean field that indicates whether DNSSEC is - currently configured and in use on the interface. Note that if DNSSEC is enabled on an interface it is + currently configured and in use on the interface. Note that if DNSSEC is enabled on an interface, it is assumed available until it is detected that the configured server does not actually support it. Thus, this property may initially report that DNSSEC is supported on an interface. - The other properties reflect the state of the various configuration settings for the link, which + The other properties reflect the state of the various configuration settings for the link which may be set with the various methods calls such as SetDNS() or SetLLMNR(). @@ -589,17 +586,17 @@ node /org/freedesktop/resolve1/link/_34 { Common Errors - Many bus calls systmed-resolved exposes (in particular the resolver calls such - as ResolveHostname() on the Manager interface) return + Many bus methods systemd-resolved exposes (in particular the resolver methods such + as ResolveHostname() on the Manager interface) may return some of the following errors: org.freedesktop.resolve1.NoNameServers - No suitable DNS servers have been found to resolve a request. + No suitable DNS servers were found to resolve a request. org.freedesktop.resolve1.InvalidReply - A response from the selected DNS server could not be understood. + A response from the selected DNS server was not understood. org.freedesktop.resolve1.NoSuchRR @@ -611,7 +608,7 @@ node /org/freedesktop/resolve1/link/_34 { org.freedesktop.resolve1.Aborted - The look-up was aborted, because the selected protocol became unavailable while the + The look-up was aborted because the selected protocol became unavailable while the operation was ongoing. @@ -624,7 +621,7 @@ node /org/freedesktop/resolve1/link/_34 { org.freedesktop.resolve1.NoTrustAnchor - No chain of trust could be established for the response, to a configured DNSSEC trust + No chain of trust could be established for the response to a configured DNSSEC trust anchor. @@ -640,7 +637,7 @@ node /org/freedesktop/resolve1/link/_34 { org.freedesktop.resolve1.LinkBusy - The requested configuration change can not be made, because + The requested configuration change could not be made because systemd-networkd8, already took possession of the interface and supplied configuration data for it. diff --git a/man/org.freedesktop.systemd1.xml b/man/org.freedesktop.systemd1.xml index a3b86d3f1c..09b1a9e78b 100644 --- a/man/org.freedesktop.systemd1.xml +++ b/man/org.freedesktop.systemd1.xml @@ -16,7 +16,7 @@ org.freedesktop.systemd1 - The D-Bus interface of systemd-systemdd + The D-Bus interface of systemd @@ -24,27 +24,27 @@ systemd1 and its - auxiliary daemons expose a number of APIs over D-Bus. This page describes the various APIs exposed by the - system and service manager itself, and does not cover the auxiliary daemons. + auxiliary daemons expose a number of APIs over D-Bus. This page only describes the various APIs exposed by the + system and service manager itself. It does not cover the auxiliary daemons. The service manager exposes a number of objects on the bus: one - Manager object as central entry point for clients, and individual objects + Manager object as a central entry point for clients along with individual objects for each unit and for each queued job. The unit objects each implement a generic - Unit interface plus a type-specific interface. For example, service units - implement org.freedesktop.systemd1.Unit as well as - org.freedesktop.system1.Service. The manager object can be used to list - unit and job objects, or to directly convert a unit name or job id into a bus path of the corresponding + Unit interface as well as a type-specific interface. For example, service units + implement both org.freedesktop.systemd1.Unit and + org.freedesktop.system1.Service. The manager object can list + unit and job objects or directly convert a unit name or job id into a bus path of the corresponding D-Bus object. Properties exposing time values are usually encoded in microseconds (usec) on the bus, even if their corresponding settings in the unit files are in seconds. - In contrast to most of the other services of the systemd suite PID 1 does not use PolicyKit for + In contrast to most of the other services of the systemd suite, PID 1 does not use PolicyKit for controlling access to privileged operations, but relies exclusively on the low-level D-Bus policy language. (This is done in order to avoid a cyclic dependency between PolicyKit and systemd/PID 1.) This means that sensitive operations exposed by PID 1 on the bus are generally not available to unprivileged - processes directly. However some (such as shutdown/reboot/suspend) are made available through the D-Bus + processes directly. However, some operations (such as shutdown/reboot/suspend) are made available through the D-Bus API of logind, see org.freedesktop.login15. @@ -245,76 +245,75 @@ node /org/freedesktop/systemd1 { Methods - Note that many of the calls exist twice: once on the Manager - object, and once on the respective unit objects. This is to optimize access times so that methods that + Note that many of the methods exist twice: once on the Manager + object and once on the respective unit objects. This is to optimize access times so that methods that belong to unit objects do not have to be called with a resolved unit path, but can be called with only the unit id, too. GetUnit() may be used to get the unit object path for a unit name. It takes - the unit name and returns the object path. If a unit has not been loaded yet by this name this call + the unit name and returns the object path. If a unit has not been loaded yet by this name this method will fail. GetUnitByPID() may be used to get the unit object path of the unit a process - ID belongs to. Takes a UNIX PID and returns the object path. The PID must refer to an existing process - of the system. + ID belongs to. It takes a UNIX PID and returns the object path. The PID must refer to an existing system process. LoadUnit() is similar to GetUnit() but will load the unit from disk if possible. - StartUnit() enqeues a start job, and possibly depending jobs. Takes the unit - to activate, plus a mode string. The mode needs to be one of replace, - fail, isolate, ignore-dependencies, - ignore-requirements. If replace the call will start the unit and - its dependencies, possibly replacing already queued jobs that conflict with this. If - fail the call will start the unit and its dependencies, but will fail if this would - change an already queued job. If isolate the call will start the unit in question - and terminate all units that aren't dependencies of it. If ignore-dependencies it - will start a unit but ignore all its dependencies. If ignore-requirements it will + StartUnit() enqueues a start job and possibly depending jobs. It takes the unit + to activate and a mode string as arguments. The mode needs to be one of replace, + fail, isolate, ignore-dependencies, or + ignore-requirements. If replace, the method will start the unit and + its dependencies, possibly replacing already queued jobs that conflict with it. If + fail, the method will start the unit and its dependencies, but will fail if this would + change an already queued job. If isolate, the method will start the unit in question + and terminate all units that aren't dependencies of it. If ignore-dependencies, it + will start a unit but ignore all its dependencies. If ignore-requirements, it will start a unit but only ignore the requirement dependencies. It is not recommended to make use of the - latter two options. Returns the newly created job object. + latter two options. On completion, this method returns the newly created job object. StartUnitReplace() is similar to StartUnit() but - replaces a job that is queued for one unit by a job for another. + replaces a job that is queued for one unit by a job for another unit. StopUnit() is similar to StartUnit() but stops the - specified unit rather than starting it. Note that isolate mode is invalid for this - call. + specified unit rather than starting it. Note that the isolate mode is invalid for this + method. ReloadUnit(), RestartUnit(), - TryRestartUnit(), ReloadOrRestartUnit(), - ReloadOrTryRestartUnit() may be used to restart and/or reload a unit, and takes + TryRestartUnit(), ReloadOrRestartUnit(), or + ReloadOrTryRestartUnit() may be used to restart and/or reload a unit. These methods take similar arguments as StartUnit(). Reloading is done only if the unit is already - running and fails otherwise. If a service is restarted that isn't running it will be started, unless + running and fails otherwise. If a service is restarted that isn't running, it will be started unless the "Try" flavor is used in which case a service that isn't running is not affected by the restart. The "ReloadOrRestart" flavors attempt a reload if the unit supports it and use a restart otherwise. KillUnit() may be used to kill (i.e. send a signal to) all processes of a - unit. Takes the unit name, an enum who and a UNIX + unit. It takes the unit name, an enum who and a UNIX signal number to send. The who enum is one of main, control or all. If - main, only the main process of a unit is killed. If control only - the control process of the unit is killed, if all all processes are killed. A + main, only the main process of the unit is killed. If control, only + the control process of the unit is killed. If all, all processes are killed. A control process is for example a process that is configured via - ExecStop= and is spawned in parallel to the main daemon process, in order to shut it + ExecStop= and is spawned in parallel to the main daemon process in order to shut it down. GetJob() returns the job object path for a specific job, identified by its id. - CancelJob() cancels a specific job identified by its numer ID. This - operation is also available in the Cancel() method of Job objects (see below), and + CancelJob() cancels a specific job identified by its numeric ID. This + operation is also available in the Cancel() method of Job objects (see below) and exists primarily to reduce the necessary round trips to execute this operation. Note that this will not have any effect on jobs whose execution has already begun. ClearJobs() flushes the job queue, removing all jobs that are still - queued. Note that this does not have any effect on jobs whose execution has already begun, it only + queued. Note that this does not have any effect on jobs whose execution has already begun. It only flushes jobs that are queued and have not yet begun execution. ResetFailedUnit() resets the "failed" state of a specific unit. ResetFailed() resets the "failed" state of all units. - ListUnits() returns an array with all currently loaded units. Note that + ListUnits() returns an array of all currently loaded units. Note that units may be known by multiple names at the same name, and hence there might be more unit names loaded than actual units behind them. The array consists of structures with the following elements: @@ -336,7 +335,7 @@ node /org/freedesktop/systemd1 { The unit object path - If there is a job queued for the job unit the numeric job id, 0 + If there is a job queued for the job unit, the numeric job id, 0 otherwise The job type as string @@ -361,8 +360,8 @@ node /org/freedesktop/systemd1 { Subscribe() enables most bus signals to be sent out. Clients which are - interested in signals need to call this function. Signals are only sent out if at least one client - invoked this function. Unsubscribe() undoes the signal subscription that + interested in signals need to call this method. Signals are only sent out if at least one client + invoked this method. Unsubscribe() reverts the signal subscription that Subscribe() implements. It is not necessary to invoke Unsubscribe() as clients are tracked. Signals are no longer sent out as soon as all clients which previously asked for Subscribe() either closed the bus diff --git a/man/org.freedesktop.timedate1.xml b/man/org.freedesktop.timedate1.xml index 8852512906..089f6fbd37 100644 --- a/man/org.freedesktop.timedate1.xml +++ b/man/org.freedesktop.timedate1.xml @@ -25,7 +25,7 @@ systemd-timedated.service8 - is a system service that can be used to control the system time and related settings. This page + is a system service that can be used to control the system time and related settings. This page describes the D-Bus interface. @@ -93,8 +93,8 @@ node /org/freedesktop/timedate1 { Use SetTime() to change the system clock. Pass a value of microseconds since the UNIX epoch (1 Jan 1970 UTC). If relative is true, the passed usec value will be - added to the current system time, if it is false the current system time will be set to the passed usec - value. If the system time is set with this call the RTC will be updated as well. + added to the current system time. If it is false, the current system time will be set to the passed usec + value. If the system time is set with this method, the RTC will be updated as well. Use SetTimezone() to set the system timezone. Pass a value like Europe/Berlin to set the timezone. Valid timezones are listed in @@ -102,11 +102,11 @@ node /org/freedesktop/timedate1 { time, it will be updated accordingly. Use SetLocalRTC() to control whether the RTC is in local time or UTC. It is - strongly recommended to maintain the RTC in UTC. Some OSes (Windows) however maintain the RTC in local - time, which might make it necessary to enable this feature. However, this creates various problems as - daylight changes might be missed. If fix_system is passed true, - the time from the RTC is read again and the system clock adjusted according to the new setting. If - fix_system is passed false the system time is written to the RTC + strongly recommended to maintain the RTC in UTC. However, some OSes (Windows) maintain the RTC in local + time, which might make it necessary to enable this feature. Note that this might create various problems as + daylight changes could be missed. If fix_system is true, + the time from the RTC is read again and the system clock is adjusted according to the new setting. If + fix_system is false, the system time is written to the RTC taking the new setting into account. Use fix_system=true in installers and livecds where the RTC is probably more reliable than the system time. Use fix_system=false in configuration UIs that are run during normal operation and where the system clock is probably more @@ -116,7 +116,7 @@ node /org/freedesktop/timedate1 { network using systemd-timesyncd. This will enable and start or disable and stop the chosen time synchronization service. - Whenever the timezone and local_rtc settings are changed via the daemon + Whenever the timezone and local_rtc settings are changed via the daemon, PropertyChanged signals are sent out to which clients can subscribe. Changing the time settings using this interface is authenticated via PolicyKit. @@ -126,7 +126,7 @@ node /org/freedesktop/timedate1 { The user_interaction boolean parameters can be used to control whether - PolicyKit should interactively ask the user for authentication credentials if it needs to. + PolicyKit should interactively ask the user for authentication credentials if required. The PolicyKit action for SetTimezone() is org.freedesktop.timedate1.set-timezone. For diff --git a/man/systemd-hostnamed.service.xml b/man/systemd-hostnamed.service.xml index 185e038809..699316a09a 100644 --- a/man/systemd-hostnamed.service.xml +++ b/man/systemd-hostnamed.service.xml @@ -30,18 +30,18 @@ Description systemd-hostnamed.service is a system service that may be used to change the - system's hostname and related machine meta data from user programs. It is automatically activated on + system's hostname and related machine metadata from user programs. It is automatically activated on request and terminates itself when unused. It currently offers access to five variables: - The current host name (Example: dhcp-192-168-47-11) + The current hostname (Example: dhcp-192-168-47-11) - The static (configured) host name (Example: + The static (configured) hostname (Example: lennarts-computer) - The pretty host name (Example: Lennart's Computer) + The pretty hostname (Example: Lennart's Computer) A suitable icon name for the local host (Example: @@ -55,7 +55,7 @@ hostnamectl1 is a command line client to this service. - See the + See org.freedesktop.hostname11 for a description of the D-Bus API. diff --git a/man/systemd-localed.service.xml b/man/systemd-localed.service.xml index cd4359dc46..e5f6b78d21 100644 --- a/man/systemd-localed.service.xml +++ b/man/systemd-localed.service.xml @@ -40,7 +40,7 @@ localectl1 is a command line client to this service. - See the + See org.freedesktop.locale11 for a description of the D-Bus API. diff --git a/man/systemd-logind.service.xml b/man/systemd-logind.service.xml index 87ee607c6c..12f9f7a0f6 100644 --- a/man/systemd-logind.service.xml +++ b/man/systemd-logind.service.xml @@ -80,7 +80,7 @@ See org.freedesktop.login13 - for for information about the D-Bus APIs systemd-logind provides. + for information about the D-Bus APIs systemd-logind provides. For more information on the inhibition logic see the Inhibitor @@ -88,7 +88,7 @@ If you are interested in writing a display manager that makes use of logind, please have look at Writing Display - Manager. + Managers. If you are interested in writing a desktop environment that makes use of logind, please have look at Writing Desktop Environments. diff --git a/man/systemd-machined.service.xml b/man/systemd-machined.service.xml index b5fad154e7..e15cc963b4 100644 --- a/man/systemd-machined.service.xml +++ b/man/systemd-machined.service.xml @@ -67,7 +67,7 @@ containers, connecting to the container's init system for that. systemctl's switch has the effect of not only showing the - locally running services, but recursively the services of all registered containers. + locally running services, but recursively showing the services of all registered containers. The machinectl command provides access to a number of useful operations on registered containers, such as introspecting them, rebooting, shutting them down, and