Run-once scripts / commands

Example: Sending a reboot command to a group of devices

This example shows how qbee can be used to issue commands to a large number of devices. It will explain a simple way to do this and give valuable background information how qbee works.

With qbee "Configure -> File distribution" it is possible to distribute and run script files to one or many groups or devices. qbee is a state based tool. This means that any configuration is autonoumously handled by the agent. If a new configuration is available it is downloaded and the agent starts to converge towards this state. The theory behind this is "promise theory". A huge avantage is that a spare device that was offline for a few years still will get and converge to the last state (for example the current ssh keys) and the agent can also continue to maintain the state when the network is down. So if someone was to try to manually change the firewall settings that are under qbee watch the agent will restore the settings again with its next run. The disadvantage is that it is slightly more complicated to do a "run-once" configuration but it also introduces the advantage that even the run-once script will be able to run months after it was initiated if a device was offline. Removing or disabling it will obviously cancel the action.

Handling run-once actions with

qbee is state based and the concept of run-once needs to be created first. But then it works extremely well and also reaches devices that are not online at the time the command is issued or get moved into a new group later on.

This small demo creates a script that reboots a group of devices. This will explain a lot of the concept.

#!/usr/bin/env bash

shutdown -R now

The "command to run" that is used is bash /usr/local/bin/ > /dev/null 2>&1 &.

Explaining the "command to run"

The script is defined as a bash script and started by calling bash /usr/local/bin/ > /dev/null 2>&1 &. This runs the script in the background and the appendix > /dev/null 2>&1 & pipes bash output to /dev/null. This command will run any time the file is changed.

File distribution will now look like this:


This only works for one run!

This will work. But only one time. The first time the script is not on the target device. Therefore it gets distributed and run. But as long as it does not change on the target or in the file manager this will never run again. So this does not really solve the problem.

A simple trick to enable the same script to run multiple times on demand

This is a very simple trick. Just introduce a comment line to the script that has something that can change. The simplest way is to use the epoch time through templating. Extend any current script with a comment line such as this # unique run-once trigger, here epoch time {{epoch}}. The mustache notation with the curly brackets exposes "epoch" as a key-value pair. Now in file distribution the script can be named as a template changing file name from .sh to .tmpl. This way qbee knows that it is a template that needs expanding. Below the new script is given as well as how the configure tab will look like. Now any time a new epoch time is inserted, saved and the configuration committed it changes the file on the target and reboots. Next time it checks destination script and source script have the same epoch and no operation is performed. If a new epoch is given there is a deviation, the new file is written and the script gets run effectively rebooting again.

#!/usr/bin/env bash

shutdown -R now

# unique run-once trigger, here epoch time {{epoch}}


When will the command (in this case a reboot) happen?

The qbee agent has a run interval. As default this is 5 minutes. The run-once command will be exectued the next time the device asks for its configuration. So if 5000 devices should reboot and the qbee interval is 5 minutes then all online devices will do so within 5 minutes. If the run interval is 6 hours it could take 6 hours until the command is issued on all devices. If a device is offline and comes online again in a year from now it would then reboot once before doing its duty.