snapctl tool is bundled with snapd to provide both specific environmental feedback and limited control from within the context of a snap’s execution environment to snapd.
snapctl is typically run from a script within a snap, rather than on the host system. These scripts are used by snap developers to implement hooks, or from within snapcraft.yaml, to caugment a snap’s execution environment.
See Creating a snap for more details on the snap development process.
From within a snap, snapctl can do the following:
When a snap has defined and exposed configuration options, such as those providing a background service, they can be queried and altered with the
snapctl set and
snaptctl unset commands, much like then can with the analogous _snap commands outside the snap.
The snapctl command uses the same get, set and unset syntax as the snap command:
snapctl get <configuration option>
See Configuration in snap for more details.
The state of a specific snap interface can be probed with the
snapctl is-connected sub-command by supplying either a slot or plug name as an argument:
snapctl is-connected <plug|slot>
The plug or slot is always the name of the plug/slot from the calling snap.
If the given plug or slot is connected, the command returns the standard exit code for success, which is
0 on POSIX systems. A non-zero exit code is returned in all other cases.
For example, the following indicates the camera interface is not connected:
$ snapctl is-connected camera | echo $? 1
This behaviour can be easily used within a hook, for example:
if snapctl is-connected camera; then # exit status=0. logic when connected echo "connected" else # logic when not connected; note if this is run from hooks. # printing to stdout/stderr is not visible to the user # (unless the hook fails entirely with exit status > 0) echo "not connected" fi
Snaps can only query their own plugs and slots because the snap name is implicit and implied by the snapctl execution context.
See Snapcraft interfaces for more details on manipulating interfaces from a snap.
As with configuration options (see above), snapctl sub-commands for managing services are the same as those used by the snap command. See Services and daemons for further details.
To query the startup and running state of a service, for example, use the
snapctl service <service-name>:
$ snapctl services nextcloud.mysql Service Startup Current Notes nextcloud.mysql enabled active -
restart snapctl commands can be used to start, stop and restart services:
$ snapctl stop nextcloud.mysql $ snapctl services nextcloud.mysql Service Startup Current Notes nextcloud.mysql enabled inactive -
Services can be enabled and disabled by adding the
--enable argument to snapctl start and
--disable to snapctl stop respectively:
$ snapctl start nextcloud.myql --enable $ snapctl stop nextcloud.mysql --disable
Snaps can only query their own services.
Health reporting is under development and its capabilities and syntax may change.
Snap developers can use
snapctl set-health to provide feedback on the operational state, or health, of a snap.
It uses the following syntax:
snapctl set-health [--code=<error code>] <status> [<message>]
status can be one of the following:
okay: which takes no message and no code
waiting: some resource the snap needs isn’t ready yet, and there’s nothing for the user to do but wait. A message (+code) must explain what it’s waiting for
blocked: the user needs to do something for the snap to do something. A message (+code) must say what
error: something went wrong; a message (+code) must explain what has broken
Outside the snap, health status in included as a note in the output to
snap list, and as a category in
snap info for a specific snap:
$ snap info nextcloud name: nextcloud summary: Nextcloud Server - A safe home for all your data health: status: blocked message: Backing up database. checked: today at 10:44 GMT
For more comprehensive information on using
snapctl set-health, see Health checks.