This chapter describes a simple test setup for testing access from roles to hosts:

  1. Create local users and roles (the section called “Creating Local Users and Roles”).

  2. Add hosts, and specify who has access to them (the section called “Adding Target Hosts”).

  3. Access the host via the PrivX GUI (the section called “Connecting to Target Hosts”).

This chapter also provides examples for setting up some additional features:

  • Enabling certificate-based SSH authentication (the section called “Enabling Certificate Authentication for OpenSSH Connections”).

  • Providing access for Active-Directory users (the section called “Importing Users from Directories”).

  • Adding hosts from Amazon Web Services (the section called “Importing Hosts from Directories”).

The sections describing the simple test setup should be performed in order. The sections describing additional features may be attempted after the simple test setup.

Creating Local Users and Roles

PrivX users can log into PrivX to use features (such as connecting to target hosts).

To create a local PrivX user:

  1. Navigate to the address of the PrivX server and log in as superuser.

  2. In the PrivX GUI, navigate to the Settings→Users page and click Add User.

    You will be presented with the New User view.

  3. In the New User view, provide the required information about the user. Click Save to save the user.

    You should now be able to see your new local user back on the Settings→Users page.

PrivX provides access in a role-based manner. To create a role and assign members:

  1. In the PrivX GUI, navigate to the Settings→Roles page, and click Add Role.

    You will be presented with a form for providing information about the new role.

  2. Provide a name for the new role. Also add users to the role by defining rules. To define a new rule for the role, click Add Rule. In this example, we add a rule to include all local users who have the user name (cn) alice into the role:


    The number of role members is indicated by Matching users. The count is updated when you unfocus from the Search String field (such as by pressing enter, or by clicking somewhere else in the GUI).

    Leave the other role settings as they are.

  3. Click Save to finalize role creation. Your new role should be visible back on the Settings→Roles page.

    To verify the users belonging to the role, click List Members:

Adding Target Hosts

Make hosts accessible via PrivX:

On the Settings→Hosts page, click Add Host. Provide at least:

  • The Name and the network Addresses of the host. This optional data helps users identify the target host.

  • The Services (SSH and/or RDP servers) available on the host. In this example we add the SSH server by providing its FQDN address and port number.

  • The Accounts to which roles are mapped on the target host. Leave the Password empty to require password authentication upon connecting. In this example we allow the previously-created example role to access the host as target user root.


    If you are adding an RDP host which uses domain accounts, you must use the username@domain syntax. For example, for domain account Domain\Administrator, the correct syntax is Administrator@Domain.

  • Enable SSH - Trust on first use to allow users to accept the SSH host key upon login.

Click Save to save the host.

You may verify that the host is listed back on the Settings→Hosts page.

Connecting to Target Hosts

After you have set up roles to access hosts, you may test connections as follows:

  1. Log into the PrivX GUI as the test user we created previously (in the section called “Creating Local Users and Roles”).

  2. Navigate to the Connections→Available Hosts page. The hosts you can connect to are listed under Available hosts.

    Expand a connection entry to display its available services. In this example, we click the SSH-server service to connect to our test host.

  3. Accept the SSH host key if prompted. Authenticate to the host by providing the password of the target account (not the PrivX account password). You should now be successfully connected to the host.

Enabling Certificate Authentication for OpenSSH Connections

To enable certificate authentication for OpenSSH connections, run the PrivX host-deployment script on the target host.

The host-deployment script is a Python script that configures the OpenSSH server on the target host to accept certificates issued by PrivX. The script also sets up allowed principals for target users.

To obtain and run the host-provisioning script:

  1. Create a host-deployment script. To do this, access the PrivX GUI as superuser, then go to the Settings→Deployment→Deploy and Configure SSH Target Hosts page.

    Select Configure using a deployment script, provide a name for the script, then click Add Script. Download the script when prompted to.

  2. Upload the host-deployment script to the target host. You may do this via the PrivX GUI by connecting to the target host (similarly as in the section called “Connecting to Target Hosts”), and then by navigating to the File Transfers tab.

  3. Execute the host-deployment script as root on the target host.

    In the command, use --principals to specify the target accounts and the roles that are allowed to access them. Also add the --standalone option if target host was not added previously using a scan script.

    For example, allowing both the target accounts root and johndoe to be accessed by members of Example Role and privx-admin (replace /path/to/ with the path of the host-deployment script, note that role names with spaces need to be quoted):

    # python /path/to/ --standalone --principals \
    root="Example Role",privx-admin:johndoe="Example Role",privx-admin

SSH connections to the target accounts from the specified roles are now authorized using certificates, without prompting users for passwords.

You may also verify that certificate authorization is used by checking the OpenSSH-server logs on the target server. Upon successful certificate authorization there should be a log message like the following:

Accepted publickey for root from port 50930 ssh2: RSA-CERT \
ID alice@ serial 4920619392583124720 (serial 4920619392583124720) \
CA RSA 98:16:36:bf:6e:c6:3f:e5:a1:5e:31:61:c1:37:ef:d8

Importing Users from Directories

You can set up PrivX to automatically add users from user directories. Such users can later be given SSH/RDP access to hosts via PrivX.

For example, to add Active Directory (AD) users:

  1. Configure PrivX to scan the AD server for users. To do this, log into PrivX as superuser (or other privx-admin user). Then on the Settings→Directories page, click Add Directory.

  2. Provide the required AD settings.


    %s in the User DN pattern stands for the user name by which AD users may log into PrivX. For example assume there is an AD user with the following fields:

    sAMAccountName: alice

    In this case, if User DN pattern were set to (sAMAccountName=%s), the user can log in with the user name alice. If User DN pattern were set to (userPrincipalName=%s), the user can log in with the user name

    Save the directory settings. PrivX automatically connects to the AD server to add any users found with the given settings.

  3. You may verify the AD status back on the Settings→Directories page. After PrivX finishes adding users from the AD, the connection status should display OK, along with the number of users added.

    To list the users added from the AD, perform a List Users action on the AD entry.

    To grant AD users access to hosts and services, add them to roles (similarly as in the section called “Creating Local Users and Roles”). For example, you can add an additional rule to the Example Role that was created earlier.

    AD users may then log into the PrivX GUI and establish SSH/RDP connections. The allowed connection targets are determined by the role(s) assigned to the AD users.

Importing Hosts from Directories

You can set up PrivX to automatically add existing hosts on cloud platforms. Such hosts can later be connected to via PrivX.

For example, to add hosts from Amazon Web Services (AWS):

  1. In your AWS, add a policy to allow host scans. To do this, access your AWS and navigate to IAM→Policies, then create a policy with the following JSON:

        "Version": "2012-10-17",
        "Statement": [
                "Effect": "Allow",
                "Action": "ec2:Describe*",
                "Resource": "*"
  2. Create an IAM user with permissions to use the host-scan policy. This can be done on the IAM→Users page.

    The IAM user must have Programmatic access, and be attached with the host-scan policy.

    Note the Access key ID and the Secret access key of the user. These are required later for configuring PrivX against AWS.

  3. Configure PrivX to scan and add the AWS hosts.

    Log into PrivX as superuser (or other privx-admin user). On the Settings→Directories page, click Add Directory.

    Fill in the basic information of the directory. To allow PrivX to detect AWS hosts, add the Access key ID and the Secret access key of the IAM user.

    You can selectively filter hosts using the Fetch hosts with tag option found under the Advanced directory settings.

    Save the directory settings. PrivX begins importing hosts from AWS.

    After a moment, you may verify the directory status back on the Settings→Directories page. The Connection should be in the OK state, and list the number of instances found on AWS.

    To list the imported hosts, click List Hosts.

    You may then Edit hosts to add services and account mappings to them, similarly as in the section called “Adding Target Hosts”.

Search Syntax

You can enter free-text criteria to filter lists.

Some lists (such as hosts, connections, monitoring, and events) support searching by specific criteria, with syntax like the following:


You can include multiple criteria in a search:


You can specify multiple values either by repeating a criteria with different values, or by delimiting the values with a pipe:



Use backslash to escape parentheses and other reserved characters in values:

(criteria=value with \(parentheses\))

Search examples:

  • Find connections with the tag Name=Example Host - (Tag=Name\=Example Host)

  • Find host entries containing both "test" and SSH service(s) - test (Service=SSH)

  • Find hosts with SSH or RDP services - (Service=SSH|RDP)


Type an open parenthesis in the search to see all the supported criteria. Note that not all pages support criteria.

To save a search, first input your search in the search field and press enter. Then click next to the search field, and click Add Favorite.

To restore a saved search, click next to the search field, then select your search.

To manage your saved searches, click next to the search field, then click Edit Favorites. In edit mode you can:

  • Rename a saved search by clicking it.

  • Drag and drop saved searches to reorganize them.

  • Delete a saved search by clicking .


To share a search with another PrivX user, first enter your search, then copy-paste your URL to the other PrivX user.