holo-users-groups.8.pod

NAME

holo-users-groups - Holo plugin to provision user accounts and groups

DESCRIPTION

This plugin provisions UNIX user accounts to passwd(5), and groups to group(5). Provisioning uses the standard commands useradd(8), usermod(8), userdel(8), groupadd(8), groupmod(8) and groupdel(8).

Entity definitions are placed at /usr/share/holo/users-groups/*.toml and are written in TOML. The following fields are accepted for users and groups:

[[group]]
name    = "mygroup"            # string,  the group name
system  = false                # if true, gives --system to groupadd
gid     = 1001                 # integer, given to groupadd as --gid

[[user]]
name    = "myuser"             # string,  the user name
system  = false                # if true, gives --system to useradd
comment = "My Own User"        # string,  given to useradd as --comment
uid     = 1023                 # integer, given to useradd as --uid
group   = "mygroup"            # string,  given to useradd as --gid
groups  = [ "audio", "video" ] # strings, given to useradd as --groups
home    = "/var/lib/myuser"    # string,  given to useradd as --home-dir
shell   = "/usr/bin/zsh"       # string,  given to useradd as --shell

In either case, name is the only required attribute. Multiple entity definitions may apply to the same entity if they have the same name attribute. This can be useful if a base hologram creates the entity and a later hologram requires more specific configuration for this entity. When entity definitions are stacked on each other, they are not allowed to contradict one another. (Different lists of auxiliary groups are allowed and will be merged.)

The entity names for users and groups are user:$name and group:$name, respectively, where $name is the user name or group name.

Apply operation

Ensure that the entity is present on the system and conforms to the entity definition. --force is required to overwrite properties that conflict between the actual state and the entity definition.

When an entity is applied for the first time, the previous state of the entity is saved into /var/lib/holo/users-groups/base/$entity_id.toml. If the entity did not exist before, the base image will only contain the type and name. The base image will be restored by holo apply when all definition files for this entity are deleted.

Whenever an entity is successfully applied, its state will be recorded into /var/lib/holo/users-groups/provisioned/$entity_id.toml. This provisioned image will be used for diffing.

Merging of attributes

The desired state of the entity is computed by merging each attribute of the entity definition into the base image at /var/lib/holo/users-groups/base/$entity_id.toml. For most attributes, merging succeeds if the attribute is set by only one side or the other (or by neither side), or if the attribute is set to the same value on both sides.

As an exception, the groups field (the list of auxiliary groups) of a user definition is merged by compiling a list of all groups mentioned on either side. For example, if /etc/passwd contains a user http by default, which is part of the auxiliary group grp1, and you then add an entity definition like so:

[[user]]
name = "http"
groups = ["grp2"]

Then after holo apply user:http, the user will be part of both grp1 and grp2. If you want to overwrite the set of auxiliary groups from the base image, set the skipBaseGroups flag like so:

[[user]]
name = "http"
groups = ["grp2"]
skipBaseGroups = true

Diff operation

Display a diff if the current state of the entity conflicts with the entity definition. The right side of the diff is always a serialization of the actual state of the entity, as stated by /etc/passwd and/or /etc/group. For example:

diff --holo /var/lib/holo/users-groups/provisioned/user:wrongshell.toml /tmp/holo/users-groups/user:wrongshell/actual.toml
--- /var/lib/holo/users-groups/provisioned/user:wrongshell.toml
+++ /tmp/holo/users-groups/user:wrongshell/actual.toml
@@ -3,4 +3,4 @@ name = "wrongshell"
 uid = 1005
 home = "/home/wrongshell"
 group = "users"
-shell = "/bin/zsh"
+shell = "/bin/bash"

For entities that have been applied at least once, the left side of the diff is /var/lib/holo/users-groups/provisioned/$entity_id.toml. For entities that have not been applied yet, the left side of the diff is the "desired state", obtained by merging the entity definition with the actual state. If any attributes have conflicting values, the entity definition takes precedence.

SEE ALSO

holo(8) provides the user interface for using this plugin.

AUTHOR

Stefan Majewsky

Further documentation is available at the project homepage: https://holocm.org

Please report any issues and feature requests at GitHub: https://github.com/holocm/holo/issues