Running notification plugins standalone

About

Using the mqttwarn command, you can invoke an individual notification plugin directly, without the dispatching and transformation machinery, and without needing to start it as a service.

This can be used for custom notification programs, and for debugging them, without needing to exercise a full end-to-end MQTT publishing workflow.

Details

To launch a plugin standalone, the commands in the next sections will give you an idea how to pass relevant information on the command line. Please note that all configuration options are obtained as strings in JSON format.

Many plugins will work without a configuration, and only need an --options parameter. Others will need an additional baseline configuration, obtained per --config parameter. Alternatively, a path to the configuration file can be specified using the --config-file parameter.

Synopsis

Launch log service plugin with a few target address descriptor options.

mqttwarn --plugin=log --options='{"message": "Hello world", "addrs": ["crit"]}'

Tip

For producing JSON with command line / script programs, you can use the excellent jo program, so you will not have to fiddle with curly braces and quotes too much.

mqttwarn --plugin=log --options="$(jo message="Hello world" addrs=$(jo -a crit))"

Examples

The best way to learn about this feature, is on behalf of a few more example invocations.

Invoke plugins that do not need a configuration, like log, file, or pushover.

# Launch "file" service plugin
mqttwarn --plugin=file --options='{"message": "Hello world\n", "addrs": ["/tmp/mqttwarn.err"]}'

# Launch "pushover" service plugin
mqttwarn --plugin=pushover --options='{"title": "About", "message": "Hello world", "addrs": ["userkey", "token"], "priority": 6}'

Invoke plugins that require a configuration, like ssh.

# Launch "ssh" service plugin
mqttwarn --plugin=ssh --config='{"host": "ssh.example.org", "port": 22, "user": "foo", "password": "bar"}' --options='{"addrs": ["command with substitution %s"], "payload": "{\"args\": \"192.168.0.1\"}"}'

Invoke ntfy plugin.

# Launch "ntfy" service plugin
mqttwarn --plugin=ntfy --options='{"addrs": {"url": "http://localhost:5555/testdrive"}, "title": "Example notification", "message": "Hello world"}' --data='{"tags": "foo,bar,äöü", "priority": "high"}'

# Launch "ntfy" service plugin, and add remote attachment
mqttwarn --plugin=ntfy --options='{"addrs": {"url": "http://localhost:5555/testdrive"}, "title": "Example notification", "message": "Hello world"}' --data='{"attach": "https://unsplash.com/photos/spdQ1dVuIHw/download?w=320", "filename": "goat.jpg"}'

# Launch "ntfy" service plugin, and add attachment from local filesystem
mqttwarn --plugin=ntfy --options='{"addrs": {"url": "http://localhost:5555/testdrive", "file": "goat.jpg"}, "title": "Example notification", "message": "Hello world"}'

Invoke external plugin.

# Launch "cloudflare_zone" service plugin from "mqttwarn-contrib"
pip install mqttwarn-contrib
mqttwarn --plugin=mqttwarn_contrib.services.cloudflare_zone --config='{"auth-email": "foo", "auth-key": "bar"}' --options='{"addrs": ["0815", "www.example.org", ""], "message": "192.168.0.1"}'