Using the snapctl tool

The 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 augment a snap’s execution environment.

For details on using snapctl to add user options to a snap, see Adding snap configuration and see Creating a snap for an overview of the snap development process.

From within a snap, snapctl can do the following:

Configuration options

A snap’s configuration options can be queried and altered with the snapctl get, snapctl set and snaptctl unset commands. These work very similar to the analogous snap get/set/.. commands outside the snap. The main difference is that using these commands from within a snap will not trigger the configure hook.

The snapctl command uses the same get, set and unset syntax as the snap command:

snapctl get <configuration option>

For example, the following sets a value of 80 for http:

snapctl set ports.http=80

To unset a value, pass its name with snapctl unset, and more than one value can be passed at a time:

snapctl unset ports.http ports.https

For convenience, an option can also be unset by adding an exclamation mark (!) to the end of a value. For example, the following unsets https:

snapctl set ports.http=80 ports.https!

By using a dot in the key of an option, you create a nested configuration. You can retrieve multiple nested options by specifying their common key:

$ snapctl get ports
"http": "80",
"https": "443"

To see this in action, look at the NextCloud snap. It uses snapctl within its various hooks to set configuration options such as snapctl get private.mode and snapctl set private.mode="$1".

For more information, see Adding snap configuration and The configure hook.

Interface connections

(from snapd 2.43+)

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 $?

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"
  # 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"

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   -

The start, stop and 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 state

:information_source: 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
  status:  blocked
  message: Backing up database.
  checked: today at 10:44 GMT

For more comprehensive information on using snapctl set-health, see Health checks.

System mode

The snapctl system-mode command returns YAML-formatted details about specific system states:

$ snapctl system-mode
system-mode: install
seed-loaded: true
factory: true

The following keys and values can potentially be returned:

  • system-mode: install, recover, run
    The current (operational) system mode. install denotes the system is installing, recover means the system is in recovery mode and run indicates the system has booted normally. Mostly relevant on UC20 but can be used on classic systems, and with UC16/UC18, where run is the only reported system mode.

  • seed-loaded: true
    Set when the installation of seeded snaps for the model has finished.

  • factory: true
    Only possible on a UC20 system in install mode (system-mode: install) with the factory image hint set. This value can be used to govern whether factory-only resources may be available. See Factory image hint for more details.

Reboot control (from the UC20 install-device hook)

The snapctl reboot command can be used to control reboot behaviour from the gadget install-device hook during UC20 install mode.

See the UC20 installation process documentation for further details.

Last updated 4 months ago.