From b750101eb236130cf056c675997decbac904cc49 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 17:35:18 +0200 Subject: Adding upstream version 252.22. Signed-off-by: Daniel Baumann --- man/org.freedesktop.home1.xml | 533 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 533 insertions(+) create mode 100644 man/org.freedesktop.home1.xml (limited to 'man/org.freedesktop.home1.xml') diff --git a/man/org.freedesktop.home1.xml b/man/org.freedesktop.home1.xml new file mode 100644 index 0000000..f217fb8 --- /dev/null +++ b/man/org.freedesktop.home1.xml @@ -0,0 +1,533 @@ + + + + + + + org.freedesktop.home1 + systemd + + + + org.freedesktop.home1 + 5 + + + + org.freedesktop.home1 + The D-Bus interface of systemd-homed + + + + Introduction + + systemd-homed.service8 + is a system service which may be used to create, remove, change or inspect home areas. This page + describes the D-Bus interface. + + + + + The Manager Object + + The service exposes the following interfaces on the Manager object on the bus: + + +node /org/freedesktop/home1 { + interface org.freedesktop.home1.Manager { + methods: + GetHomeByName(in s user_name, + out u uid, + out s home_state, + out u gid, + out s real_name, + out s home_directory, + out s shell, + out o bus_path); + GetHomeByUID(in u uid, + out s user_name, + out s home_state, + out u gid, + out s real_name, + out s home_directory, + out s shell, + out o bus_path); + GetUserRecordByName(in s user_name, + out s user_record, + out b incomplete, + out o bus_path); + GetUserRecordByUID(in u uid, + out s user_record, + out b incomplete, + out o bus_path); + ListHomes(out a(susussso) home_areas); + @org.freedesktop.systemd1.Privileged("true") + ActivateHome(in s user_name, + in s secret); + @org.freedesktop.systemd1.Privileged("true") + DeactivateHome(in s user_name); + RegisterHome(in s user_record); + UnregisterHome(in s user_name); + CreateHome(in s user_record); + RealizeHome(in s user_name, + in s secret); + RemoveHome(in s user_name); + @org.freedesktop.systemd1.Privileged("true") + FixateHome(in s user_name, + in s secret); + AuthenticateHome(in s user_name, + in s secret); + UpdateHome(in s user_record); + ResizeHome(in s user_name, + in t size, + in s secret); + ChangePasswordHome(in s user_name, + in s new_secret, + in s old_secret); + @org.freedesktop.systemd1.Privileged("true") + LockHome(in s user_name); + @org.freedesktop.systemd1.Privileged("true") + UnlockHome(in s user_name, + in s secret); + AcquireHome(in s user_name, + in s secret, + in b please_suspend, + out h send_fd); + @org.freedesktop.systemd1.Privileged("true") + RefHome(in s user_name, + in b please_suspend, + out h send_fd); + @org.freedesktop.systemd1.Privileged("true") + ReleaseHome(in s user_name); + @org.freedesktop.systemd1.Privileged("true") + LockAllHomes(); + @org.freedesktop.systemd1.Privileged("true") + DeactivateAllHomes(); + @org.freedesktop.systemd1.Privileged("true") + Rebalance(); + properties: + readonly a(sso) AutoLogin = [...]; + }; + interface org.freedesktop.DBus.Peer { ... }; + interface org.freedesktop.DBus.Introspectable { ... }; + interface org.freedesktop.DBus.Properties { ... }; +}; + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Methods + + GetHomeByName() returns basic user information (a minimal subset of the full + user record), provided a user name. The information supplied more or less matches what + getpwnam3 returns: + the numeric UID and GID, the real name, home directory and shell. In addition it returns a state + identifier describing the state the user's home directory is in, as well as a bus path referring to the + bus object encapsulating the user record and home directory. This object implements the + org.freedesktop.home1.Home interface documented below. + + GetHomeByUID() is similar to GetHomeByName() but + acquires the information based on the numeric UID of the user. + + GetUserRecordByName() is also similar to + GetHomeByName() but returns the full JSON user record data instead of the broken + down records. An additional returned boolean indicates whether the record is complete or not. A record + is considered complete when its privileged section is included, and incomplete if it + was removed (see JSON User Records for details + about the various sections of a user record). Generally, only privileged clients and clients running + under the identity of the user itself get access to the privileged section and will + thus see complete records. + + GetUserRecordByUID() is similar to GetUserRecordByName() + but returns the user record matching the specified numeric UID. + + ListHomes() returns an array of all locally managed users. The array + contains the same fields GetHomeByName() returns: user name, numeric UID, state, + numeric GID, real name, home directory, shell and bus path of the matching bus object. + + ActivateHome() activates (i.e. mounts) the home directory of the specified + user. The second argument shall contain a user record consisting only of a secret + section (all other sections should be stripped, see JSON + User Records for details), and should contain only the secret credentials necessary for + unlocking the home directory. Typically a client would invoke this function first with an entirely + empty record (which is possibly sufficient if single-factor authentication with a plugged-in security + token is configured), and would then retry with a record populated with more information, depending on + the returned error code, in case more credentials are necessary. This function is synchronous and + returns only after the home directory was fully activated (or the operation failed), which might take + some time. Clients must be prepared for that, and typically should extend the D-Bus method call + timeout accordingly. This method is equivalent to the Activate() method on the + org.freedesktop.home1.Home interface documented below, but may be called on the + manager object and takes a user name as additional argument, instead. + + DeactivateHome() deactivates (i.e. unmounts) the home directory of the + specified user. It is equivalent to the Deactivate() method on the + org.freedesktop.home1.Home interface documented below. + + RegisterHome() registers a new home directory locally. It receives the JSON + user record as only argument (which typically excludes the secret + section). Registering a home directory just makes the user record known to the system, it does not + create a home directory or such (which is expected to exist already, or created later). This operation + is useful to register home directories locally that are not located where + systemd-homed.service would find them automatically. + + UnregisterHome() unregisters an existing home directory. It takes a user + name as argument and undoes what RegisterHome() does. It does not attempt to + remove the home directory itself, it just unregisters it with the local system. Note that if the home + directory is placed where systemd-homed.service looks for home directories anyway + this call will only undo fixation (see below), but the record will remain known to + systemd-homed.service and be listed among known records. Since the user record is + embedded into the home directory this operation generally does not discard data belonging to the user + or their record. This method is equivalent to + Unregister() on the org.freedesktop.home1.Home + interface. + + CreateHome() registers and creates a new home directory. This takes a fully + specified JSON user record as argument (including the secret section). This registers + the user record locally and creates a home directory matching it, depending on the settings specified + in the record in combination with local configuration. + + RealizeHome() creates a home directory whose user record is already + registered locally. This takes a user name plus a user record consisting only of the + secret section. Invoking RegisterHome() followed by + RealizeHome() is mostly equivalent to calling CreateHome(), + except that the latter combines the two in atomic fashion. This method is equivalent to + Realize() on the org.freedesktop.home1.Home + interface. + + RemoveHome() unregisters a user record locally, and removes the home + directory belonging to it, if it is accessible. It takes a user name as argument. This method is equivalent to + Remove() on the org.freedesktop.home1.Home + interface. + + FixateHome() fixates an automatically discovered home + directory. systemd-homed.service automatically discovers home directories dropped + in our plugged in and adds them to the runtime list of user records it manages. A user record + discovered that way may be fixated, in which case it is copied out of the home + directory, onto persistent storage, to fixate the UID/GID assignment of the record, and extract + additional (typically previously encrypted) user record data from the home directory. A home directory + mus be fixated before it can be logged into. This method call takes a user name and a JSON user record + consisting only of the secret section as argument. This method is equivalent to + Fixate() on the org.freedesktop.home1.Home interface. + + AuthenticateHome() checks passwords or other authentication credentials + associated with the home directory. It takes a user name and a JSON user record consisting only of the + secret section as argument. Note that many of the other method calls authenticate + the user first, in order to execute some other operation. This method call only authenticates and + executes no further operation. Like ActivateHome() it is usually first invoked + with an empty JSON user record, which is then populated for subsequent tries with additional + authentication data supplied. This method is equivalent to + Authenticate() on the org.freedesktop.home1.Home + interface. + + UpdateHome() updates a locally registered user record. Takes a fully + specified JSON user record as argument (including the secret section). A user with a + matching name and realm must be registered locally already, and the last change timestamp of the newly + supplied record must be newer than the previously existing user record. Note this operation updates the + user record only, it does not propagate passwords/authentication tokens from the user record to the + storage back-end, or resizes the storage back-end. Typically a home directory is first updated, and then + the password of the underlying storage updated using ChangePasswordHome() as well + as the storage resized using ResizeHome(). This method is equivalent to + Update() on the org.freedesktop.home1.Home interface. + + ResizeHome() resizes the storage associated with a user record. Takes a user + name, a disk size in bytes and a user record consisting only of the secret section + as argument. If the size is specified as UINT64_MAX the storage is resized to the + size already specified in the user record. Typically, if the user record is updated using + UpdateHome() above this is used to propagate the size configured there-in down to + the underlying storage back-end. This method is equivalent to + Resize() on the org.freedesktop.home1.Home + interface. + + ChangePasswordHome() changes the passwords/authentication tokens of a home + directory. Takes a user name, and two JSON user record objects, each consisting only of the + secret section, for the old and for the new passwords/authentication tokens. If the + user record with the new passwords/authentication token data is specified as empty the existing user + record's settings are propagated down to the home directory storage. This is typically used after a + user record is updated using UpdateHome() in order to propagate the + secrets/authentication tokens down to the storage. Background: depending on the backend the user's + authentication credentials are stored at multiple places: the user record kept on the host, the user + record kept in the home directory and the encrypted LUKS volume slot. If the home directory is used on + a different machined temporarily, and the password is changed there, and then is moved back to the + original host, the passwords of the three might get out of sync. By issuing + ChangePasswordHome() the three locations are updated to match the newest + information. This method is equivalent to ChangePassword() on the + org.freedesktop.home1.Home interface. + + LockHome() temporarily suspends access to a home directory, flushing out any + cryptographic keys from memory. This is only supported on some back-ends, and usually done during system + suspend, in order to effectively secure home directories while the system is sleeping. Takes a user + name as single argument. If an application attempts to access a home directory while it is locked it + will typically freeze until the home directory is unlocked again. This method is equivalent to + Lock() on the org.freedesktop.home1.Home interface. + + UnlockHome() undoes the effect of LockHome(). Takes a + user name and a user record consisting only of the secret section as arguments. This + method is equivalent to Unlock() on the + org.freedesktop.home1.Home interface. + + AcquireHome() activates or unlocks a home directory in a reference counted + mode of operation. Takes a user name and user record consisting only of secret + section as argument. If the home directory is not active yet, it is activated. If it is currently + locked it is unlocked. After completion a reference to the activation/unlocking of the home directory + is returned via a file descriptor. When the last client which acquired such a file descriptor closes it + the home directory is automatically deactivated again. This method is typically invoked when a user + logs in, and the file descriptor is held until the user logs out again, thus ensuring the user's home + directory can be unmounted automatically again in a robust fashion, when the user logs out. The third + argument is a boolean which indicates whether the client invoking the call is able to automatically + re-authenticate when the system comes back from suspending. It should be set by all clients that + implement a secure lock screen running outside of the user's context, that is brought up when the + system comes back from suspend and can be used to re-acquire the credentials to unlock the user's home + directory. If a home directory has at least one client with an open reference to the home directory + that does not support this it is not suspended automatically at system suspend, otherwise it is. This + method is equivalent to Acquire() on the + org.freedesktop.home1.Home interface. + + RefHome() is similar to AcquireHome() but takes no user + record with secret section, i.e. will take an additional reference to an already + activated/unlocked home directory without attempting to activate/unlock it itself. It will fail if the + home directory is not already activated. This method is equivalent to + Ref() on the org.freedesktop.home1.Home + interface. + + ReleaseHome() releases a home directory again, if all file descriptors + referencing it are already closed, that where acquired through AcquireHome() or + RefHome(). Note that this call does not actually cause the deactivation of the + home directory (which happens automatically when the last referencing file descriptor is closed), but + is simply a synchronization mechanism that allows delaying of the user session's termination until any + triggered deactivation is completed. This method is equivalent to Release() on the + org.freedesktop.home1.Home interface. + + LockAllHomes() locks all active home directories that only have references + that opted into automatic suspending during system suspend. This is usually invoked automatically + shortly before system suspend. + + DeactivateAllHomes() deactivates all home areas that are currently + active. This is usually invoked automatically shortly before system shutdown. + + Rebalance() synchronously rebalances free disk space between home + areas. This only executes an operation if at least one home area using the LUKS2 backend is active and + has rebalancing enabled, and is otherwise a NOP. + + + + Properties + + AutoLogin exposes an array of structures consisting of user name, seat name + and object path of an home directory object. All locally managed users that have the + autoLogin field set are listed here, with the seat name they are associated with. A + display manager may watch this property and pre-fill the login screen with the users exposed this + way. + + + + + The Home Object + + +node /org/freedesktop/home1/home { + interface org.freedesktop.home1.Home { + methods: + @org.freedesktop.systemd1.Privileged("true") + Activate(in s secret); + @org.freedesktop.systemd1.Privileged("true") + Deactivate(); + Unregister(); + Realize(in s secret); + Remove(); + @org.freedesktop.systemd1.Privileged("true") + Fixate(in s secret); + Authenticate(in s secret); + Update(in s user_record); + Resize(in t size, + in s secret); + ChangePassword(in s new_secret, + in s old_secret); + @org.freedesktop.systemd1.Privileged("true") + Lock(); + @org.freedesktop.systemd1.Privileged("true") + Unlock(in s secret); + @org.freedesktop.systemd1.Privileged("true") + Acquire(in s secret, + in b please_suspend, + out h send_fd); + @org.freedesktop.systemd1.Privileged("true") + Ref(in b please_suspend, + out h send_fd); + @org.freedesktop.systemd1.Privileged("true") + Release(); + properties: + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s UserName = '...'; + readonly u UID = ...; + readonly (suusss) UnixRecord = ...; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly s State = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates") + readonly (sb) UserRecord = ...; + }; + interface org.freedesktop.DBus.Peer { ... }; + interface org.freedesktop.DBus.Introspectable { ... }; + interface org.freedesktop.DBus.Properties { ... }; + interface org.freedesktop.DBus.ObjectManager { ... }; +}; + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Methods + + Activate(), Deactivate(), + Unregister(), Realize(), Remove(), + Fixate(), Authenticate(), Update(), + Resize(), ChangePassword(), Lock(), + Unlock(), Acquire(), Ref(), + Release() operate like their matching counterparts on the + org.freedesktop.home1.Manager interface (see above). The main difference is that + they are methods of the home directory objects, and hence carry no additional user name + parameter. Which of the two flavors of methods to call depends on the handles to the user known on the + client side: if only the user name is known, it's preferable to use the methods on the manager object + since they operate with user names only. If however the home object path was already acquired some way + it is preferable to operate on the org.freedesktop.home1.Home objects + instead. + + + + Properties + + UserName contains the user name of the user account/home directory. + + UID contains the numeric UNIX UID of the user account. + + UnixRecord contains a structure encapsulating the six fields a + struct passwd typically contains (the password field is suppressed). + + State exposes the current state home the home directory. + + UserRecord contains the full JSON user record string of the user account. + + + + + + + See Also + + systemd1, + systemd-homed.service8, + homectl1 + + + + -- cgit v1.2.3