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

▶ Watch this deck — 8 scenes, ~6 min

01 Two copies on one laptop

PARALLEL INSTALLS $ sudo snap install photo-editor_work $ snap listName Version Revphoto-editor 2.4 42photo-editor_work 2.4 42 store: photo-editorone snap in the storephoto-editorphoto-editor_work datadataown revision, own settings and files, own connections $ photo-editor_workits own command photo-editor_work is the instance namework is the instance key
snap install photo-editor_work adds a second row to snap list; photo-editor and photo-editor_work are one snap in the store but two installations, each with its own data and its own command

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 NAME photo-editor_worksnap nameinstance key 1 to 10 characters: a to z, 0 to 9invalid instance key: "Work-2" $ sudo snap install photo-editor_workfrom the store: put the key in the name $ sudo snap install --dangerous \--name photo-editor_work ./photo-editor_2.4_amd64.snapfrom a file: the --name flag $ sudo snap install pc_twocannot install snap of type gadget as "pc_two"only app snaps can have a key then every command takes the instance name: snap refresh, remove, connect, run photo-editor_work
The name photo-editor_work split into the snap name and the instance key; the key is 1 to 10 lowercase letters or digits; from the store the key goes in the name, for a file the --name flag gives it; a gadget snap cannot be installed with a 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

ON THE HOST photo-editor_work mounted at/snap/photo-editor_work/42 system data/var/snap/photo-editor_work/user data~/snap/photo-editor_work/ security tagsnap.photo-editor_work.convertAppArmor and seccomp use it service unitsnap.photo-editor_work.<app>.serviceif the snap has services one exception in spelling: desktop files use photo-editor+work as their prefix
photo-editor_work in the centre with five names built from it: the mount directory, the system and user data directories, the security tag that names the profiles, and the service unit; desktop files use photo-editor+work

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

INSIDE THE NAMESPACE hostinside photo-editor_work /snap/photo-editor_work/var/snap/photo-editor_work /snap/photo-editor/var/snap/photo-editorrbind, x-snapd.origin=overname what the app sees inside photo-editor_workSNAP=/snap/photo-editor/42SNAP_DATA=/var/snap/photo-editor/42 SNAP_USER_DATA=/home/alice/snap/photo-editor_work/42the home directory keeps the key SNAP_NAME=photo-editorSNAP_INSTANCE_NAME=photo-editor_workSNAP_INSTANCE_KEY=workwhich copy am I? classic instances: the sametwo mounts, from snap-confine on the host, /snap/photo-editor and /var/snap/photo-editor exist as mount points while any instance is installed
On the host /snap/photo-editor_work and /var/snap/photo-editor_work are bind-mounted onto /snap/photo-editor and /var/snap/photo-editor inside the instance; SNAP and SNAP_DATA have no key, SNAP_USER_DATA, SNAP_INSTANCE_NAME and SNAP_INSTANCE_KEY do

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

REFUSED photo-editorphoto-editor_workone name on the session bus $ sudo snap install photo-editor_workcannot install snap "photo-editor_work" as parallel instance:app "photo-editor" uses bus-name which is not supported for such installation refused when:an app's D-Bus namean app's common-idsome plugs and slots,such as a dbus or wayland slot $ sudo snap install --allow-unsupported-instances photo-editor_workinstalls anyway; the clash is then yours to manage an instance that later becomes unsupported has its refresh blocked,and snapd records a warning that names this flag
photo-editor and photo-editor_work both reach for one name on the session bus; the second is refused with an error naming the app and bus-name; --allow-unsupported-instances installs it anyway

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

THE REFRESH REQUEST snapdphoto-editorphoto-editor_workown revision, own tracking snap-id: <id of photo-editor>instance-key: <id>store snap-id: <id of photo-editor>instance-key: <id>:<hash> hash: SHA-256 of snap-id, key and saltURL-safe base64, salt kept on the device one answer per entrythe word "work" does not leave the laptop
snapd sends both photo-editor and photo-editor_work to the store under the same snap-id; the plain one has the snap-id as its instance-key, the keyed one the snap-id and a salted SHA-256 hash; the store answers each entry

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

THE FLAG experimental.parallel-instancesunset: onfalse: offa system option; the name still says experimental $ sudo snap set system experimental.parallel-instances=falsefalse: off $ sudo snap install photo-editor_clientfeature flag validation failed for snap "photo-editor_client":experimental feature disabled - test it by setting 'experimental.parallel-instances' to true older snapd releases had it off by default; there you set it to true first
The option experimental.parallel-instances is on when unset; snap set system experimental.parallel-instances=false switches it off and a keyed install then fails with experimental feature disabled

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 Parallel installsAliasesinstances start unaliased The mount namespacehow it is built and kept Confinementprofiles named after the instance Snap packagingthe directories the key renames Servicesthe units of an instance Desktop filesthe photo-editor+work prefixThe storethe refresh request
Roads from Parallel installs: aliases, the mount namespace, confinement, snap packaging, services, desktop files and the store

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

CommandEffect
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=falserefuse 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

ThingPlainWith 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 tagsnap.<snap>.<app>snap.<snap>_work.<app>
Service unitsnap.<snap>.<app>.servicesnap.<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

VariableValue
SNAP_NAME<snap>
SNAP_INSTANCE_NAME<snap>_work
SNAP_INSTANCE_KEYwork
SNAP/snap/<snap>/<rev>
SNAP_DATA/var/snap/<snap>/<rev>
SNAP_COMMON/var/snap/<snap>/common
SNAP_USER_DATA~/snap/<snap>_work/<rev>

Messages

MessageWhen
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 installationalso common-id
refresh of snap "N" is blocked as it is not supported for parallel instances: ...; use --allow-unsupported-instances to refresh anywaya warning, when an installed instance fails the check at refresh
allow-unsupported-instances can only be used with parallel instancesthe flag on a plain name
allow-unsupported-instances can only be specified for install or refreshthe flag on another action
feature flag validation failed for snap "N": experimental feature disabled - test it by setting 'experimental.parallel-instances' to truethe flag is false
cannot run parallel installed classic snap N: the snapd native package needs updating to support parallel installed classic snapsfrom 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.InstanceKey and SnapState.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-key is built by genInstanceKey in 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 the refresh-privacy-key salt 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 app may have a key.

Further reading

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

SANDBOX INTERNALS · the mount namespace