System usernames
a snap.yaml feature for app developers for administrators
A snap cannot ship user accounts so a daemon that starts as root has nobody to drop to. With system-usernames the snap asks for one of a few fixed names such as _daemon_. snapd creates that user and group with a fixed id while installing the snap and then writes seccomp rules that allow changing to exactly that user and AppArmor rules for three capabilities. The accounts stay when the snap is removed.
On the map: developing snaps district
01 A root daemon with nobody to become
With system usernames, a snap asks snapd for a fixed non-root user and group. snapd creates them, and the snap's seccomp and AppArmor profiles then allow dropping to that user and changing file ownership to it.
The agent's daemon starts as root. It doesn't need to stay root, and you'd sleep better if it didn't. But who is it supposed to turn into? A traditional package would create a user in its install script. A snap can't: it's a read-only image, and it doesn't get to edit the system's account database. Even if it could, the number behind the name would differ from machine to machine. So the snap asks snapd for a user from a fixed list. snapd answers with three things: the account, with a fixed id, permission to switch to that user and no other, and permission to hand files to it.
02 Asking for the user for app developers for snapd developers
system-usernames: {_daemon_: shared}. Supported names are _daemon_ (584792), the deprecated snap_daemon (584788) and three names reserved for specific store snaps. Only scope shared is supported.
You'd like to call the user acme. You can't. snapd keeps a short table of names, and you pick from it. The request is two lines of snap.yaml: under the system-usernames key, the name and its scope. The one to use is _daemon_, id 584792. snap_daemon is the older name; it's marked deprecated and still works. Three more names are reserved for particular snaps, and a snap from the store that isn't on their list is refused. The only scope that works is shared, and it means what it says: every snap that asks for this name gets the very same user.
03 The accounts appear during the install for app developers for administrators for Ubuntu Core developers for snapd developers
In mount-snap snapd ensures the user and group snapd-range-524288-root (id 524288), then runs groupadd and useradd for the requested name with its fixed id, adding --extrausers on Ubuntu Core. Accounts that already exist with the right id are left alone.
On the gateway there's no _daemon_ user yet. You run snap install. Somewhere in that change the user has to appear. When, and how? In the mount-snap task, while snapd checks the snap and before it mounts it. First a precondition: the seccomp compiler must be able to filter on arguments, because the permission rests on that. Then snapd creates a marker account named after its range of ids, so other tools see the range as taken. Then groupadd and useradd, with the fixed id, no home directory and no login shell. The gateway runs Ubuntu Core, so both go to the extrausers database.
04 Why 584792 for app developers for administrators for snapd developers
snapd's range is 524288 to 589823. snapd-range-524288-root has the first id; shared users are at offsets 60500 to 60999, so snap_daemon is 584788 and _daemon_ is 584792.
Ask for the numeric owner of the agent's files and you get 584792. That number isn't random. A distribution hands out its own ids within the first 65536. snapd set aside a block of 65536 ids further up, starting at 524288. The marker account from the install sits on the first id of that block. Inside it, shared users live at a fixed offset, from 60500 on. The first is snap_daemon, at 584788, and _daemon_ is four further along. Fixing the numbers is the point: a file owned by this user on one gateway has the same owner on the next.
05 seccomp, before and after for app developers for snapd developers
The bare setuid and setgid family is replaced by argument-filtered rules such as setuid u:_daemon_, setresuid u:_daemon_ u:_daemon_ u:_daemon_ and chown - u:_daemon_ g:_daemon_, plus setgroups 0 - and the root forms. snap-seccomp resolves the names when it compiles the profile.
The account exists. But a confined process calling setuid gets refused, account or no account. Every snap's seccomp profile lists the setuid family bare, and AppArmor doesn't grant the capability, so the calls fail. Ask for a system username and that's replaced. Now each rule names its argument: setuid to _daemon_, setgid to its group, the three-argument forms for a permanent drop, and chown to that user and group. Clearing the supplementary groups is allowed, and so is root. The names become numbers when the profile is compiled, so the account had to exist first.
06 The drop itself for app developers
Every app and hook profile gets capability setuid, setgid and chown. dac_override, dac_read_search and kill are not granted. Change file ownership first, then setgroups(0, …), setgid, setuid.
The account and seccomp rules are in place. When the daemon drops root, order matters. AppArmor now grants three capabilities: setuid, setgid and chown. While still root, the daemon gives its spool directory to _daemon_. It clears the supplementary groups, changes the group, and changes the user last, because after that it can't do the others. The capabilities that let root ignore file permissions, or signal other users' processes, are left out on purpose. So a directory you forgot to chown stays out of reach. Hooks get the same rules, so the install hook is a good place for that chown.
07 What can block it, and what stays for app developers for administrators
A pre-existing user or group with the same name and another id, or only one of the two, fails the install with cannot ensure users for snap …. The accounts are not removed with the snap and are reused.
An administrator asks two things about anything touching accounts: what if the name is taken, and what's left behind? snapd won't take over an account it doesn't recognise. If a user or group with this name exists under another id, or only one of the pair exists, the install stops before the snap is mounted, and the error says which. Rename or remove the conflicting account. Now remove the agent. The user and the range marker are still there. snapd doesn't delete them, and the next snap that asks gets the same user back. Shared means shared: to the file system, every snap using that name is one user.
08 Where to go from here
Roads: confinement, services, local installs and policy for snaps without a snap-id, run and debug, the lifecycle hooks and the overview.
An account, a handful of seccomp rules, three capabilities. That's all a system username is, and each piece is explained further elsewhere. Confinement shows the seccomp and AppArmor profiles these rules are added to. Services covers the daemon that starts as root in the first place. While you develop, your snap has no snap-id, and try and pack, and when snapd asks, cover what that changes. To try the drop by hand, run and debug shows how to get a shell inside the snap. The lifecycle hooks deck covers the install hook, a good place for the chown. Or head back to the overview.
Read more
Supported names
| Name | uid and gid | Who may use it |
|---|---|---|
_daemon_ | 584792 | any snap |
snap_daemon | 584788 | any snap; deprecated in favour of _daemon_ |
snap_microk8s | 584789 | the microk8s snap |
snap_aziotedge | 584790 | the azure-iot-edge snap |
snap_aziotdu | 584791 | the deviceupdate-agent snap |
The three reserved names are tied to snap-ids. The check is made only for snaps that have a snap-id, which is intended: a snap installed with --dangerous or snap try has none and may use any of the five names.
Syntax
system-usernames: _daemon_: shared
The long form is a map with scope: shared. Only shared is supported; private and external are recognised and refused.
Errors
| Message | Cause |
|---|---|
invalid system username "<name>" | the name does not match the allowed pattern |
system username "<name>" does not specify a scope | the long form has no scope |
snap "<snap>" requires unsupported system username "<name>" | the name is not in snapd's table |
snap "<snap>" is not allowed to use the system user "<name>" | a reserved name and a snap-id that is not listed |
snap "<snap>" requires unsupported user scope "<scope>" for this version of snapd | scope private or external |
snap "<snap>" system usernames require a snapd built against ... | the seccomp compiler cannot filter on arguments |
cannot ensure users for snap "<snap>" required system username "<name>": ... | the account could not be created or does not match |
found unexpected uid for user "<name>": <id> | a user of that name exists with another id |
found unexpected gid for group "<name>": <id> | a group of that name exists with another id |
cannot add user/group "<name>": group exists and user does not | only one of the pair exists (also the reverse) |
The id range
| Ids | Use |
|---|---|
| 524288 to 589823 | snapd's range, 65536 ids |
| 524288 | snapd-range-524288-root, the marker user and group |
| 584788 to 585287 | shared users (offsets 60500 to 60999) |
for administrators for Ubuntu Core developers for snapd developers
How the accounts are created
| Step | Command |
|---|---|
| group | groupadd --system --gid <id> <name> |
| user | useradd --system --home-dir /nonexistent --no-create-home --shell <false> --gid <id> --no-user-group --uid <id> <name> |
| on Ubuntu Core | both with --extrausers |
This happens in the mount-snap task of every install and refresh of a snap with the key, while snapd checks the snap and before it is mounted. The marker account snapd-range-524288-root is ensured first, then the requested name. If useradd fails the group is deleted again. Existing accounts with the expected ids are left as they are. Nothing removes the accounts when the snap is removed.
for app developers for snapd developers
What the profiles allow
| Profile | With system-usernames |
|---|---|
| seccomp | setuid, setreuid, setresuid to u:<name> in the forms for a permanent drop, for seteuid and for keeping root as the saved id; the same for the gid family with g:<name>; chown, fchown, fchownat, lchown to <name>:<name>, to the user only, to the group only, to <name>:root and to root:<name>; setgroups 0 -; setting uid or gid to root |
| AppArmor | capability setuid, capability setgid, capability chown, in every app and hook profile |
| not granted | dac_override, dac_read_search, kill |
Without the key, the seccomp profile lists the setuid and setgid family without argument filters and AppArmor grants none of these capabilities. snap-seccomp turns u:<name> and g:<name> into numbers when it compiles the profile, so the account has to exist before the profile is built.
The order for a daemon: change file ownership, setgroups(0, ...), setgid, setuid. Layout user and group do not accept these names.
Further reading
- System usernames: the published explanation, with examples of dropping privileges, signals and file ownership.
- The snap format: the
system-usernameskey. It names the old usersnap-daemon; the name in snapd issnap_daemon, and there are five names, not two. - Security policies: the seccomp side that a user and group change has to pass.
Roads from here
START HERE
- snapd — back to the overview
INTERFACES AND CONFINEMENT
- Confinement — the seccomp and AppArmor profiles these rules are added to
RUNNING SNAPS
- Services — the daemon that starts as root and drops its privileges
HOOKS · code snapd runs inside a snap
- Hooks: install, configure, refresh, remove — the install hook where data is usually handed to the user
POLICY · who may install and connect what
- When snapd asks — what else differs for a snap without a snap-id
DEVELOPING SNAPS · try, pack, run, debug
- Trying and packing a snap — local installs which have no snap-id
- Running and debugging an app — a shell inside the snap to try the drop by hand