HomeDocumentationAPI Reference
Log In

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 example playbook from GitHub to a directory on your Ansible machine.

    For the rest of the steps, we assume you downloaded the example playbook to 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