| <?xml version='1.0'?> |
| <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
| "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" > |
| <!-- SPDX-License-Identifier: LGPL-2.1+ --> |
| |
| <refentry id="org.freedesktop.home1" conditional='ENABLE_HOMED' |
| xmlns:xi="http://www.w3.org/2001/XInclude"> |
| <refentryinfo> |
| <title>org.freedesktop.home1</title> |
| <productname>systemd</productname> |
| </refentryinfo> |
| |
| <refmeta> |
| <refentrytitle>org.freedesktop.home1</refentrytitle> |
| <manvolnum>5</manvolnum> |
| </refmeta> |
| |
| <refnamediv> |
| <refname>org.freedesktop.home1</refname> |
| <refpurpose>The D-Bus interface of systemd-homed</refpurpose> |
| </refnamediv> |
| |
| <refsect1> |
| <title>Introduction</title> |
| |
| <para><citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> |
| is a system service which may be used to create, remove, change or inspect home areas. This page |
| describes the D-Bus interface. |
| </para> |
| </refsect1> |
| |
| <refsect1> |
| <title>The Manager Object</title> |
| |
| <para>The service exposes the following interfaces on the Manager object on the bus:</para> |
| |
| <programlisting executable="systemd-homed" node="/org/freedesktop/home1" interface="org.freedesktop.home1.Manager"> |
| 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); |
| ActivateHome(in s user_name, |
| in s secret); |
| 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); |
| 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); |
| LockHome(in s user_name); |
| UnlockHome(in s user_name, |
| in s secret); |
| AcquireHome(in s user_name, |
| in s secret, |
| in b please_suspend, |
| out h send_fd); |
| RefHome(in s user_name, |
| in b please_suspend, |
| out h send_fd); |
| ReleaseHome(in s user_name); |
| LockAllHomes(); |
| properties: |
| readonly a(sso) AutoLogin = [...]; |
| }; |
| interface org.freedesktop.DBus.Peer { ... }; |
| interface org.freedesktop.DBus.Introspectable { ... }; |
| interface org.freedesktop.DBus.Properties { ... }; |
| }; |
| </programlisting> |
| |
| <!--Autogenerated cross-references for systemd.directives, do not edit--> |
| |
| <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.home1.Manager"/> |
| |
| <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.home1.Manager"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="GetHomeByName()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="GetHomeByUID()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="GetUserRecordByName()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="GetUserRecordByUID()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="ListHomes()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="ActivateHome()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="DeactivateHome()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="RegisterHome()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="UnregisterHome()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="CreateHome()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="RealizeHome()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="RemoveHome()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="FixateHome()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="AuthenticateHome()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="UpdateHome()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="ResizeHome()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="ChangePasswordHome()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="LockHome()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="UnlockHome()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="AcquireHome()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="RefHome()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="ReleaseHome()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="LockAllHomes()"/> |
| |
| <variablelist class="dbus-property" generated="True" extra-ref="AutoLogin"/> |
| |
| <!--End of Autogenerated section--> |
| |
| <refsect2> |
| <title>Methods</title> |
| |
| <para><function>GetHomeByName()</function> returns basic user information (a minimal subset of the full |
| user record), provided a user name. The information supplied more or less matches what |
| <citerefentry project='man-pages'><refentrytitle>getpwnam</refentrytitle><manvolnum>3</manvolnum></citerefentry> 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 |
| <classname>org.freedesktop.home1.Home</classname> interface documented below.</para> |
| |
| <para><function>GetHomeByUID()</function> is similar to <function>GetHomeByName()</function> but |
| acquires the information based on the numeric UID of the user.</para> |
| |
| <para><function>GetUserRecordByName()</function> is also similar to |
| <function>GetHomeByName()</function> 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 <literal>privileged</literal> section is included, and incomplete if it |
| was removed (see <ulink url="https://systemd.io/USER_RECORD">JSON User Records</ulink> 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 <literal>privileged</literal> section and will |
| thus see complete records.</para> |
| |
| <para><function>GetUserRecordByUID()</function> is similar to <function>GetUserRecordByName()</function> |
| but returns the user record matching the specified numeric UID.</para> |
| |
| <para><function>ListHomes()</function> returns an array of all locally managed users. The array |
| contains the same fields <function>GetHomeByName()</function> returns: user name, numeric UID, state, |
| numeric GID, real name, home directory, shell and bus path of the matching bus object.</para> |
| |
| <para><function>ActivateHome()</function> activates (i.e. mounts) the home directory of the specified |
| user. The second argument shall contain a user record consisting only of a <literal>secret</literal> |
| section (all other sections should be stripped, see <ulink url="https://systemd.io/USER_RECORD">JSON |
| User Records</ulink> 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 <function>Activate()</function> method on the |
| <classname>org.freedesktop.home1.Home</classname> interface documented below, but may be called on the |
| manager object and takes a user name as additional argument, instead.</para> |
| |
| <para><function>DeactivateHome()</function> deactivates (i.e. unmounts) the home directory of the |
| specified user. It is equivalent to the <function>Deactivate()</function> method on the |
| <classname>org.freedesktop.home1.Home</classname> interface documented below.</para> |
| |
| <para><function>RegisterHome()</function> registers a new home directory locally. It receives the JSON |
| user record as only argument (which typically excludes the <literal>secret</literal> |
| 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 |
| <filename>systemd-homed.service</filename> would find them automatically.</para> |
| |
| <para><function>UnregisterHome()</function> unregisters an existing home directory. It takes a user |
| name as argument and undoes what <function>RegisterHome()</function> 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 <filename>systemd-homed.service</filename> looks for home directories anyway |
| this call will only undo fixation (see below), but the record will remain known to |
| <filename>systemd-homed.service</filename> 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 |
| <function>Unregister()</function> on the <classname>org.freedesktop.home1.Home</classname> |
| interface.</para> |
| |
| <para><function>CreateHome()</function> registers and creates a new home directory. This takes a fully |
| specified JSON user record as argument (including the <literal>secret</literal> 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.</para> |
| |
| <para><function>RealizeHome()</function> creates a home directory whose user record is already |
| registered locally. This takes a user name plus a user record consisting only of the |
| <literal>secret</literal> section. Invoking <function>RegisterHome()</function> followed by |
| <function>RealizeHome()</function> is mostly equivalent to calling <function>CreateHome()</function>, |
| except that the latter combines the two in atomic fashion. This method is equivalent to |
| <function>Realize()</function> on the <classname>org.freedesktop.home1.Home</classname> |
| interface.</para> |
| |
| <para><function>RemoveHome()</function> 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 |
| <function>Remove()</function> on the <classname>org.freedesktop.home1.Home</classname> |
| interface.</para> |
| |
| <para><function>FixateHome()</function> <literal>fixates</literal> an automatically discovered home |
| directory. <filename>systemd-homed.service</filename> 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 <literal>fixated</literal>, 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 <literal>secret</literal> section as argument. This method is equivalent to |
| <function>Fixate()</function> on the <classname>org.freedesktop.home1.Home</classname> interface.</para> |
| |
| <para><function>AuthenticateHome()</function> 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 |
| <literal>secret</literal> 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 <function>ActivateHome()</function> 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 |
| <function>Authenticate()</function> on the <classname>org.freedesktop.home1.Home</classname> |
| interface.</para> |
| |
| <para><function>UpdateHome()</function> updates a locally registered user record. Takes a fully |
| specified JSON user record as argument (including the <literal>secret</literal> 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 <function>ChangePasswordHome()</function> as well |
| as the storage resized using <function>ResizeHome()</function>. This method is equivalent to |
| <function>Update()</function> on the <classname>org.freedesktop.home1.Home</classname> interface.</para> |
| |
| <para><function>ResizeHome()</function> 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 <literal>secret</literal> section |
| as argument. If the size is specified as <constant>UINT64_MAX</constant> the storage is resized to the |
| size already specified in the user record. Typically, if the user record is updated using |
| <function>UpdateHome()</function> above this is used to propagate the size configured there-in down to |
| the underlying storage back-end. This method is equivalent to |
| <function>Resize()</function> on the <classname>org.freedesktop.home1.Home</classname> |
| interface.</para> |
| |
| <para><function>ChangePasswordHome()</function> changes the passwords/authentication tokens of a home |
| directory. Takes a user name, and two JSON user record objects, each consisting only of the |
| <literal>secret</literal> 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 <function>UpdateHome()</function> in order to propagate the |
| secrets/authentication tokens down to the storage. This method is equivalent to |
| <function>ChangePassword()</function> on the <classname>org.freedesktop.home1.Home</classname> |
| interface.</para> |
| |
| <para><function>LockHome()</function> 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 |
| <function>Lock()</function> on the <classname>org.freedesktop.home1.Home</classname> interface.</para> |
| |
| <para><function>UnlockHome()</function> undoes the effect of <function>LockHome()</function>. Takes a |
| user name and a user record consisting only of the <literal>secret</literal> section as arguments. This |
| method is equivalent to <function>Unlock()</function> on the |
| <classname>org.freedesktop.home1.Home</classname> interface.</para> |
| |
| <para><function>AcquireHome()</function> activates or unlocks a home directory in a reference counted |
| mode of operation. Takes a user name and user record consisting only of <literal>secret</literal> |
| 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 <function>Acquire()</function> on the |
| <classname>org.freedesktop.home1.Home</classname> interface.</para> |
| |
| <para><function>RefHome()</function> is similar to <function>AcquireHome()</function> but takes no user |
| record with <literal>secret</literal> 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 |
| <function>Ref()</function> on the <classname>org.freedesktop.home1.Home</classname> |
| interface.</para> |
| |
| <para><function>ReleaseHome()</function> releases a home directory again, if all file descriptors |
| referencing it are already closed, that where acquired through <function>AcquireHome()</function> or |
| <function>RefHome()</function>. 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 <function>Release()</function> on the |
| <classname>org.freedesktop.home1.Home</classname> interface.</para> |
| |
| <para><function>LockAllHomes()</function> 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.</para> |
| </refsect2> |
| |
| <refsect2> |
| <title>Properties</title> |
| |
| <para><varname>AutoLogin</varname> 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 |
| <literal>autoLogin</literal> 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.</para> |
| </refsect2> |
| </refsect1> |
| |
| <refsect1> |
| <title>The Home Object</title> |
| |
| <programlisting executable="systemd-homed" node="/org/freedesktop/home1/home" interface="org.freedesktop.home1.Home"> |
| node /org/freedesktop/home1/home { |
| interface org.freedesktop.home1.Home { |
| methods: |
| Activate(in s secret); |
| Deactivate(); |
| Unregister(); |
| Realize(in s secret); |
| Remove(); |
| 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); |
| Lock(); |
| Unlock(in s secret); |
| Acquire(in s secret, |
| in b please_suspend, |
| out h send_fd); |
| Ref(in b please_suspend, |
| out h send_fd); |
| 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 { ... }; |
| }; |
| </programlisting> |
| |
| <!--Autogenerated cross-references for systemd.directives, do not edit--> |
| |
| <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.DBus.ObjectManager"/> |
| |
| <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.home1.Home"/> |
| |
| <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.DBus.ObjectManager"/> |
| |
| <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.home1.Home"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="Activate()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="Deactivate()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="Unregister()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="Realize()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="Remove()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="Fixate()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="Authenticate()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="Update()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="Resize()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="ChangePassword()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="Lock()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="Unlock()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="Acquire()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="Ref()"/> |
| |
| <variablelist class="dbus-method" generated="True" extra-ref="Release()"/> |
| |
| <variablelist class="dbus-property" generated="True" extra-ref="UserName"/> |
| |
| <variablelist class="dbus-property" generated="True" extra-ref="UID"/> |
| |
| <variablelist class="dbus-property" generated="True" extra-ref="UnixRecord"/> |
| |
| <variablelist class="dbus-property" generated="True" extra-ref="State"/> |
| |
| <variablelist class="dbus-property" generated="True" extra-ref="UserRecord"/> |
| |
| <!--End of Autogenerated section--> |
| |
| <refsect2> |
| <title>Methods</title> |
| |
| <para><function>Activate()</function>, <function>Deactivate()</function>, |
| <function>Unregister()</function>, <function>Realize()</function>, <function>Remove()</function>, |
| <function>Fixate()</function>, <function>Authenticate()</function>, <function>Update()</function>, |
| <function>Resize()</function>, <function>ChangePassword()</function>, <function>Lock()</function>, |
| <function>Unlock()</function>, <function>Acquire()</function>, <function>Ref()</function>, |
| <function>Release()</function> operate like their matching counterparts on the |
| <classname>org.freedesktop.home1.Manager</classname> 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 <classname>org.freedesktop.home1.Home</classname> objects |
| instead.</para> |
| </refsect2> |
| |
| <refsect2> |
| <title>Properties</title> |
| |
| <para><varname>UserName</varname> contains the user name of the user account/home directory.</para> |
| |
| <para><varname>UID</varname> contains the numeric UNIX UID of the user account.</para> |
| |
| <para><varname>UnixRecord</varname> contains a structure encapsulating the six fields a |
| <structname>struct passwd</structname> typically contains (the password field is suppressed).</para> |
| |
| <para><varname>State</varname> exposes the current state home the home directory.</para> |
| |
| <para><varname>UserRecord</varname> contains the full JSON user record string of the user account.</para> |
| </refsect2> |
| </refsect1> |
| |
| <refsect1> |
| <title>Versioning</title> |
| |
| <para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html"> |
| the usual interface versioning guidelines</ulink>.</para> |
| </refsect1> |
| |
| <refsect1> |
| <title>See Also</title> |
| <para> |
| <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>homectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> |
| </para> |
| </refsect1> |
| |
| </refentry> |