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

To use this feature you need either of:

• MAMAS 0.8.x (full featured including machine ID)
• 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 MAMAS 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 link can be found above
  • The agent archives do contain deployment-specific data so you need to copy it from your MAMAS server - look into your deployment directory (e.g. /opt/mamas or /opt/mamas<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 it on Debian GNU/Linux version 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 python3 push_agent.py -h

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 root user on the device), authentication token (path to a ssh keyfile, path to file containing the password or the passord 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 MAMAS 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 MAMAS 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 MAMAS server machine, the agent_dir should be /opt/mamas/agents or /opt/mamas<your_domain>/agents respectively. NOTE the script on your server resides here: /opt/mamas<your_domain>/push_agent.py