handling subids and subuids

admin-guide/container.md

@@ -23,3 +23,35 @@ base::pkg_group::extra:
   - 'docker' 
 ```
 This will install podman from the appstream repository.
+
+### Subuids and Subgids
+
+To be able to run rootless containers with podman you need to define a subuid/subgid range for each user which should be able to launch containers with `podman` in `/etc/subuid` and `/etc/subgid`.
+
+To be able to have these ids consistent PSI wide there is a small central database/API to register and lookup such IDs.
+
+The API endpoint is `https://sysdb.psi.ch/subid/v1/config` and allows for one or more `user` parameters. It will then return the line(s) you need to add to `/etc/subuid` and `/etc/subgid`.
+
+Note that the ID is now reserved for 2 years. With every lookup with the API the reservation gets renewed. After it timed out the ID range will be freed and will be used by someone else.
+
+
+**Examples:**
+
+This will get the ID range (the same for both subuid and subgid) for your user.
+```
+curl "https://sysdb.psi.ch/subid/v1/config?user=$USER"
+```
+This will get the ID range (the same for both subuid and subgid) for your user.
+
+And for several users:
+
+```
+USER1=...
+USER2=...
+USER3=...
+curl "https://sysdb.psi.ch/subid/v1/config?user=$USER1&user=$USER2&user=$USER3"
+```
+
+**Future Work**:
+- Puppet integration
+- automatic refresh on login