service: add new RootImageOptions feature

[thirdparty/systemd.git] / docs / USER_GROUP_API.md

diff --git a/docs/USER_GROUP_API.md b/docs/USER_GROUP_API.md
index ebff6e69034fb7baa0744acd8104376e10c1b2ed..ca88b3a16d9ce1732360d9f8b0b3feda4bc4ac86 100644 (file)
--- a/docs/USER_GROUP_API.md
+++ b/docs/USER_GROUP_API.md
@@ -108,7 +108,7 @@ example, introspection is not available, and the resolver logic is not used.
 
 ## Other Services
 
-The `systemd` project provides two other services implementing this
+The `systemd` project provides three other services implementing this
 interface. Specifically:
 
 1. `io.systemd.DynamicUser` → This service is implemented by the service
@@ -119,6 +119,10 @@ interface. Specifically:
    and provides records for the users and groups defined by the home
    directories it manages.
 
+3. `io.systemd.Machine` → This service is implemented by
+   `systemd-machined.service` and provides records for the users and groups used
+   by local containers that use user namespacing.
+
 Other projects are invited to implement these services too. For example it
 would make sense for LDAP/ActiveDirectory projects to implement these
 interfaces, which would provide them a way to do per-user resource management
@@ -185,6 +189,7 @@ error NoRecordFound()
 error BadService()
 error ServiceNotAvailable()
 error ConflictingRecordFound()
+error EnumerationNotSupported()
 ```
 
 The `GetUserRecord` method looks up or enumerates a user record. If the `uid`
@@ -264,4 +269,11 @@ services. Result of this is that it can be one service that defines a user A,
 and another service that defines a group B, and a third service that declares
 that A is a member of B.
 
+Looking up explicit users/groups by their name or UID/GID, or querying
+user/group memberships must be supported by all services implementing these
+interfaces. However, supporting enumeration (i.e. user/group lookups that may
+result in more than one reply, because neither UID/GID nor name is specified)
+is optional. Services which are asked for enumeration may return the
+`EnumerationNotSupported` error in this case.
+
 And that's really all there is to it.