Supported snap hooks

There are situations where snapd needs to notify a snap that something has happened, or needs to allow to snap to have an opinion about a particular operation in progress. For example, when a snap is upgraded it may need to run some sort of migration on the previous version’s data in order to make it consumable by the new version. Or when an interface is connected or disconnected, the snap might need to obtain attributes specific to that connection. These types of situations are handled by hooks.

A hook is defined as an executable contained within the meta/hooks/ directory inside the snap (snap/hooks/, for snapcraft), where the filename of the executable is based on the hook name. The existence of the properly named executable is enough for snapd to recognize that a hook exists and should be called as appropriate for the hook kind.

Since hooks also execute in the same confined environment as the snap applications themselves, in some cases interfaces may be necessary to access required system resources. For that, the snap’s snap.yaml inside file must carry some additional syntax describing what are the requirements, with plugs and slots as usual. When using snapcraft, these should go inside snapcraft.yaml and snapcraft itself will take care of creating a snap.yaml that holds that metadata.

For example, the following excerpt registers an install hook making use of a network plug.

apps:
    ...

hooks:
    install:
        plugs: [network]

Hooks are called with no parameters. When they need to request or modify information in snapd they can do so via the snapctl tool, which is always available in their environment. See snapctl --help and snapctl <command> --help for details on how to use the tool.

The configure hook

The configure hook is called upon initial install, on refresh, and whenever the user requests a configuration
change via the snap set command. The hook should use snapctl get to retrieve configuration values from snapd. If the hook exits with a non-zero status code, the configuration will not be applied.

For example, given the following command:

$ snap set mysnap username=foo password=bar

The configure hook located within the mysnap snap at meta/hooks/configure would be called to apply the configuration changes, if necessary.

The hook might look similar to:

#!/bin/sh

username="$(snapctl get username)"
password="$(snapctl get password)"

if [ -z "$username" -o -z "$password" ]; then
    echo "Username and password are required."
    exit 1
fi

mkdir -m 0600 $SNAP_DATA/options
echo "username: $username" > $SNAP_DATA/options/credentials
echo "password: $password" >> $SNAP_DATA/options/credentials

The install hook

The install hook is called upon initial install only, i.e. it’s not called on subsequent refreshes. The hook is executed before starting snap services (if it has any) and before the configure hook. The install hook is the place for one-time actions, such as an early initialization of a resource when installed for the first time.

The pre-refresh hook

The pre-refresh hook is called whenever the snap gets refreshed. It is executed for the already installed revision of the snap with its services still running (if the snap has any services) and before switching to the newly installed revision. This hook is a good place for any maintenance or cleanup actions that prepare the snap for switching to the new revision.

The post-refresh hook

The post-refresh hook is similiar to pre-refresh in that it is called whenever the snap gets refreshed. Contrary to `pre-refresh’, this hook is executed for the newly installed snap, before starting new services (if applicable). This hook is a good place for any extra actions that need to be performed for the new revision of the snap.

The remove hook

The remove hook is called when the last revision of the snap gets removed from the system. It’s executed after stopping the services of the snap (if the snap has any services), therefore it’s useful for any custom cleanup logic.

The prepare-device hook

This hook is only supported in gadget snaps. See more details in the gadget snap documentation.

Last updated a month ago. Help improve this document in the forum.