Keywords: deployment script, deploy.py
PrivX provides a host-deployment script. It is a Python script that can be executed on target hosts to automatically set up certificate authentication.
The host-deployment script has the following system requirements:
- Supported operating systems: Amazon Linux, Arch Linux, CentOS, Fedora, FreeBSD, Debian, Gentoo Linux, OpenSUSE, MacOS, Red Hat, Rocky Linux, Ubuntu.
- Required Python version: 2.7.9+ or 3.6.5+
- Required OpenSSH version: 6.9 or later.
- Network: Connectivity to a PrivX server.
On target hosts that do not support the host-deployment script, and on hosts that cannot connect to PrivX, you can set up certificate-authentication manually as described in Manual Certificate-Authentication Setup.
For hosts that cannot be accessed directly by PrivX, you need to first set up a PrivX Extender for proxying host connections. For more information about PrivX Extender setup, see Setting up Hosts.
On-prem machines must have unique machine IDs. For more information about setting up unique machine IDs, see Host External ID and Deployment Script
To use the host-deployment script to set up certificate authentication on a target host, for connections between certain target accounts and PrivX users from certain roles:
To create a host-deployment script, navigate to the Administration→Deployment→Deploy and configure SSH target hosts page, select Configure using a deployment script.
If you need to granularly delegate host and connection-management permissions, also select the Access group the host is to be deployed to. For more information about access groups, see Host-Specific Management Permissions.
Click Add Script. Download the
deploy.pyscript when prompted to.
Execute the deployment script on the target host as root. You will at least need to provide the host type, and the accounts (specifying which target accounts can be accessed, and by whom).
To specify the host type, use one of the following options:
--aws: The host runs on AWS.
--azure: The host runs on Microsoft Azure.
--google-cloud: The host runs on Google Cloud.
--openstack: The host runs on OpenStack.
--standalone: For non-cloud hosts.
For allowing PrivX users access to target accounts, use any of the following options:
--personal-account-roles: Allow members of certain roles to log in with their personal accounts (to target accounts whose names match their Windows/Unix username). Corresponds to a Directory account.
--principals: Manually define target accounts and the roles that may access them. Corresponds to an Explicit account.
NOTE: If you run deploy script again with different principal, the new run does not remove the principal file in /etc/ssh/auth_principals/ created by the previous execution.
--user-defined-account-roles: Allow members of certain roles to input the target account when connecting (similarly to manual connections). Corresponds to a User-Defined account. Note that this option does not enable certificate-based authentication for the specified roles.
--delegated-principals: Delegate role configuration to PrivX for the given principal. Allows creating new roles on PrivX side, which can access this principal without a need to reconfigure the host.
--delegated-personal-account-roles: Delegate role configuration to PrivX for all target principals. Allows creating new roles on PrivX side, which can access this host without a need to reconfigure the host.
--configure-only: Configures the target host, but does not register the host to PrivX. Can be used to modify existing configuration, if you don't want to override the settings in PrivX.
NOTE: even if target host has been configured to allow access, PrivX needs to still know about it either via host tags or via manual/scripted config.
When deploy script is being run, it will overwrite the PrivX host configuration with the actual config on the target host. This flag is useful, If you have done manual changes to host on PrivX side and do not wish to overwrite those settings.
--show-config: Show which PrivX roles and principals SSHD allows to connect to the host. Verifies the role configs on the target host. This shows only the host SSHD configuration and does not verify PrivX configuration for the host.
For more information about account types, see Account Types.
For example, using
--personal-account-roles to allow members of the roles
Example Role 01 and
Example Role 02 to log in with their personal accounts, add:
--personal-account-roles "Example Role 01,Example Role 02"
You may also specify
--principals to define target accounts and the roles that may access them. The general format is:
For example, to allow target account
alice to be accessed by PrivX users belonging to the privx-admin role, set this option to:
As another example, to additionally allow accounts
bob to be accessed by members of
--principals alice=privx-admin,"Example Role":bob="Example Role"
--user-defined-account-roles allow members of selected roles to freely input the target-account name. However, access defined with this option defaults to password authentication unless paired with another account option.
In the following example, members of
Example Role 01 and
Example Role 02 may access any target account with password authentication, but if a member of
Example Role 01 inputs
alice they are authenticated using certificates:
--user-defined-account-roles "Example Role 01,Example Role 02" --principals alice="Example Role 01"
Full syntax example of running the host-deployment script:
# /path/to/deploy.py --standalone \ --personal-account-roles "Example Role 01, Example Role 02" \ --principals alice="Example Role",privx-admin:bob=privx-admin \ --user-defined-account-roles "Example Role 01,Example Role 02"
Finally, you may use
--show-configto verify the results:
[[email protected] ~]# python deploy.py --show-config deploy script version 17.0-0 Access group ID 0bbbc3ef-4771-4292-78af-684151b64428 usepam yes permitrootlogin yes PrivX CA certificate path OK AuthorizedPrincipalsCommand OK authorizedprincipalscommanduser nobody Accepted CA certificates: ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQClupyy3sMlpHP4hQ3qGLxi7TUFmr0EeL7jfcVr1PvaYgP4UCZpYyQ2 Je+MIHNFdnqSBxsuCip8Tr7h033qJmxabjdFVw2B0qnGRsYwAm3PKYbgxwZnolGPbszQfScPuAtdTvo3kOWd IbSL5JYS034bHZ5L5mWCVpyOGIZqP9+Z+RdVM/gyzdCRNX7xU3xWlD5Tw/eVl26oRrrvOHdKSNyPB2QdjQCZ fBcgxPLXMF9tQxqIbwLkjHH70BRdySBdFvWaGCKLL7qI6FQOAcA0HvQF+L1n0oeH1xi7H1up7oPGJ9xe6Zuf rr1wF5jgvkgS2ky5afUI1d0EYjR7Lq1FQmeqfPD9EzvDjjkjpHxqeGUvtjGENJLuFlG8UFIN5S1u9/jWjAse fLUJ+NI4lhmPnqPkj68MMthzGGOdoQFKTrYYms/o+wxyuf5rTEU9ey4nDHzdObKPT9WlXCZhv0Vy5tty2Ql+ 0B06aktqojGY9sE1DT3x9BVUU+2GQdPmCIxvUS4yCJbJle0FtE5QXfHwFoB3kpyfZkglBuzmZi8kEPnqk6FB TSJUWfZwbuflMm3K0DeTBfXy+mbWXc/6YRS+kCZjhVduZCbt5j+Jh8ZJZmVIAOV02aC5jGOd1zQe7+W25+Cf THN6gtbOOJUkIlmkSTVbSpQAyrird8rE9kdoeaPnbw== Certificate login with principal 'centos' allowed for these roles: delegated-roles # All PrivX roles Certificate login with principal 'root' allowed for these roles: 44985f40-5c68-433d-9604-9b493589feb1 # privx-admin OK - verified by privx.local.com e0844e38-460b-5762-4190-b7db71682533 # delegate_test OK - verified by privx.local.com 12312312-1233-1233-1233-123123123123 # mystery role long tex.. Failed to verify - privx.local.com Certificate login with principal 'test' allowed for these roles: 44985f40-5c68-433d-9604-9b493589feb1 # privx-admin OK - verified by privx.local.com 12312312-1234-1234-1234-123123123123 # delegate_test Role id does not match the name - privx.local.com Certificate login with any principal except 'centos,root,test' when using Directory account type, allowed for these roles: delegated-roles # All PrivX roles
For a full list of options supported by the host-deployment-script, run:
$ /path/to/deploy.py --help
For more examples about deployment options, see Configuring SSH target host to accept PrivX connections.
If connections to the target host are relayed via a PrivX Extender, use the
--api-hostname option to specify the Extender's address and port, similarly to the following:
# /path/to/deploy.py --standalone \ --personal-account-roles "Example Role 01" \ --api-hostname "extender.example.com:8443"
You may verify the addresses (subject-alternative names) of your PrivX Extender from its TLS certificate:
# openssl x509 -text -noout -in /opt/privx/extender/extender.crt grep -A 1 "Subject Alternative Name"
The PrivX Extender port is 8443 by default. You may verify the port from the Extender's configuration file, where it is specified by the
Certificates issued by PrivX are very time-sensitive. Even a clock skew of just few minutes may prevent certificates from working correctly.
Verify that the target-host time is correct. Adjust as necessary.
PrivX users belonging to one of the allowed roles should now see the target host on the Connections→Available Hosts page.
You may also verify that certificate-based authentication is used by checking the OpenSSH-server logs on the target server. Upon successful certificate-based authentication there should be a log message like the following:
Accepted publickey for alice from 192.0.2.26 port 50930 ssh2: RSA-CERT \ ID [email protected]:53188 serial 4920619392583124720 \ (serial 4920619392583124720) \ CA RSA 98:16:36:bf:6e:c6:3f:e5:a1:5e:31:61:c1:37:ef:d8
You may disable password login after certificate-based authentication is set up on the target host.
For cloud-based hosts, PrivX can be configured to import allowed principals from host tags. This method simplifies host deployment as principals do not need to be provided for the host-deployment script.
Configuring access with host tags can be used for setting up hosts that mostly lack connection to PrivX: An initial instance must be able to connect to PrivX, but subsequent clones of this instance do not need PrivX connectivity.
To configure allowed principals for a cloud-based host using host tags:
- Add host tags to the host via your cloud-host-management interface (such as EC2 for AWS instances). Host tags must specify the access rules and SSH/RDP services related to the host.
The list of supported host tags is provided later in this section.
When specifying tags for cloud hosts, do not include double-quotation marks in the value.
Configure PrivX to import host tags. To do this, navigate to Administration→Directories in the PrivX GUI and Edit the directory to which the target host belongs to. Enable the Import host instance tags from the directory setting. Click Save to apply your changes.
Deploy the host using the host-deployment script, or manually.
Users from PrivX roles are now able to access the host according to the principals defined in the host tags, with certificate-based authentication.
PrivX supports the following host tags:
Allow target accounts to be accessed by specified PrivX roles using SSH connections. Corresponds to an Explicit account.
Access to each target account is specified with target=roles syntax, where target is the account name and roles is the comma-separated names of PrivX roles allowed to access the account. Each such mapping must be separated with a colon (
For example, to allow target user
alice to be accessed by PrivX roles
Role 01, and to allow target user
bob to be accessed by
privx-ssh-principals=alice=Role 01,privx-admin:bob=Role 02
- Allow target accounts to be accessed by specified PrivX roles using RDP connections. Corresponds to an Explicit account.
Syntax is the same as with the
- Allow target accounts to be accessed by specified PrivX roles using VNC connections. Corresponds to an Explicit account.
Syntax is the same as with the
Allow members of certain role(s) to log in with their personal accounts (to target accounts whose names match their Windows/Unix username) using SSH connections. Corresponds to a Directory account.
Any comma-separated PrivX-role names in
<roles> are allowed login to personal accounts. For example, to allow members of
Role 01 and
Role 02 to login to personal accounts:
privx-ssh-personal-account-roles=Role 01,Role 02
Allow members of certain role(s) to log in with their personal accounts (to target accounts whose names match their Windows/Unix username) using RDP connections. Corresponds to a Directory account.
Syntax is similar to the
- Allow members of certain role(s) to freely specify the target account when connecting with SSH. Corresponds to a User-Defined account. Note that access defined with this option does not grant certificate-based authentication to the specified roles.
Syntax is similar to the
- Allow members of certain role(s) to freely specify the target account when connecting with RDP. Corresponds to a User-Defined account. Note that access defined with this option does not grant certificate-based authentication to the specified roles.
Syntax is similar to the
Specify the SSH-server port of the target host. By default SSH servers run on port 22.
Specify the RDP-server port of the target host. By default RDP servers run on port 3389.
Specify the vnc-server port of the target host. Defaults to 5900.
Specify the port of the SSH server that is used for tunneling VNC connections. Defaults to 22.
If connections to the host are relayed through a PrivX Extender, use this tag to specify the name of the Extender.
For more information about PrivX Extender, see [ XXX →Proxying Connections to Hosts]
Specify the name of the carrier that should be used as the default carrier for this host's web connections.
Toggle auditing for the host. Defaults to
Enabling this prevents using scanned public IP addresses as connection addresses for cloud hosts. This can be used to enforce connecting to hosts via private IP addresses only.
Enable/disable Trust on First Use, allowing regular users to connect to targets without known host keys. If disabled, superuser needs to accept host keys for unknown hosts on the first connection.
For more information about Trust on First Use, see [ XXX →Trusting Target-Host Identities].
Deploy the host to the named access group. If unspecified, the host is deployed to the Default access group.
For more information about access groups, see [ XXX →Host-Specific Management Permissions].
Deploy the host to the access group with the specified ID. If unspecified, the host is deployed to the Default access group.
To obtain the tag in key-value format, split the syntax at the first
=sign. For example, some of the previously-provided examples converted to key-value format:
alice=Role 01,privx-admin:bob=Role 02
Role 01,Role 02
When configuring a new host and registering it to PrivX using deploy script, the host is assigned a unique external ID. For cloud hosts, this external ID is based on instance ID on cloud instance metadata. Instance IDs are automatically used, if you use
--openstack deployment flags.
For on-prem hosts and hosts configured with deploy script but without cloud provider flag, the host's machine-id is used instead.
If you're deploying cloned virtual machines or on-prem hosts using machine-id, make sure your machine id's are unique before running the deploy script. The same thing applies, if running PrivX instances on on-prem hosts. Running HA instances on hosts with duplicate IDs might cause issues with license activations.
If host's machine-id cannot be resolved, the deployment script will fail.
You can check your host's machine ID from
/etc/machine-id, or by running:
# dmidecode --string system-uuid
For more information about machine IDs, see https://www.man7.org/linux/man-pages/man5/machine-id.5.html
You can regenerate the machine-id on most cloned VM OSes with one of the following commands:
uuidgen > /etc/machine-id
For cloned MacOS instances, the machine ID is part of platform registry and can be changed by modifying or resetting NVRAM.
Re-running a deploy script on a host will update the existing host in PrivX host store. Re-running the deployment script requires host's 'deployable' flag to be enabled first for security reasons. If the host does not exist, it will be created. If the host was added using PrivX host directory host scanning feature, the host will have the same external_id as when deploying it with a deployment script and will be updated accordingly.
You should not configure multiple identical host directories which see the same instances. If this is necessary for some reason, use host tagging and "FETCH HOSTS WITH TAG" -feature in PrivX host directory to filter out unwanted hosts.
Hosts added manually via PrivX UI are considered 'local hosts' and have no external ID. Those instances cannot be redeployed via deployment script and need to be configured manually or via automation tools instead.
Updated 3 months ago