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
01 What runs when you type the command
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 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 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
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
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 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
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: 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
| Key | Meaning | Where it is explained |
|---|---|---|
command | path in the snap plus arguments | this deck |
command-chain | programs run in front of the command | this deck |
environment | variables for this app | this deck |
completer | a bash completion script in the snap | this deck |
plugs, slots | interfaces of this app | plugs and slots |
aliases | alias names | aliases |
common-id, autostart | desktop integration | desktop files |
refresh-mode | only ignore-running for an app that is not a service | refresh |
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
| Field | Allowed characters | Notes |
|---|---|---|
command | A-Z a-z 0-9 / . _ # : $ - and the space | split at single spaces; no quote characters |
command-chain entry | the same without the space | a 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 by | Variables |
|---|---|
snap run | the 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 them | SNAP_APP_COMMON_ID, SNAP_APP_DESKTOP_FILE, SNAP_APP_BUS_NAME |
snap run, when the snap has components | SNAP_COMPONENTS; for a component hook SNAP_COMPONENT, SNAP_COMPONENT_NAME, SNAP_COMPONENT_VERSION, SNAP_COMPONENT_REVISION |
snap run, when relocated | XAUTHORITY, KRB5CCNAME |
| snap-confine | SNAP_COOKIE, SNAP_CONTEXT for apps; for confined snaps PATH, SHELL=/bin/bash, TMPDIR=/tmp and TEMPDIR=/tmp |
| snap-exec | the 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 whenVARis set but empty. - snapd's validation does not restrict the keys or values.
assumes
| Form | Meaning |
|---|---|
common-data-dir, snap-env, command-chain, kernel-assets, app-refresh-mode, snap-uid-envvars | a feature name the running snapd must know |
snapd<version>, for example snapd2.70 | the 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
| Step | What happens |
|---|---|
| install | for 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 files | a completer there that snapd did not create is kept |
| Tab | complete.sh calls snap run --command=complete <app> ... |
| in the sandbox | snap-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 aboutPATH,SNAP_LIBRARY_PATH,SNAP_UIDandSNAP_EUIDdiffer from the code this deck follows. - The snap format: the annotated snap.yaml with
command,command-chain,completerandassumes. - Tab completion: the
completerkey and how completion is marshalled. - Data locations: the directories behind
SNAP_DATA,SNAP_COMMONand 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
- Hooks: how they work — hooks which take command-chain and environment too
ADMINISTRATION · managing a system of snaps
- Aliases — shorter names for an app's command
DESKTOP · snaps in a user session
- Desktop files, icons and D-Bus activation — autostart and common-id and the desktop file of an app
DEVELOPING SNAPS · try, pack, run, debug
- Running and debugging an app — the chain of programs that ends in snap-exec
- Trying and packing a snap — snap pack checks that commands and completers exist