dpkg: How to use trigger?

Question

I wrote a little CDN server that rebuilds its registry pool when new pool-content-packages are installed into that registry pool.

Instead of having each pool-content-package call the init.d of the cdn-server, I'd like to use triggers. That way it would restart the server only once at the end of an installation run, after all packages were installed.

What have I to do to use triggers in my packages with debhelper support?

Answer 1

What you are looking for is dpkg-triggers.

One solution with use of debhelper to build the debian packages is this:

Step 1)

Create file debian/<serverPackageName>.triggers (replace <serverPackageName> with name of your server package).

Step 1a)

Define a trigger that watch the directory of your pool. The content of file would be:

interest /path/to/my/pool

Step 1b)

But you can also define a named trigger, which have to be fired explicit (see step 3).

content of file:

interest cdn-pool-changed

The name of the trigger cdn-pool-changed is free. You can take what ever you want.

Step 2)

Add handler for trigger to file debian/<serverPackageName>.postinst (replace <serverPackageName> with name of your server package).

Example:

#!/bin/sh

set -e

case "$1" in
    configure)
    ;;

    triggered)
        #here is the handler 
        /etc/init.d/<serverPackageName> restart
    ;;

    abort-upgrade|abort-remove|abort-deconfigure)
    ;;

    *)
        echo "postinst called with unknown argument \`$1'" >&2
        exit 1
    ;;
esac

#DEBHELPER#

exit 0

Replace <serverPackageName> with name of your server package.

Step 3) (only for named triggers, step 1b) )

Add in every content package the file debian/<contentPackageName>.triggers (replace <contentPackageName> with names of your content packages).

content of file:

activate cdn-pool-changed

Use same name for trigger you defined in step 1.

More detailed Information

The best description for dpkg-triggers I could found is "How to use dpkg triggers". The corresponding git repository with examples you can get here:

git clone git://anonscm.debian.org/users/seanius/dpkg-triggers-example.git

Answer 2

I had a need and read and re-read the docs many times. I think that the process is not clearly explain or rather what goes where is not clearly explained. Here I hope to clarify the use of Debian package triggers.

Service with Configuration Directory

A service reading its settings in a specific directory can mark that directory as being of interest.

Say I create a new service which reads settings from /usr/share/my-service/config/...

That service gets two additions:

1. In its debian directory I add my-service.triggers

   And here are the contents:

   # my-service.triggers
   interest /usr/share/my-service/config
   

   This means if any other package installs or removes a file from that directory, the trigger enters its "needs to be run" state.

2. In its debian directory I also add my-service.postinst

   And I have a script as follow to check whether the trigger happened and run a process as required:

   # my-service.postinst
   if [ "$1" = "triggered" ]
   then
     if [ "$2" = "/usr/share/my-service/config" ]
     then
       # this may or may not be what you need to do, but this is often
       # how you handle a change in your service config files
       #
       systemctl restart my-service
     fi
   
     exit 0
   fi
   

That's it.

Now packages adding extensions to your service can add their own configuration file(s) under /usr/share/my-service/config (or a directory under /etc/my-service/my-service.d/... or /var/lib/my-service/..., although that last one should be reserved for dynamic files, not files installed from a package) and dpkg automatically calls your postinst script with:

postinst triggered /usr/share/my-service/config
# where /usr/share/my-service/config is your <interest-path>

This call happens only once and after all the packages were installed, hence the advantage of having a trigger in the first place. This way each package does not need to know that it has to restart my-service and it does not happen more than once, which could cause all sorts of side effects (i.e. the service tries to listen on a TCP port and get error: address already in use).

IMPORTANT: keep in mind that the postinst should include a line with #DEBHELPER#.

So you do not have to do anything special in other packages. Only make sure to install the configuration files in the correct directory and dpkg picks up from there (i.e. in my example under /usr/share/my-service/config).

I have an extension to BIND9 called ipmgr which makes use of .ini files saved in a specific folder. It uses the files to generate DNS zones (way less errors that way! and it includes support for getting letsencrypt certificates and settings for dmarc/dkim). This package uses this case: a simple directory where configuration files get installed. Other packages do not need to do anything other than install files in the right place (/usr/share/ipmgr/zones, for this package).

Service without a Configuration Folder

In some (rare?) cases, you may need to trigger something in a service which is not driven by the installation of a new configuration file.

In this case, you can use an arbitrary name (it should include your package name to make sure it is unique since this name is global to the entire Debian/Ubuntu system).

To make this one work, you need three files, one of which is a trigger in the other packages.

1. State the Interest

   As above, we have an interest. In this case, the interest is stated as a name on its own. The dpkg system distinguish between a name and a path because a name cannot include a slash (/) character. Names are limited to ASCII except control characters and spaces. I would suggest you stick to a-z, 0-9 and dashes (-).

   # my-service.triggers
   interest my-service-settings
   

   This is useful if you cannot simply track a folder. For example, the settings could come from a network connection that a package offers once installed.

2. Listen for the Triggers

   Again, as above, you need a postinst script in your Service Package. This captures the trigger and allows you to run a command. The script is the same, only you test for the name instead of the folder (note that you can have any number of triggers, so you could also have both: a folder as above and a special name as here).

   # my-service.postinst
   if [ "$1" = "triggered" ]
   then
     if [ "$2" = "my-service-settings" ]
     then
       # this may or may not what you need to do, but this is often
       # how you handle a change in your service config files
       #
       systemctl restart my-service
     fi
   
     exit 0
   fi
   

3. The Trigger

   As mentioned above, we need a third file. An arbitrary name is not going to be triggered automatically by dpkg. It wouldn't know whether your other package needs to trigger something just like that (although it is fairly automated as it is already).

   So in other packages, you create a trigger file which looks like this:

   # other-package.triggers
   activate my-service-settings
   

   Now we recognize the name, it is the same as the interest stated above.

   In other words, if the trigger needs to run for something other than just the installation of files in a given location, use a special name and add this triggers file with the activate keyword.

Other Features

I have not tested the other features of the dpkg-trigger(1) tool. There are other keywords support in the triggers files:

interest
interest-await
interest-noawait

activate
activate-await
activate-noawait

The deb-triggers manual page has additional information about those. I am not too sure what the await/noawait implies other than the trigger may happen at any time when nowait is used.

Automatic Trigger Added

The build system on Ubuntu (probably Debian too) automatically adds a triggers file with the following when your package includes a library:

$ cat triggers 
# Triggers added by dh_makeshlibs/11.1.6ubuntu2
activate-noawait ldconfig

I suggest you exercise caution if your package includes libraries. If you have your own triggers file, I do not know whether this addition will still happen automatically.

This also shows us a special case where it wants to use the noawait. If I understand correctly, it has to run the ldconfig trigger ASAP so your commands will work as expected after the unpack. Otherwise ldd will not know anything about your newly installed library.