One-off file distribution

Learn how to distribute a file that can be individualized on the target device without being overwritten

This short example shows how to play out a file to one device or a group of devices that can change on the target device. A typical example is a base configuration but the device (or a user) will later rewrite this configuration.

qbee is a state based system. For file distribution the files in the file manager are the reference files. Each file has a checksum and the qbee agent will check the following and do according actions:

  • Is the file on the device? -> if not distribute the file to the target device

  • Has the file on the target the same checksum as in file manager -> if not re-distribute the file to the target. Overwrite the file with the wrong checksum

This has certain implications. If a file on the target device gets changed by a process or by a user the checksum is changed. This will trigger a new file distribution the next time the agent runs, effectively overwriting the file on the target. In some use case it is useful to distribute a common file to many devices. This could be a base configuration. Based on different scenarios this file could individually change on the target devices later on. If the goal is not to have all devices have the same file but allow individual editing of the file this can be solved in the following way:

  • A file text.txt is uploaded to the file manager

  • The file text.txt is distributed to the targets with an intermediate name text-base.txt

  • A script or a "command-to-run" checks if the file text.txt exists on the device

  • If the file text.txt exists nothing happens. If the file does not exist the intermediate file text-base.txt will be copied with the new name text.txt

This causes the file to be created if it was not on the device. The next time the agent runs it will only compare the checksum of text-base.txt with text.txt from file manager. This will still be identical even if the file text.txt on the target device has changed. Thus nothing happens and the text.txt can be changed individually. If that file is deleted and the text-base.txt is deleted the old original file will be distributed again. If the original text.txt in the file manager changes it will distribute a new text-base.txt and run "command to run again".

In order to nail this use case we need to test if the file is there. This can be done with the following command [ ! -f /home/pi/text.txt ] or the test command can be used. In this particular case we test if the file is NOT there. If it is not we copy the file with option cp -p to maintain file properties. Alternatively a chmod can be run afterwards. Here is the whole command:

[ ! -f /home/pi/text.txt ] && cp -p /home/pi/text-base.txt /home/pi/text.txt 

Summarizing the one time file distribution

This needs to be thought through once and then it should be quite easy to understand. If you want to "break" the relationship between a file on the remote device and the file manager you need to somehow copy it into a new file. Then this can be independently be edited without any re-distribution. BUT: any time the original file in file manager changes (or someone deletes the linked file on the remote device) the "command to run" runs again. This causes a new copy thus overwriting the file that you want to be "unlinked". We solve this by checking if it already exists and preventing the copy operation in case it does.