Adding snap configuration

Snaps can expose configuration options which change their behaviour. As an example, the Nextcloud snap allows users to configure the hostname, ports, php memory limit and more.

This page describes how a snap developer can add configuration options to their snap.

Using and changing configuration

Internally, snaps view and change their configuration using the snapctl and its get, set and unset arguments (see Using the snapctl tool for more details).

When creating a snap, you don’t need to define which configuration options it supports because any (valid) option name is accepted. However, configuration values should be documented in the snap description so that users know which values are supported.

:information_source: Users view and change configuration with the analogous snap get|set|unset .. commands.

The snapctl get|set|unset commands work anywhere within the snap context: during execution of your applications and services, and in all the hooks of your snap.

However, when you change configuration during a hook, if the hook exits with a non-zero status code the configuration will not be applied. This is because the hook context is transactional - either every change is applied, or none are.

When a user changes the configuration of a snap, the configure hook is executed. This hook will typically validate the configuration and, for example, write to the necessary configuration files. However, when the snap changes its own configuration, this hook is not called.

Snaps that use configuration options need to have a configure hook defined. Otherwise, users will not be able to change the configuration.

Default values

Snapd itself does not have the concept of a “default value” for a configuration option. However, snap developers can implement this using the configure hook.

When a user resets a configuration option with snap unset, the configure hook is run. The snap developer can therefore use this hook to check when these values are unset and, if so, use snapctl set to restore that option to its default value.

Setting these values explicitly is preferred over using implicit defaults in the snap, because this way, users can easily discover which configuration options your snap supports.

Nested values

You can group configuration options using a dotted path:

snapctl set my-snap server.protocol=tcp server.port=4242

Each configuration option can be retrieved by using the same dotted path, or you can retrieve the entire collection as a json document by specifying their common key:

$ snapctl get server
{
    "protocol": "tcp",
    "port": "4242"
}

More information

For a complete example, take a look at the configure hook of the Nextcloud snap.

Last updated 4 months ago. Help improve this document in the forum.