How to add many devices to Dwarfguard in an automated and quick way

To use this feature you need either of:

• Dwarfguard 0.8.x and newer (full featured including machine ID)
• Dwarfguard/MAMAS 0.7.4
• any older MAMAS version and download the push_agent.py script manually

If the devices you want to install the agents on are reachable via ssh from the Dwarfguard server, you have everything you need.

In the other case (copying the tool to another machine), you need:

• Make a copy of the script and agent archives to another machine (e.g. a notebook) that could be connected to the network that provides ssh connection from the notebook to each of the devices you want to install agent on.
  • The script can be downloaded from the GUI under Download agents -> View All Downloads -> AAD - automated agent deployment tool. Prior to running the script you need to add execution permissions to the downloaded file (or execute it prepending the python3 text in front of the commands shown below)
  • The agent archives do contain deployment-specific data so you need to copy it from your Dwarfguard server - either download one by one via GUI (under Download agents -> View All Downloads) or, if you prefer and have command-line access to your Dwarfguard server available - look into your deployment directory (e.g. /opt/dwarfg_ or /opt/dwarfg_<your_domain>) and copy the whole agent subdirectory.
• The script has been tested on Linux box. While there is a chance it will work on Windows, we do not support that so your best bet with Windows OS is to install a VM containing Linux.
  • We have tested the AAD on Debian GNU/Linux version 12 (and 11) though virtually any Linux sporting Python3 and ssh+sshpass SW packages should work.
  • Please note that the sshpass is probably not installed on your Linux box by default, so you may need to use your package management software to install it first.

The script can run a number of agent push installations in parallel, bringing down the required time to install on all devices considerably. Use --jobs <number> parameter for that.

The script takes a file listing one device address and parameters per line. As for the file syntax, run ./push_agent.py -h or python3 push_agent.py -h if you have not assigned execution permission to the downloaded script.

An example file could be:

172.17.3.122:keyfile:/home/user/.ssh/id_rsa:remove
advrout3:passfile:myfile:remove
advrout4:password:mysupersecretpassword:noremove
advrout2:password:mysupersecretpassword:remove

as you can see, next to the device address (IP or DNS resolvable name) you specify way of authentication (to access root user on the device), authentication token (path to a ssh keyfile, path to file containing the password or the password literal directly) and finally if you want to remove any existing agents or not. See script help for more.

The script goes though the list of devices and processes them, producing up to two new files:

• <original_file_name>.ok ... contains all the devices that successfully registered to the Dwarfguard server
• <original_file_name>.err ... contains all the failed devices

Each of these files could be extremely useful:

• The failed devices file contains not only the errors, but also the skipped devices. Devices could be skipped for example if you have pressed Ctrl-C during script execution time. If you have a really lot devices, you may want to process them in a several runs. You can either split the file by yourself or simply run the script on the whole file, interrupting it when you want it to stop. Both devices ending up in errors and the unprocessed devices will be stored in the .err file that you can simply reuse next time.
• The successful installation list contains the original lines enriched by the assigned Device ID. Example of such line could be:

advrout2:password:mysupersecretpassword:remove:BOBO

• The file can be used as it is (including the BOBO) for re-pushing agent to that device, keeping the assigned Device ID and thus keeping all the history and setting for this device in the Dwarfguard server.
• This re-push could come handy in case you e.g. underestimated lifetime of the server certificate and you need to change it. In the highest (default) security settings, agents will not accept the certificate changed on one side (just on server). In this case, the re-push can save your day.

While the execution of the script is quite straightforward, you are strongly encouraged to test out the script to get familiar with the parameters and the way it works prior to running it for real against thousands of devices for your very first time.

In general, all you need is something like this:

./push_agent.py <path_to_devicelist> --agent_dir <path_to_copied_agents_dir> --jobs <number> 

If you run it directly on Dwarfguard server machine, the agent_dir should be /opt/dwarfg_/agents or /opt/dwarfg_<your_domain>/agents respectively. NOTE the script on your server resides here: /opt/dwarfg_<your_domain>/push_agent.py