Apps, command lines and environment

app entries in snap.yaml for app developers

The command an app entry names is not run as written. snap-exec puts the command-chain programs in front and expands variables in the arguments from snap.yaml and appends what the user typed. The environment is assembled by three programs in turn - snap run and snap-confine and snap-exec - and the snap's own environment entries are applied last. assumes states what the snap needs from snapd and is checked at install.

On the map: developing snaps district

▶ Watch this deck — 8 scenes, ~6 min

01 What runs when you type the command

ONE COMMAND, AS RUN $ acme-agent.ctl statuswhat you type what actually runsstatuswhat you typed the app's program and its fixed optionsfrom the snap a helper that runs firstfrom the snap the environment it runs inset by the snapwhatever the snap defined for itself, applied lastset by snapdwhere the snap's files are, where its data goesfrom your terminalinherited, unless a layer above replaces it the developer wrote all of this in one short app entry; snap-exec reads it just before the program starts
The typed command acme-agent.ctl status, and below it the longer command line that actually runs: a helper from the snap, then the app's program with its fixed options, then the typed word status; under it the environment in three layers: from your terminal, set by snapd, set by the snap on top

What runs is the snap's helper programs, then the app's program with the options its developer fixed, then your arguments. The environment comes from your terminal, from snapd and from the snap, in that order.

You type acme-agent.ctl, status. Two words. What actually gets executed is quite a bit longer. Status, the word you typed, comes last. In front of it sits the app's own program, with options the developer fixed. And in front of that, a helper the snap wants to run first. It all runs with variables you didn't set: where the snap's files are, where its data goes, plus whatever the snap defined for itself. The developer wrote it down in one short app entry, and snap-exec reads it just before your program starts. This deck reads that entry, one key at a time.

02 How the command line is built for app developers for snapd developers

COMMAND command: bin/acme-ctl --config $SNAP_DATA/agent.conf split at single spaces: no quoting, no shell /snap/acme-agent/42/bin/acme-ctlthe first piece, under the snap's directory --config/var/snap/acme-agent/42/agent.conf$SNAP_DATA, expanded from the environmentthe other pieces: arguments statuswhat the user typed: appended, not expanded command: bin/acme-ctl --name "my agent"app description field 'command' contains illegal "bin/acme-ctl --name \"my agent\"" (legal: …)quotes are refused at validation; an argument that expands to nothing is dropped; for a shell, point command at a script
The line command: bin/acme-ctl --config $SNAP_DATA/agent.conf cut at its spaces into three pieces; the first becomes /snap/acme-agent/42/bin/acme-ctl, then --config, then /var/snap/acme-agent/42/agent.conf with $SNAP_DATA expanded, then the user's word status appended unchanged; below, a command with quotes is refused by validation

command is split at single spaces. The first word is made absolute under $SNAP; $VAR in the other words is expanded and empty results are dropped; the user's arguments follow unchanged. Quote characters are not allowed.

The command line in snap.yaml looks like something you'd type into a shell. It isn't, and the difference matters the first time you want a space in an argument. No shell reads it. snap-exec cuts it at every space. The first piece is a path inside the snap, and snap pack already checked that it's executable. The other pieces are arguments. A dollar variable in them is filled in from the environment, and if one comes out empty, it's dropped. Then whatever the user typed is added, untouched. Quotes would only raise false hopes, so validation refuses them. Need a shell? Point command at a script.

03 "command-chain: programs that run first" for app developers for snapd developers

COMMAND-CHAIN command-chain: [bin/load-env] bin/load-envargs: $SNAP/bin/acme-ctl --config … statusruns first, given the rest of the line export ACME_TOKEN=…; exec "$@"execbin/acme-ctl --config … statusthe app, with the token already set snapd's own test: [chain1, chain2] in front of hellochain1chain2hellooutput: chain1 chain2 hello appsserviceshooksthe same key on all three$ snap run --shell acme-agent.ctlthe chain runs in front of the debugging shell too no arguments: a chain entry is a path only
command-chain: [bin/load-env]. load-env runs first, receives the rest of the command line, sets a token and execs bin/acme-ctl; snapd's test runs chain1 and chain2 before hello; the key works for apps, services and hooks, and also in front of snap run --shell; a chain entry takes no arguments

command-chain lists programs, relative to the snap, that are put in front of the command. Each receives the remaining command line and is expected to exec it. Entries take no arguments. Apps, services and hooks accept the key.

The control tool needs a token loaded before it starts. So do two other apps and the configure hook. Where do you put that step, once? In command-chain. Each entry is a program in the snap. snap-exec puts them in front of the command, in order, so the first one is what actually runs, with the rest of the line as its arguments. It does its work, then execs the rest. snapd's own test chains two in front of hello. The key works on apps, services and hooks, and it even runs in front of snap run --shell. One limit: an entry can't take arguments.

04 Three programs build the environment for app developers for snapd developers

WHO SETS WHAT your terminalLANGTERMDISPLAYPATH…inherited unlessreplaced to the right snap runSNAP, SNAP_DATASNAP_COMMONSNAP_NAMESNAP_REVISIONSNAP_APP_NAME=ctlSNAP_UID, SNAP_EUIDHOMEXDG_RUNTIME_DIRoverrides whateverwas inherited snap-confinePATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/gamesSNAP_COOKIEPATH is reset fora confined snap snap-execACME_HOMEACME_LOGthe snap's environment,applied last a PATH exported in your terminal does not reach a confined appapplied last, the snap's own entries can replace anything to their left, for the snap's own processes
Four columns from left to right: your terminal passes LANG, TERM, DISPLAY and PATH; snap run sets SNAP, SNAP_DATA, SNAP_COMMON, SNAP_NAME, SNAP_REVISION, SNAP_APP_NAME, SNAP_UID, SNAP_EUID, HOME and XDG_RUNTIME_DIR and overrides inherited values; snap-confine resets PATH to a fixed list for a confined snap and sets SNAP_COOKIE; snap-exec applies the snap's own environment, ACME_HOME and ACME_LOG, last

snap run sets the SNAP_* variables, HOME and XDG_RUNTIME_DIR; snap-confine resets PATH for confined snaps and sets SNAP_COOKIE; snap-exec applies the snap's environment. Everything else is inherited.

Run env inside the agent's snap and you'll see dozens of variables. Some are yours, some are snapd's, some are the snap's own. Your terminal's variables come along first. Snap run adds the ones that describe the snap: where it is, where its data lives, which app this is, and who's running it. They override anything you'd set. For a confined snap, snap-confine then resets PATH to a fixed list, and adds the cookie that snapctl uses. snap-exec goes last and applies the snap's own environment entries. So a PATH you exported doesn't reach a confined app, and a variable the snap sets wins over everything above it.

05 environment in snap.yaml for app developers

ENVIRONMENT environment:ACME_HOME: $SNAP_COMMONapps:ctl:environment:ACME_LOG: $ACME_HOME/ctl.log 121 · snap-level first, then 2 · app-level or hook-level; keys in the order writtenhooks take the same key; snapd does not check the names or the values ACME_HOME=/var/snap/acme-agent/commonsnapd's variables are already there to use ACME_LOG=/var/snap/acme-agent/common/ctl.logan earlier key can be used by a later one ACME_SERVER: ${ACME_SERVER:-localhost}ACME_SERVER=localhostdefault if unset; an unset variable expands to nothing PATH: $SNAP/bin:$PATHPATH=/snap/acme-agent/42/bin:/usr/local/…a snap can put its own directories on PATH
A snap.yaml with a top-level environment entry ACME_HOME: $SNAP_COMMON and, under app ctl, ACME_LOG: $ACME_HOME/ctl.log, ACME_SERVER with a default and PATH extended with $SNAP/bin; on the right the resulting values, applied snap-level first and app-level second, each in the order written

snap-level entries apply first, then app-level or hook-level ones, each in the order written. Values may use $SNAP and the other snapd variables, the caller's variables, earlier keys, ${VAR:-default} and ${VAR:+value}. snapd does not check the names or values.

The control tool wants to know where to write its log, and that depends on where the snap's data lives. You can't hard-code it, so you compute it. Environment is a map at the top of snap.yaml, under an app, or under a hook. snap-exec applies the top one first, then the app's, each in the order written. Every value is expanded against what's already set: $SNAP_COMMON and friends, the caller's variables, and the keys above. So ACME_LOG builds on ACME_HOME. The colon dash form gives a default; anything unset becomes empty. And since this layer is last, a snap can extend PATH here.

06 assumes is a gate, not a switch for app developers for administrators

ASSUMES assumes: [snapd2.70, command-chain] command-chaina feature this snapd knows?snapd2.70is this snapd at least 2.70?isa-riscv64-rva23checked only on riscv64 the mount-snap taskchecks the list against this snapd all pass: the install goes on$ snap install acme-agent… snap "acme-agent" assumes unsupported features:snapd2.70 (try to refresh snapd)on a device with an older snapd listing a feature requires it; it does not turn it onSNAP_UID is set whether or not you assume snap-uid-envvars
assumes: [snapd2.70, command-chain]. Three kinds of entry: a feature name, snapd with a minimum version, an instruction set for one architecture; the mount-snap task checks them against the running snapd; if all pass the install goes on, otherwise snap install fails with snap acme-agent assumes unsupported features: snapd2.70 (try to refresh snapd); listing a feature does not turn it on

assumes accepts feature names, snapd<version> and isa-<arch>-<isa>. A failed check reads snap "…" assumes unsupported features: … (try to refresh snapd). It only requires; it enables nothing.

You've started using command-chain. Some gateway runs a snapd too old to know what that is. What should happen when your snap arrives? That's what assumes is for. It's a list at the top of snap.yaml with three kinds of entry: a feature name, snapd plus a minimum version, or an instruction set for one architecture. snapd checks the list in the mount-snap task. If an entry is unknown or the version too low, the install stops, and the message names it and suggests refreshing snapd. Administrators see that message. And assumes is a requirement, not a switch: listing a feature turns nothing on.

07 Tab completion runs inside the sandbox for app developers for snapd developers

COMPLETER $ acme-agent.ctl st<Tab>completer: share/acme-ctl.bash your shell's bash-completion…/completions/acme-agent.ctlsymlinksnapd's complete.shmade at install, one per app snap runsnap run --command=complete acme-agent.ctl … inside the sandbox/bin/bash+ snapd's helper+ $SNAP/share/acme-ctl.bash candidates$ acme-agent.ctl statusfiltered by snapd's script first not for services; needs bash-completion on the host; for an alias, snap run maps the words back to the real app
Pressing Tab after acme-agent.ctl st: the user's bash-completion finds a symlink named acme-agent.ctl that points at snapd's complete.sh; it runs snap run --command=complete acme-agent.ctl; inside the sandbox /bin/bash runs snapd's helper and the snap's share/acme-ctl.bash; the candidates come back, snapd's script filters them, and the line becomes acme-agent.ctl status

For an app with completer, snapd creates a symlink to its own complete.sh in the bash-completion directory. Completion runs snap run --command=complete, and snap-exec runs the snap's script with /bin/bash inside the sandbox. complete.sh drops candidates that contain control or shell characters.

The control tool has subcommands, so you ship a bash completion script. But that's code running in the user's own shell, every time they press Tab. snapd doesn't give a snap that kind of trust. At install it links the app's name in the completions directory to a generic script of snapd's. When you press Tab, that script asks snap run to run the app's completion. Inside the sandbox, snap-exec starts bash with a small helper and your completer file. The completer sees only what the app could see, and snapd's script filters its candidates before your shell uses them. Services don't get completion.

08 Where to go from here

ROADS one app entry Servicesadd daemon to an appAliasesshorter names for a commandDesktop filesa desktop file and autostart Run and debugthe programs before snap-execSnap packagingevery location variable Hookshelper programs and variables too Try and packsnap pack checks your commands
Roads from one app entry: services, aliases and desktop files for the other keys; run and debug and snap packaging for what happens around snap-exec; hooks, try and pack, and the overview

Roads: services, aliases, desktop files, run and debug, the location variables in snap packaging, hooks, and try and pack.

That's one app entry, read the way snap-exec reads it. The keys we skipped each have a deck of their own. Add daemon and the app becomes a service, which the services deck covers. Aliases give it shorter names. A desktop app gets a desktop file, and can start when you log in. Run and debug follows the chain of programs that ends in snap-exec, with the shell that lets you look at the environment from inside. The table of every location variable is in snap packaging. Hooks take command-chain and environment like apps do. And try and pack shows snap pack checking that your commands exist.

Read more

acme-agent.ctl is a command-line app added to the running example for this deck.

Keys of an app entry that are not about services

KeyMeaningWhere it is explained
commandpath in the snap plus argumentsthis deck
command-chainprograms run in front of the commandthis deck
environmentvariables for this appthis deck
completera bash completion script in the snapthis deck
plugs, slotsinterfaces of this appplugs and slots
aliasesalias namesaliases
common-id, autostartdesktop integrationdesktop files
refresh-modeonly ignore-running for an app that is not a servicerefresh

An app name uses letters, digits and dashes. Every app that is not a service gets a command on the path: <snap>.<app>, or just <snap> when the app is named like the snap. The service keys are in services.

Rules for command and command-chain

FieldAllowed charactersNotes
commandA-Z a-z 0-9 / . _ # : $ - and the spacesplit at single spaces; no quote characters
command-chain entrythe same without the spacea path only, no arguments

A character outside the set is refused with app description field 'command' contains illegal "…" (legal: '…'). For an app that is not a service, the command file must exist and be executable; snap pack checks it.

The final command line is: every command-chain entry made absolute under the snap's directory, then the first word of command made absolute, then the other words of command with $VAR and ${VAR} expanded (an empty result is dropped), then the user's arguments, unexpanded.

Who sets which variable

Set byVariables
snap runthe location, name and revision variables listed under snap packaging; SNAP_APP_NAME; SNAP_UID, SNAP_EUID; SNAP_LIBRARY_PATH; SNAP_REAL_HOME; HOME and XDG_RUNTIME_DIR for confined snaps
snap run, when the app has themSNAP_APP_COMMON_ID, SNAP_APP_DESKTOP_FILE, SNAP_APP_BUS_NAME
snap run, when the snap has componentsSNAP_COMPONENTS; for a component hook SNAP_COMPONENT, SNAP_COMPONENT_NAME, SNAP_COMPONENT_VERSION, SNAP_COMPONENT_REVISION
snap run, when relocatedXAUTHORITY, KRB5CCNAME
snap-confineSNAP_COOKIE, SNAP_CONTEXT for apps; for confined snaps PATH, SHELL=/bin/bash, TMPDIR=/tmp and TEMPDIR=/tmp
snap-execthe snap's environment, then the app's or hook's; CUPS_SERVER=/var/cups/cups.sock when /var/cups is a separate mount

Variables set by snap run replace values of the same name inherited from the caller. Everything not in this table is inherited.

PATH as set by snap-confine for a confined snap is /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games. SNAP_LIBRARY_PATH defaults to /var/lib/snapd/lib/gl:/var/lib/snapd/lib/gl32. SNAP_UID and SNAP_EUID are always set. The published variable reference differs on these three points; this table follows the code.

environment

  • Levels: top of snap.yaml, per app, per hook.
  • Order: snap-level first, then app-level or hook-level; within a level, the order written.
  • Expansion: $VAR, ${VAR}, ${VAR:-default}, ${VAR:+value}, against the environment built so far. An undefined variable expands to nothing. ${VAR:-default} also applies when VAR is set but empty.
  • snapd's validation does not restrict the keys or values.

assumes

FormMeaning
common-data-dir, snap-env, command-chain, kernel-assets, app-refresh-mode, snap-uid-envvarsa feature name the running snapd must know
snapd<version>, for example snapd2.70the running snapd must be at least that version; plain dotted numbers only
isa-<arch>-<isa>an instruction-set requirement, checked only on that architecture

The check runs in the mount-snap task. Failure: snap "<name>" assumes unsupported features: <a>, <b> (try to refresh snapd); the hint is left out for an instruction-set failure. A snapd whose version is unknown passes version checks. Listing a feature does not enable anything.

for app developers for snapd developers

completer

StepWhat happens
installfor an app that is not a service, a symlink named like the app's command is created in /var/lib/snapd/desktop/bash-completion/completions/, pointing at snapd's complete.sh; with a bash-completion older than 2.2, in /usr/share/bash-completion/completions/ if writable
existing filesa completer there that snapd did not create is kept
Tabcomplete.sh calls snap run --command=complete <app> ...
in the sandboxsnap-exec runs /bin/bash with snapd's helper script and $SNAP/<completer>

The completer must be a readable regular file in the snap. If the host's bash-completion version cannot be determined, no completion is installed.

Further reading

  • Environment variables: every SNAP_* variable with a typical value. Its statements about PATH, SNAP_LIBRARY_PATH, SNAP_UID and SNAP_EUID differ from the code this deck follows.
  • The snap format: the annotated snap.yaml with command, command-chain, completer and assumes.
  • Tab completion: the completer key and how completion is marshalled.
  • Data locations: the directories behind SNAP_DATA, SNAP_COMMON and the user variables.

Roads from here

START HERE

  • snapd — back to the overview

GETTING SNAPS

  • Snap packaging — the table of SNAP and SNAP_DATA and the other location variables

RUNNING SNAPS

  • Services — the service keys of an app entry

HOOKS · code snapd runs inside a snap

ADMINISTRATION · managing a system of snaps

  • Aliases — shorter names for an app's command

DESKTOP · snaps in a user session

DEVELOPING SNAPS · try, pack, run, debug