Configure snaps

Certain snaps, such as those providing a background service, expose configuration options that can be viewed and changed.

The commands for viewing and changing these configuration options are snap get, snap set and snap unset.

For example, to see the configuration options exposed by an installed snap, enter snap get <snap name>:

$ sudo snap get nextcloud
Key        Value
mode       production
nextcloud  {...}
php        {...}
ports      {...}
private    {...}

The {...} in the output indicates that there are further options beneath the current key name level.

To explore configuration options, append the key name to the get command:

$ sudo snap get nextcloud ports
Key          Value
ports.http   80
ports.https  443

Alternatively, the entire set of configuration options can be dumped as JSON by adding the -d option:

$ sudo snap get -d nextcloud
{
        "http": {
                "compression": false
        },
        "mode": "production",
        "nextcloud": {
                "cron-interval": "5m"
        },
        "php": {
                "memory-limit": "512M"
        },
        "ports": {
                "http": 80,
                "https": 443
        },
        "private": {
                "http": {
                        "compression": false
                },
                "mode": "production",
                "nextcloud": {
                        "cron-interval": "5m"
                },
                "php": {
                        "memory-limit": "512M"
                },
                "ports": {
                        "http": 80,
                        "https": 443
                }
        }
}

Use the set command to change a configuration option:

$ sudo snap set nextcloud ports.http=81
$ sudo snap get nextcloud ports
Key          Value
ports.http   81
ports.https  443

To clear and return a value to its default state, use the unset command (from snapd 2.41+):

$ sudo snap unset nextcloud ports.http
# sudo snap get nextcloud ports
Key          Value
ports.http   80
ports.https  443

Adding an exclamation mark (!) to the end of an option name also clears its value:

$ sudo snap set nextcloud ports.http!

Un-setting with an exclamation mark can be mixed with setting other options at the same time:

$ sudo snap set nextcloud ports.https! ports.http=81

The update process will test the validity of the configuration options. If any errors are detected, the overall change is cancelled and the previous configuration reinstated.

Similarly, if the configuration update process takes longer than a reasonable amount of time, currently 5 minutes, the update is forcefully aborted and the once again the configuration is rolled back.

:information_source: For background details on how snap developers set configuration options, see Adding snap configuration and The configure hook.

1 Like

(perhaps this is not the right place to ask, if so, my apologies and feel free to move my reply, but the example in this post matches exactly what I’m trying to adjust)

I’m trying to limit nextcloud (i.e.apache) to localhost, and according to the docs, I should be able to specify it as follows:

sudo snap set nextcloud ports.http=127.0.0.1:80

But I get: - Run configure hook of "nextcloud" snap (run hook "configure": "127.0.0.1:80" is not a valid HTTP port). Is the nextcloud snap’s check too strict, or am I doing something wrong?

-jcw

Are there any limits in the length of config values?

Maybe 80 is an accepted value?

I seem to remember someone saying that the max length of a value with snap set THE_SNAP key=val is 32K

How to access this configuration from your snapped app?

I.e. I’ve written a small Ruby app - how do I access these configuration variables from my code? Do they appear as environment variables perhaps?

Would be useful to have that information in the documentation.

You can use snapctl as documented a little bit here: https://docs.snapcraft.io/supported-snap-hooks. See also snapctl --help

1 Like

Ok, thanks for that. That answers my question.

Would it be a good idea to put a footnote on the configuration page to that Hooks article? It wasn’t obvious to a total snap newbie (me) that “Supported Snap Hooks” was the article I needed to find the answer I was looking for.

1 Like

Thanks for raising this - and yes, I think you’re right. I’ll add a link and look at improving what we have on snapctl.

1 Like

Certain snaps, such as those providing a background service, expose configuration options that can be examined and altered.

As a snap author, I want to know how I can expose those options (or do things like set a default) - neither this nor https://snapcraft.io/docs/supported-snap-hooks actually answer that for me

Am I right in thinking that “exposition” happens as an implicit consequence of the configure hook calling snapctl get?

The commands for viewing and changing these configuration options are snap get and snap set.

Is there a way to “unset” / remove config?

As far as I can tell (possibly because I’m in devmode?) there are no restrictions on keys, so, thanks to a typo, my snap has config for usre instead of user - can I remove this at all?

A design for this was discussed at Configuration options vs null values vs unsetting and I believe resulted in https://github.com/snapcore/snapd/pull/7102, which will eventually enable you to do snap unset. When that feature has landed in stable, it will be documented here. @pstolowski is the person to ask about this if you need to know before then I think

1 Like

Correct. There was also https://github.com/snapcore/snapd/pull/7096, so it will soon be possible to unset values either with snap unset.. or with snap set usre! user=john (exclamation mark removes the option).

1 Like

Did you find out how to set the configuration settings of snaps “below” your Ruby app?

I am trying to build a snap on top of wpe-webkit-mir-kiosk which has a configuration variable “url” which I want to set. Unfortunately the hooks run in containment and snapctl can only set variables for my own snap, not the underlying snap. Also, wpe-webkit-mir-kiosk only exposes this as a configuration, not as a slot that I can plug into.

Any ideas?

Given that these questions have not yet been answered explicitly, I’ll say what I found out from testing. All this is for snap authors, not users.

How do I define/expose which options my snap has?

You can’t define the options your snap uses. snapctl set and snap set will accept any (valid) option name. If you want your users to know which options they can use, you need to document those options, for example in the snap description. As a result, when users mistype an option, they will not get any feedback that that option is not recognised by your snap.

How do I set default values for an option?

Options do not have the concept of “default values”. Users can unset an option, but that will just remove the option. However, you can “simulate” default values by, in your config hook, checking if an option is unset, and if so, setting it to the default value. This way, when a user runs snap unset, the config option will be removed by the command and set to its “default” value by your config hook.

2 Likes

I would change the second sentence to read:

" The commands for viewing and changing these configuration options are snap get, snap set and snap unset.

Also, after the sample command:

$ sudo snap get nextcloud

I would add using “-d” to further dump the entire document right after that example (and show the output):

$ sudo snap get -d nextcloud

Done, thanks for the suggestions!

I just filed a bug that relates to this page, https://bugs.launchpad.net/snapd/+bug/2017344.

As you can see, if you ask for config info for a non-existent or uninstalled snap, you get the misleading message:

$ snap get nextcloud error: snap “nextcloud” has no configuration $

when this page (correctly) displays the config info if the snap is installed.

1 Like