Migrating to v2.0

When upgrading to v2.0, manual intervention is required in some cases. This page outlines what you need to do.

The old state format

Versions 1.2 and 1.3 tracked which users and groups have been provisioned by holo-users-groups, by writing a single file like this:

$ cat /var/lib/holo/users-groups/state.toml
ProvisionedGroups = ["mygroup"]
ProvisionedUsers = ["myuser", "myotheruser"]

The new format

Version 2.0 abandons this format and uses base images and provisioned images instead. Provisioned images are created automatically after every successful holo apply and don't require manual intervention during the upgrade. The bigger change is the base image, which records the state of the user or group just before the first provisioning. This change allows holo-users-groups to make more competent decisions when cleaning up an entity that is not needed anymore.

After migrating to version 2.0, the first invocation of holo-users-groups will remove the state.toml and create empty base images for all the mentioned entities:

$ sudo holo apply
...
$ cat /var/lib/holo/users-groups/base/group:mygroup.toml
[[group]]
name = "mygroup"
$ cat /var/lib/holo/users-groups/base/user:myuser.toml
[[user]]
name = "myuser"
$ cat /var/lib/holo/users-groups/base/user:myotheruser.toml
[[user]]
name = "myotheruser"

What you need to do

These base images are empty because they only contain the name attribute. Empty base images are appropriate when the entity (the user or group) was created by holo-users-groups. If the entity did exist already, and holo-users-groups just modified some of its attributes, you need to amend the base image to describe the state of the entity before the first provisioning.

As an example, Arch Linux's default /etc/passwd contains the following http user:

$ getent passwd http
http:x:33:33:http:/srv/http:/bin/false

Now consider that we use an entity definition that sets a different home directory:

$ cat /usr/share/holo/users-groups/http-home.toml
[[user]]
name = "http"
home = "/srv/webspace"

In version 1.2/1.3 of holo-users-groups, this would change the home directory and record ProvisionedUsers = ["http"] in the state.toml. Upon migration to version 2.0, this would be converted to an empty base image:

$ cat /var/lib/holo/users-groups/base/user:http.toml
[[user]]
name = "http"

This implies that the http user was created by holo-users-groups, which is wrong! To fix this, you need to add all the entity's attributes to the base image as they were before the first provisioning (especially including the old home directory value!). The syntax is identical to entity definitions:

$ cat /var/lib/holo/users-groups/base/user:http.toml
[[user]]
name = "http"
uid = 33
group = "http"
home = "/srv/http"
shell = "/bin/false"

Tip: You can already create the non-empty base images before migrating to version 2.0. The upgrade process will recognize and use these. But be cautious: Non-empty base images must always include the actual UID or GID of the user or group.