Merge pull request #16841 from keszybz/acl-util-bitmask

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

diff --git a/docs/USER_GROUP_API.md b/docs/USER_GROUP_API.md
index 3530f00d0d5e0587ad743f74cfaefd6f67a0a8b5..ca88b3a16d9ce1732360d9f8b0b3feda4bc4ac86 100644 (file)
--- a/docs/USER_GROUP_API.md
+++ b/docs/USER_GROUP_API.md
@@ -95,7 +95,7 @@ services are listening there, that have special relevance:
 2. `io.systemd.Multiplexer` → This service multiplexes client queries to all
    other running services. It's supposed to simplify client development: in
    order to look up or enumerate user/group records it's sufficient to talk to
-   one service instead of all of them in parallel. Note that it is not availabe
+   one service instead of all of them in parallel. Note that it is not available
    during earliest boot and final shutdown phases, hence for programs running
    in that context it is preferable to implement the parallel lookup
    themselves.
@@ -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
@@ -160,7 +164,7 @@ method GetUserRecord(
         service : string
 ) -> (
         record : object,
-        incomplete : boolean
+        incomplete : bool
 )
 
 method GetGroupRecord(
@@ -169,7 +173,7 @@ method GetGroupRecord(
         service : string
 ) -> (
         record : object,
-        incomplete : boolean
+        incomplete : bool
 )
 
 method GetMemberships(
@@ -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.