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

▶ Watch this deck — 8 scenes, ~6 min

01 A root daemon with nobody to become

SYSTEM USERNAMES acme-agent's daemonrunning as rootwants to give up root after start-up an unprivileged user?a snap is read-only: it cannot add one,and ids differ from machine to machine the snap asks for a userby a fixed namesnapd 1 · an accountthe same id on every system 2 · may switch to itto that user and no other 3 · may hand files to itchange their owner to that user
acme-agent's daemon runs as root and wants to give up root, but a read-only snap cannot add an unprivileged user; the snap asks snapd for a user by a fixed name and snapd answers with three things: an account with the same id on every system, permission to switch to that user and no other, and permission to hand files to it

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

THE KEY snap.yamlsystem-usernames:_daemon_: shared 1 · is the name in snapd's table?_daemon_ · 584792snap_daemon · 584788 · deprecated, still workssnap "acme-agent" requires unsupported system username "daemon" 2 · is this snap allowed that name?three more names are reserved for particular store snapssnap "acme-agent" is not allowed to use the system user "snap_microk8s" 3 · is the scope shared?snap "acme-agent" requires unsupported user scope "private" for this version of snapd shared: every snap that asks for _daemon_ gets the same user
Two lines of snap.yaml, system-usernames with _daemon_: shared, then three checks in the order snapd makes them, each with its refusal: the name must be in snapd's table (_daemon_ is 584792, snap_daemon is 584788 and deprecated), a store snap may use a reserved name only if it is on that name's list, and the scope must be shared

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

CREATING THE USER accounts on the gateway: no _daemon_ yet mount-snap: check the snapbefore the snap is mounted, on everyinstall and refresh of a snap with the key can the seccomp compilerfilter on arguments?if not: the install stops and nameswhat snapd must be built against snapd-range-524288-root · 524288marks the range as taken group _daemon_ · 584792user _daemon_ · 584792no home, no login shellgroupadd --system --gid 584792 _daemon_useradd --system --uid 584792 --gid 584792--no-create-home --home-dir /nonexistent--no-user-group ... _daemon_ + --extrausers on Ubuntu Core$ getent passwd _daemon_lists the new user afterwards
During snap install, the mount-snap task checks the snap before mounting it: the seccomp compiler must filter on arguments, then snapd ensures snapd-range-524288-root with id 524288, then runs groupadd and useradd for _daemon_ with id 584792, no home directory and no login shell, adding --extrausers on Ubuntu Core

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

ONE RANGE OF IDS 0user ids, not to scale a distribution's users:within the first 65536 524288 to 589823one block of 65536 ids, set aside by snapd 524288snapd-range-524288-root offsets 60500 to 60999:shared users 584788 · snap_daemon584792 · _daemon_ same name, same number on every system: a file owned by _daemon_ on one gateway has the same owner on the next
A number line of user ids, not to scale: a distribution's own ids within the first 65536; snapd's block of 65536 ids from 524288 to 589823; snapd-range-524288-root on the first id; shared users at offsets 60500 to 60999, where snap_daemon is 584788 and _daemon_ is 584792

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 SECCOMP PROFILE without the keysetuidsetgidsetresuidsetresgid...allowed as system calls, butAppArmor does not grant CAP_SETUIDor CAP_SETGID, so they fail anyway with _daemon_: sharedsetuid u:_daemon_setgid g:_daemon_ setresuid u:_daemon_ u:_daemon_ u:_daemon_permanent drop chown - u:_daemon_ g:_daemon_fchown - u:_daemon_ g:_daemon_ setgroups 0 -clear supplementary groupssetuid u:rootsetgid g:rootroot itself stays allowed... u:_daemon_584792resolved by snap-seccomp when it compiles the profile,so the account must exist first
Two seccomp profiles side by side. Without the key: setuid, setgid, setresuid and setresgid listed bare, and AppArmor withholds the capabilities so they fail. With _daemon_: shared: setuid u:_daemon_, setgid g:_daemon_, setresuid to _daemon_ three times for a permanent drop, chown and fchown to _daemon_:_daemon_, setgroups 0 and the root forms; snap-seccomp turns _daemon_ into 584792 when it compiles the profile, so the account must exist first

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

DROPPING PRIVILEGES capability setuid,capability setgid,capability chown,added to every app and hook profile of the snap chown _daemon_:_daemon_ $SNAP_COMMON/spoolroot setgroups(0, ...)no supplementary groupsrootsetgid(_daemon_)root setuid(_daemon_)last: no way back_daemon_ dac_override · dac_read_search · killleft out on purpose: root in the snap stillobeys file permissions, so hand files overwhile root, before the drop hooks get the same rules: the install hook is a good place for the chown
The AppArmor profile gains capability setuid, setgid and chown in every app and hook profile. The daemon then, while root, changes the owner of its spool directory to _daemon_, calls setgroups with zero, setgid and finally setuid, after which it runs as _daemon_. dac_override, dac_read_search and kill are left out on purpose, so a directory not handed over stays out of reach; hooks get the same rules

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

FOR THE ADMINISTRATOR before the installafter the removal this system already has a user_daemon_ with id 1001 $ snap install acme-agent... cannot ensure users for snap"acme-agent" required system username"_daemon_": found unexpected uid foruser "_daemon_": 1001 or: a group of that name without the user, or the reversecannot add user/group "_daemon_":group exists and user does notfix: rename or remove that account $ snap remove acme-agent$ getent passwd _daemon_still there snapd-range-524288-root · _daemon_kept, and reused by the next snap that asks shared means shared: every snap that uses _daemon_ is the same user to the file system
Before the install: a system that already has a user _daemon_ with id 1001 makes snap install acme-agent fail with cannot ensure users for snap, found unexpected uid for user _daemon_: 1001; a group without the user, or the reverse, fails too; the fix is to rename or remove that account. After the removal: snap remove acme-agent leaves _daemon_ and snapd-range-524288-root in place, and the next snap that asks gets the same user

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 System usernames Confinementthe two profilesServicesthe daemon that starts as root Try and packlocal installs, no snap-idWhen snapd askspolicy without a snap-id Run and debugtry the drop from a shell Lifecycle hooksthe install hook, for the chown The overview
Roads from System usernames: Confinement, Services, Try and pack, When snapd asks, Run and debug, Hooks, and back to the overview

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

Nameuid and gidWho may use it
_daemon_584792any snap
snap_daemon584788any snap; deprecated in favour of _daemon_
snap_microk8s584789the microk8s snap
snap_aziotedge584790the azure-iot-edge snap
snap_aziotdu584791the 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

MessageCause
invalid system username "<name>"the name does not match the allowed pattern
system username "<name>" does not specify a scopethe 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 snapdscope 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 notonly one of the pair exists (also the reverse)

The id range

IdsUse
524288 to 589823snapd's range, 65536 ids
524288snapd-range-524288-root, the marker user and group
584788 to 585287shared users (offsets 60500 to 60999)

for administrators for Ubuntu Core developers for snapd developers

How the accounts are created

StepCommand
groupgroupadd --system --gid <id> <name>
useruseradd --system --home-dir /nonexistent --no-create-home --shell <false> --gid <id> --no-user-group --uid <id> <name>
on Ubuntu Coreboth 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

ProfileWith system-usernames
seccompsetuid, 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
AppArmorcapability setuid, capability setgid, capability chown, in every app and hook profile
not granteddac_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-usernames key. It names the old user snap-daemon; the name in snapd is snap_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

POLICY · who may install and connect what

DEVELOPING SNAPS · try, pack, run, debug