An Ansible connection plugin using systemd's machinectl
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Ansible Connection Plugin - machinectl

Ansible plugin that uses systemd's machinectl to communicate with virtual machines and containers managed by systemd-machined.


This plugin relies on machinectl's shell subcommand, which was introduced in systemd version 225; see the release notes (permalink).


This plugin can be installed with ansible-galaxy or by directly cloning this repository. You will need to move connection_plugins/ into one of the connection_plugins directories configured in your ansible.cfg.

Connection Variables

None at the moment.

Example Usage

Simply pass the -c|--connection= option to Ansible along with the machine name. Given the machine ansible-nspawn (in a typical setup, this would refer to a chroot located at /var/lib/machines/ansible-nspawn):

$ ansible -c machinectl -m setup ansible-nspawn
archlinux-ansible | SUCCESS => {
    "ansible_facts": {
        # <snip>
        "ansible_virtualization_type": "systemd-nspawn",
        # <snip>
    "changed": false


machinectl requires superuser privileges when running the shell subcommand. There's no straightforward way to piggyback on Ansible's become logic, as this would mean distinguishing between whether the user wants to (1) acquire superuser privileges on the control machine, or (2) acquire superuser privileges within the target machine.

For the moment, this means that Ansible must be run with superuser privileges in order to use this connection type. The plan is to add connection configuration parameters for specifying the local user and their password when running machinectl; at the moment, do:

# Preserve your environment when escalating privileges
$ sudo -E ansible -c machinectl -m setup <target-machine>