Parallel installs
managing snaps for administrators for users for snapd developers
One snap can be installed more than once. Each extra installation has an instance key and is named snap_key. The instance has its own revisions and data and services and security profiles because all of them are named after the instance name. Inside its mount namespace the snap still sees itself under its plain name.
On the map: administration district
01 Two copies on one laptop
snap install photo-editor_work installs a second instance of photo-editor. The part after the underscore is the instance key. Each instance has its own revisions, data, connections and command name. The documentation calls this parallel installs; the code says parallel instances.
You use photo-editor for your own pictures, and now for a client's too, with different presets and plugins. You'd like the two kept apart. Can you just install it twice? You can. Run snap install photo-editor_work: the snap name, an underscore, and a word you choose. Snap list now shows two rows. To the store it's still one snap. On your laptop it's two installations, each with its own revision, its own data and settings, its own connections, and its own command. The word after the underscore is the instance key, and the whole name is the instance name.
02 The instance key
The instance key matches ^[a-z0-9]{1,10}$. From the store, append it to the name; for a file use --name. Only snaps of type app can be installed with a key.
What can you put after the underscore? Less than you might hope, and that's on purpose: the key ends up in file names, unit names and profile names. It's one to ten characters, lowercase letters and digits, nothing else. The limit is on the key, not on the whole name. From the store, you just write the name with the key. A snap file has no name to append to, so there's the --name flag, and the name you give must match the snap inside the file. Only application snaps qualify: no second kernel, gadget, base or snapd. After that, refresh, remove, connect and run all take the instance name.
03 Everything outside carries the key for administrators for snapd developers
Mount directory, data directories, security tag, profiles, service units and command names are built from the instance name photo-editor_work. Desktop files use the prefix photo-editor+work.
How does snapd stop two copies of one snap from treading on each other? It has no special case for it. It changes one input. Wherever snapd builds a name from the snap, it uses the instance name. So the mount directory carries the key. So do the system-data and the user data directories. So does the security tag, and through the tag every AppArmor and seccomp profile. A service of the instance is its own systemd unit. One spelling differs: desktop file names use a plus sign instead of the underscore. So whatever you go looking for, look for the instance name.
04 Inside, the snap sees its plain name for administrators for snapd developers
The mount profile of an instance starts with two rbind entries marked x-snapd.origin=overname: /snap/photo-editor_work onto /snap/photo-editor and the same under /var/snap. SNAP and SNAP_DATA have no key; SNAP_USER_DATA, SNAP_INSTANCE_NAME and SNAP_INSTANCE_KEY do.
photo-editor was built believing it lives under /snap/photo-editor, with paths like that compiled in. What does the second copy see? Inside its mount namespace, snapd mounts the keyed snap and system-data directories over the plain ones, before layouts and the rest. The snap is shown its usual address, so $SNAP and $SNAP_DATA read just as in the first copy. Your home isn't remapped, so $SNAP_USER_DATA keeps the key. To learn which copy it is, the snap reads $SNAP_INSTANCE_NAME or $SNAP_INSTANCE_KEY. Classic instances get the same two mounts from snap-confine. On the host, the plain directories stay as mount points.
05 Snaps that cannot be doubled
An instance is refused when an app declares a bus name or a common ID, or when a plug or slot's interface does not support parallel instances. --allow-unsupported-instances installs or refreshes it anyway. The photo-editor bus name is invented for this example.
Not every snap can be doubled. Some things exist once per session, like a bus name or a display server's socket, and two copies would both reach for them. Say photo-editor owned a bus name. Installing a second copy is refused, and the message names the app. Snapd refuses an app with a bus name or a common id, and a plug or slot whose interface can't serve two instances, such as a dbus or wayland slot. If you'll only run one copy at a time, the --allow-unsupported-instances flag installs it anyway. The same check runs at refresh, and there snapd leaves a warning naming that flag.
06 What the store is told for administrators for snapd developers
Both instances are sent under the same snap-id. The request's instance-key is the bare snap-id for the plain instance and <snap-id>:<base64 of SHA-256(snap-id, key, salt)> for a keyed one, so the local key is not sent in clear.
Both copies refresh on their own. But the store only knows one photo-editor, so what does snapd tell it? Each copy is its own entry in snapd's state, with its own revision. When snapd asks about installed snaps, both go in under the same snap-id, because to the store it's one snap. To match the answers up, each entry carries an instance-key field. For the plain copy that's just the snap-id. For the keyed copy, snapd appends a hash of the snap-id, your key and a salt kept on the device. The store can tell them apart, and the word work stays on your laptop.
07 On unless you switch it off
experimental.parallel-instances is treated as enabled when unset in current snapd (the published documentation says from 2.79). Set to false, a keyed install fails with experimental feature disabled.
One switch governs everything you've just seen, and its name still says experimental. It's a system option called experimental.parallel-instances. In current snapd, it counts as on when you haven't set it, which is why the first scene just worked. Set it to false, and the next keyed install is refused, with a message that tells you which option to set. You'd want that on a fleet where a second copy of anything is a mistake. Older releases had the default the other way round, which is why many guides start by setting it to true.
08 Where to go from here
Roads: aliases, the mount namespace, confinement, packaging, services, desktop files and the store.
The instance key shows up in a lot of places, so there are a lot of roads. Aliases first, because an instance arrives without its automatic ones. The mount namespace deck shows how the namespace from scene four is built and kept. Confinement covers the profiles named after the instance. Snap packaging covers the directories the key renames. Services covers the units. And the desktop files deck explains the plus sign, while the store deck covers the refresh request.
Read more
Commands
| Command | Effect |
|---|---|
snap install <snap>_<key> | install an instance from the store |
snap install --name <snap>_<key> <file> | install a snap file under an instance name |
snap install --allow-unsupported-instances <snap>_<key> | install although a plug, slot or app does not support instances; also accepted by snap refresh |
snap set system experimental.parallel-instances=false | refuse new keyed installs |
Every other command takes the instance name where it takes a snap name, for example snap run photo-editor_work.convert and snap remove --purge photo-editor_work. A new instance is installed as if --unaliased were given, unless --prefer is given; see Aliases.
for administrators for snapd developers
What carries the key
| Thing | Plain | With key work |
|---|---|---|
| Mount directory on the host | /snap/<snap>/<rev> | /snap/<snap>_work/<rev> |
| System data | /var/snap/<snap>/ | /var/snap/<snap>_work/ |
| User data | ~/snap/<snap>/ | ~/snap/<snap>_work/ |
| Security tag | snap.<snap>.<app> | snap.<snap>_work.<app> |
| Service unit | snap.<snap>.<app>.service | snap.<snap>_work.<app>.service |
| Command | <snap>.<app> | <snap>_work.<app> |
| Desktop file prefix | <snap> | <snap>+work |
| Mount profile | /run/snapd/ns/snap.<snap>.fstab | /run/snapd/ns/snap.<snap>_work.fstab |
for administrators for snapd developers
Environment inside an instance
| Variable | Value |
|---|---|
SNAP_NAME | <snap> |
SNAP_INSTANCE_NAME | <snap>_work |
SNAP_INSTANCE_KEY | work |
SNAP | /snap/<snap>/<rev> |
SNAP_DATA | /var/snap/<snap>/<rev> |
SNAP_COMMON | /var/snap/<snap>/common |
SNAP_USER_DATA | ~/snap/<snap>_work/<rev> |
Messages
| Message | When |
|---|---|
invalid instance key: "K" | the key is not 1 to 10 lowercase letters or digits |
cannot use explicit name when installing from store | --name without a file |
cannot use instance name when installing multiple snaps | --name with several snaps |
instance name "N" does not match snap name "S" | the file is a different snap |
cannot install snap of type T as "N" | the snap is not of type app |
cannot install snap "N" as parallel instance: plug "P" with interface "I" is not supported for parallel instances: ... | also with slot |
cannot install snap "N" as parallel instance: app "A" uses bus-name which is not supported for such installation | also common-id |
refresh of snap "N" is blocked as it is not supported for parallel instances: ...; use --allow-unsupported-instances to refresh anyway | a warning, when an installed instance fails the check at refresh |
allow-unsupported-instances can only be used with parallel instances | the flag on a plain name |
allow-unsupported-instances can only be specified for install or refresh | the flag on another action |
feature flag validation failed for snap "N": experimental feature disabled - test it by setting 'experimental.parallel-instances' to true | the flag is false |
cannot run parallel installed classic snap N: the snapd native package needs updating to support parallel installed classic snaps | from snap-confine, for a classic instance |
for administrators for snapd developers
Interfaces that refuse instances
Slot side, among others: dbus, bluez, network-manager, wayland, pulseaudio, shared-memory. Plug side: desktop (when it declares desktop-file-ids). An interface that does not say otherwise is taken to support instances. Instances that were installed before these checks existed are marked as allowed by a migration.
for administrators for snapd developers
Known problem
Setting a default application with xdg-settings from inside an instance fails: snapd looks for <snap>_<key>_<name>.desktop, while the installed file is <snap>+<key>_<name>.desktop (usersession/userd/settings.go). This is recorded as a confirmed bug.
for snapd developers
In the code
Info.SnapName()is the store name;Info.InstanceName()includes the key.- State:
SnapState.InstanceKeyandSnapState.AllowUnsupportedInstances; setup:SnapSetup.InstanceKey. There is no task kind for instances. - The two overname mount entries are added before layout and general entries.
- A classic instance gets a mount namespace of its own from snap-confine for the two bind mounts.
- The store request's
instance-keyis built bygenInstanceKeyin store/store_action.go: the bare snap-id, or the snap-id, a colon and the unpadded URL-safe base64 of SHA-256 over the snap-id, the key and therefresh-privacy-keysalt kept in snapd's state.
Where the documentation differs
- The parallel installs page says in one place that the instance name can be up to 10 characters; the limit applies to the key.
- The same page lists snapd, base, kernel and gadget snaps as not installable in parallel; the rule in the code is that only type
appmay have a key.
Further reading
- Parallel installs: the main page, with the path tables and the interface table.
- Environment variables:
SNAP_INSTANCE_NAMEandSNAP_INSTANCE_KEY. - Experimental features: the
parallel-instancesflag. - Desktop interface: why
desktop-file-idsblocks an instance.
Roads from here
GETTING SNAPS
- Snap packaging — the directories of a snap that the key renames
- The store — the request in which the store sees the instance
INTERFACES AND CONFINEMENT
- Confinement — the confinement whose profile names carry the instance name
RUNNING SNAPS
- Services — the service units of an instance
ADMINISTRATION · managing a system of snaps
- Aliases — an instance is installed without its automatic aliases
DESKTOP · snaps in a user session
- Desktop files, icons and D-Bus activation — desktop files of an instance
SANDBOX INTERNALS · the mount namespace
- The per-snap mount namespace — how the per-snap mount namespace is built and kept