Package: ants-client
ANTS is a framework to manage and apply macOS and Linux host configurations using Ansible Pull.The ANTS Framework is developed by the Client Services Team of theUniversity of BaselIT Servicesand released under theGNU General Public License Version 3.Ansibleis a trademark ofRed Hat, Inc.IntroductionThe ANTS Framework consists of the following components:A wrapper for Ansible-PullAn Ansible Dynamic Inventory Script (MS Active Directory Connector)A modular collection of roles ready to be usedStrong logging integrationRequirementsThis project assumes that you are familiar withAnsible,Gitand the shell.Getting startedInstalling ants using pipMake suregitis installed on your machineInstall the latest ants client using pip:pip install ants_clientPip will install the ANTS client with a default configuration and put the executable in your path.Installing ants using macOS .pkg installerDownload the latest .pkg installer from thereleases page.Execute the installer. This will take care of all dependencies.A launch daemon will be installed, runningantsevery 15 minutes. It will trigger after the next restart.Run antsOpen your terminalStart an ANTS run by typingants.Wait for ANTS to finish, then open another shell. You will see a new message of the day.What happened?Running ANTS with the default configuration will use ansible-pull to clonethe ANTS playbookvia https from a github repository and execute an ansible run.By default, this will generate/etc/motdto add a message of the day to your macOS or Linux host.
Logs of all the runs are stored at/var/log/ants.Also by default, ants will add github to yourknown_hostsfile. This is important for later, when you want to enable git clone
using ssh.Where to go from here?Look at the optionsRunants-hto see all command line options.Write your own configurationRunants--show-configto see the active configuration.Runants--initializeto write your own configuration.Your local configuration file will be saved at/etc/ants/ants.cfg.
You can also edit it using your favorite text editor.Do not modify the default configuration file as it might be overwritten when updating ANTS.On Mac OS, you can also configure ANTS with a preference list (plist) or configuration profile.
Please note that configurations set in this manner will override any other configuration, includingants.cfg.
Goherefor an example configuration profile.Run other rolesFork or duplicateour example playbookand change the client configuration to point to your repository.
Updatemain.ymlto assign different roles to your hosts.You can use the default Ansible syntax. You can also use wildcards. Have a look at theAnsible documentationAdd ssh authentication to your repositoryAnsible-pull can clone a git repository using ssh. You can enable this by creating your own private playbook,
adding ssh authentication and a read only ssh key to the repository.
Configure ANTS to use that key.By default, ANTS will look for a private key at/etc/ants/id_antsYou can generate a key withssh-keygen-trsa-b4096-N''-C"ants client"-f/etc/ants/id_antsBy default, ANTS is configured to run with strict host key checking disabled
and will add the host key for your repo to yourknown_hostsfile.You should change this in production.To do so, addssh_stricthostkeychecking = Trueto your ants.cfgAdd a dynamic inventory sourceAnsible supports dynamic inventory scripts. (A json representation of hosts to group mappings.)You can use scripts to tell ansible-pull which tasks to run on which host.
You need an inventory source and a script that can read and return it in thecorrect format.By default, ANTS will run a dummy scriptinventory_defaultthat will just return your hostname belonging to a group
namedants-common. You can editmain.ymlstraight away and assign roles using host names. But
ANTS shows it’s real power when ansible-pull is combined with a dynamic inventory using group mappings.For this we provide theinventory_adscript  which will connect to your Active Directory and return all groups your
host is a member of. Just add your configuration to/etc/ants/ants.cfg. Note that read only rights for the
Active Directory user are sufficient.Your host DOSN’T have to be bound to Active Directory in order for this to work.You can use a placeholder object.By using a dynamic inventory source, you can assign roles to a host using AD and let ANTS handle the configuration.Group Layout in Active DirectoryThe groups in Active Directory must have the same names as the mappings and the variables you want to assign
using Ansible. We recommend to keep the groups in a dedicated Organizational Unit to prevent naming collisions.Nested groups with access restrictions are an easy way to offer rights delegation to other units in your organization.What else do I needNothing. You just set up a configuration management that communicates savely over ssh using your AD and Github.No additional infrastructure and no AD binding required.Add your own inventory fileYou can add your own inventory file. This can be adynamic inventory sourceor astatic file. By default, ANTS will look for the inventory file in its python package. This is useful because it enables you to use inventory scripts likeinventory_adwithout having to specify the full path. However, if you would
like to place your inventory file somewhere else you’re free to do so. All you have to do is use an absolute path inants.cfg.The following entry inants.cfgwill look for your inventory file in the ANTS python package. This is useful for everything that comes with the ANTS installation:[main]
inventory_script = inventory_adThis entry on the other hand will look for your inventory file in/etc/ants:[main]
inventory_script = /etc/ants/myinventoryCallback plugins and reportingANTS can be configured to execute ansible callback plugins. We will cover the most common use case here: log ANTS information to logstash.ANTS ships with a modified version of thedefault ansible logstash plugin. If you want to use plugins that are installed at a custom location you can specify your path in theants.cfgconfig file underansible_callback_plugins.In order for ANTS to execute the callback plugin, just add the following entries to the config file:ansible_callback_whitelist = ants_logstashand add a new section called[callback_plugins].  This section should contain theLOGSTASH_SERVERand theLOGSTASH_PORT.  ANTS will set the environment variables according to these values. Environment variables will only be added if theansible_callback_whitelistis not empty.You can add other callback plugins toansible_callback_whitelistif you desire. The same is true for[callback_plugins]. Just add environment variables to that sub section.Please note that the casing of the environment variables is essential for the callback plugins to work. The casing can be found usingansible-doc-tcallback logstash $name_of_plugin.Testing and DevelopmentYou made changes to the ANTS code or you want to test a feature that hasn’t been released yet? This is
what you should do:If what you’re looking for is already available in pypi as a pre-release, you can simply install it
by telling pip to include pre-releases in its search:pip install ants_client--preIf you made local changes to your code and want to test them, you can set up avirtual environment,activate itand install your code locally usingpip install-e<path_to_ants>.Make sure all inventory files are found. You can run a local dev version of ants ANTS using the following commands:git clone https://github.com/ANTS-Framework/ants.git ants_dev
cd ants_dev
python3 -m venv venv
source venv/bin/activate
python -m pip install -e .
sudo ants --ansible_pull_exe $(which ansible-pull) -i $(which inventory_ad) -vvvCommunicationPlease use theGitHub issue trackerto file issues.Please use aGitHub Pull-Requestto suggest changes.Comparison of plain Ansible and Ansible Tower to ANTSWhat does ANTS do, that Ansible can not?ANTS gives you a set of ready to be used roles for typical macOS and Linux host configurations.ANTS let’s you utilize Active Directory to map computers to roles. With all it’s delegation and nesting features.ANTS utilizes Ansible Pull and therefore does not require an active network connection to a central server. Roles will be locally applied even if the host is offline.What does Ansible or Ansible Tower do that ANTS does not?Tower has a nice DashboardTower has a real time job output and push-button job runsTower can to job schedulingTower supports run-time job promotingTower supports workflowsAnsbile can use encrypted secrets using VaultAnsible and Tower do offer Enterprise Support