HomeDocumentationAPI Reference
Log In
These docs are for v17. Click to read the latest docs for v33.

Onboarding SSH target hosts to PrivX via Ansible

Ansible Deployment

This example uses Ansible for deploying a target host into PrivX, and allows members of specified PrivX roles to access the host.

Prerequisites

  • A host for running Ansible commands. Requires Ansible 1.2 or compatible.
  • A target host satisfying the following requirements:
    • Python 2.7 installed. Modify the scripts to install Python if not available yet.
    • Allow HTTPS to/from PrivX servers. You may need to enable HTTPS in the target-host firewall settings.
    • For automatic host deployment, the target host must have a user account that satisfies the following:
      • Ability to gain root privileges via passwordless sudo.
      • Allows SSH public-key login without passphrase.
        (In the example Ansible files, we assume ubuntu account on the target host to satisfy these requirements.)
  • PrivX must include some roles and users that are to be granted access to the target host. For more information about PrivX roles and users, see the PrivX Administrator Manual: PrivX Users and Permissions.
    (In the example Ansible files, we assume PrivX is configured with a web-developers role, and that this role has some members.)
  • Host-deployment script downloaded from PrivX. For more information about obtaining a host-deployment-script, see the PrivX Administrator Manual: Script-Based Certificate-Authentication Setup.
    • You are familiar with host-deployment-script options.

Deploying PrivX Hosts with Ansible

Unless otherwise specified, perform the following commands on your Ansible machine:

  1. Download the privx_ansible.tgz package attached to the bottom of this article. Extract the package to your Ansible machine:

    $ tar xvf privx_ansible.tgz
    

    This creates the privx_ansible directory in your current working directory.

  2. From your target host, download the private key used for accessing the host. Place it at privx_ansible/privx_test.pem.

  3. From PrivX, download a host-deployment script. Place it at privx_ansible/deploy.py.

  4. Modify privx_ansible/privx_hosts as follows:
    *Under [webservers], specify the target host you will deploy to PrivX.

    • Under [webserver:vars], provide the SSH and Python settings to match your target host, and the location of the downloaded private key.
    • Set host_environment according to your host platform. For example: --aws for AWS hosts, or --standalone for non-cloud hosts.
    • Set --principals according to which roles you want accessing the target host.
  5. Go to the privx_ansible directory and run Ansible as follows:

    $ cd privx_ansible
    $ ansible-playbook -b -i privx_hosts privx_hosts.yml
    

📘

Note

deploy.py requires sudo access (-b flag) for modifying OpenSSH-server configurations.

You should see output similar to the following on successful deployment:

PLAY [Deploy PrivX hosts]
****************************************

TASK [Gathering Facts]
****************************************
ok: [ubuntu1]

TASK [common : Copy deploy.py script to target host]
****************************************
ok: [ubuntu1]

TASK [common : Run deployment script]
****************************************
changed: [ubuntu1]

PLAY RECAP
****************************************
ubuntu1: ok=3    changed=2    unreachable=0    failed=0

📘

Note

By default the deployment script fails with already-deployed hosts. If you want to be able to rerun the script for the same host, you must enable Deployable in the host's settings in PrivX.

2284
For example configuration, see privx_ansible.tgz