Script-Based Certificate-Authentication Setup

Keywords: deployment script, deploy.py, host-deployment script

PrivX provides a Python-based host-deployment script that automatically configures certificate authentication on target hosts.

Prerequisites

Before you run the script, make sure the target host meets the following requirements:

• Operating system: Amazon Linux, Arch Linux, CentOS, Fedora, FreeBSD, Debian, Gentoo Linux, macOS, OpenSUSE, Oracle Linux, Red Hat Enterprise Linux, Rocky Linux, SUSE Linux Enterprise, or Ubuntu
• Python: Version 2.7.9 or later, or version 3.6.5 or later
• OpenSSH: Version 6.9 or later
• Network connectivity: Access to the PrivX Server, unless using the --offline option.

Consider the following deployment scenarios and requirements:

• If the target host does not support the host-deployment script, configure certificate authentication manually. For more information, see Manual Certificate-Authentication Setup.
• If PrivX cannot access the target host directly, configure a PrivX Extender to proxy connections to the host. For setup instructions, see Proxying Connections.
• Each on-premises host must have a unique machine ID. For setup instructions, see Host External ID and Deployment Script.

Quick Setup

Follow this procedure to deploy an on-premises SSH target with the default host-deployment script configuration. For environment-specific configuration options, see Customizing Host Deployment. Before you begin, make sure that the target host meets the following requirements.

tip

PrivX certificates are time-sensitive. A clock difference of a few minutes can prevent certificate authentication. Make sure that the time on the target host is correct. By default, SSH certificates are valid for 5 minutes, starting 2 minutes before the current time on the PrivX Server.

Use the host-deployment script to configure certificate authentication between specified target accounts and PrivX users in specified roles:

1. In Administration → Deployment → Deploy and Configure SSH Target Hosts, select the Configure using a deployment script option.

2. To delegate host-management and connection-management permissions at a more granular level, select from the drop-down menu the access group to which you want to deploy the host. For more information, see Access Groups.

3. Click Add Script, and download the deploy.py script to the target host.

4. Run the deployment script as root.

   1. The following example uses --standalone to add an on-premises host and --delegated-principals-all to allow certificate authentication for all principals. You can configure the permitted roles in the host settings in the PrivX Web UI:

      sudo python3 deploy.py \
      --standalone \
      --delegated-principals-all \

   2. To verify the configuration, run the deployment script with the --show-config option:

      sudo python3 deploy.py --show-config

      After successful deployment, the command displays output similar to the following:

      sudo python3 deploy.py --show-config
      ** GET ssh user CA public key from PrivX
      ** GET principals_command.sh from PrivX
      ** Resolve role IDs
      ** Read ssh public host keys
      PrivX deploy script version 99-7566
      Access group ID 6678583d-56dd-4300-6c9e-a5f1f2088555
      
      usepam yes
      permitrootlogin yes
      trustedusercakeys /etc/ssh/privx_ca.pub
      authorizedprincipalscommand /etc/ssh/principals_command.sh %u
      authorizedprincipalscommanduser nobody
      
      Accepted CA certificates:
      ssh-rsa
      <...>
      
      Certificate login allowed with any role for all principals.

      To view all supported options, run:

      /path/to/deploy.py --help

5. Allow PrivX roles and their users to access target accounts:

   1. In Administration → Hosts, click Edit to edit the added host and then click Add Accounts to specify which roles can access each target account.

   2. Save your changes. PrivX automatically configures passwordless certificate authentication for the specified accounts. Users in the permitted roles can now access the target host in Connections → Available Hosts.

   3. To verify that certificate authentication is used, check the OpenSSH server logs on the target host. After successful certificate authentication, the logs contain a message similar to the following:

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

Customizing Host Deployment

Use the following options to customize the host deployment for your environment. You can configure specific principals and roles, deploy cloud hosts, enable connection justification, or deploy hosts that cannot connect to PrivX. To deploy an on-premises SSH target with the default host-deployment script configuration, see Quick Setup.

Before you begin, make sure that the target host meets the following requirements.

You can customize the following deployment settings:

• Host Platform
• Target-Account Access
• PrivX Extender Configuration
• Additional Configuration Options

Selecting Host Platform

Use one of the following options to specify the target-host platform:

• --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.
• --oracle-cloud: The host runs on Oracle Cloud.
• --proxmox: The host runs on Proxmox VE.
• --vmware: The host runs on VMware ESXi, VMware vCenter, or VMware Cloud.
• --standalone: For an on-premises host or a host on an unsupported cloud platform.

The selected platform affects how PrivX assigns the host to a directory.

When you deploy a cloud host with the deployment script (for example, using --aws or --google-cloud), PrivX adds the host to the Local Hosts directory in any of the following cases:

• PrivX did not discover the host in a cloud directory.
• Directory filters exclude the host.
• PrivX did not scan the host.

If you later configure a cloud host directory that discovers this host, for example, an AWS directory, PrivX moves it from Local Hosts to that cloud directory.

important

The external ID assigned during deployment must match the external ID discovered by the cloud directory. If the IDs do not match, the host remains in Local Hosts and will not be reassigned. To resolve an external-ID mismatch, remove the cloud host or its cloud directory, redeploy the host, and scan the directory again. Make sure that the deployment script and the cloud directory resolve the same external ID.

Defining Target-Account Access

The host-deployment script lets you define target-account access in one or both of the following ways:

• After deployment: Configure access in the PrivX Web UI or through the PrivX API. Use this method for hosts with changing access requirements.
• During deployment: Configure access with command-line options. Use this method when the required access is already known.

Configuring Access After Deployment

Use the following options to allow access to be configured later in the PrivX Web UI or through the PrivX API:

Option	Description
--delegated-principals	Automatically configures certificate authentication for accounts added in the PrivX Web UI that target the specified principals.
--delegated-personal-account-roles	Automatically configures certificate authentication for roles added to a Directory account in PrivX Web UI.
--delegated-principals-all	Automatically configures certificate authentication for all accounts added to the host in PrivX Web UI. Does not work when using the --offline option for standalone hosts.

Configuring Access During Deployment

Use the following options to define access when you run the deployment script:

Option	Description	Account type
--personal-account-roles	Allows members of the specified roles to log in with personal accounts to target accounts whose names match their Windows or Unix usernames.	Directory
--principals	Defines target accounts and the roles that can access them. If you run the deployment script again with different principals, the script does not remove principal files created by previous runs from /etc/ssh/auth_principals/.	Explicit
--user-defined-account-roles	Allows members of the specified roles to enter the target-account name when connecting (similar to manual connections). This option does not enable certificate authentication for these roles.	User-Defined
--target-domains	Sets the target domains for accounts defined with the previous options.	Explicit or Directory

For more information about account types, see Account Types.

Deploying Hosts Behind Extenders

If connections to the target host are relayed through a PrivX Extender, specify the Extender address and proxy port:

# PrivX Extender v1 (default proxy port: 8443)
sudo /path/to/deploy.py --standalone \
--personal-account-roles "Example Role 01" \
--api-hostname <extender-address>:<proxy-port>

# PrivX Extender v2 (default proxy port: 10443)
sudo /path/to/deploy.py --standalone \
--personal-account-roles "Example Role 01" \
--extender <extender-prefix>/<extender-address>:<proxy-port>

The configuration field that specifies the proxy port depends on the PrivX Extender version:

• For PrivX Extender v1, see the host_deployment_listen_address field
• For PrivX Extender v2, see the privx_deployment_proxy_port field

For PrivX Extender v2, the privx_deployment_proxy_enabled field controls whether the Extender accepts requests from the deployment script.

To view the addresses (subject-alternative names) in the PrivX Extender v1 TLS certificate, run:

openssl x509 -text -noout -in /opt/privx/extender/extender.crt | grep -A 1 "Subject Alternative Name"

To verify connectivity to PrivX through PrivX Extender v2, run:

openssl s_client -proxy <extender-address>:<proxy-port> -showcerts -connect <privx-address>:<privx-port>

Configuration Options

Use the following options to configure additional deployment-script behavior:

Option	Description
--enable-justification	Requires users to provide a justification before connecting to the SSH service.
--configure-only	Configures the target host without registering or updating it in PrivX. Use this option when you have manually configured the host in PrivX and do not want the deployment script to overwrite those settings. For users to access the target host, a corresponding host configuration must still exist in PrivX. Create it using host tags or manual or scripted configuration.
--offline	Uses the public key and role IDs (for SSH principals) embedded in the deployment script instead of retrieving them from PrivX. Use this option when the target host cannot connect to PrivX, such as when preparing a VM image. The script does not register the host in PrivX. Configure the host manually or, for a cloud host, import it from the cloud provider. PrivX embeds the latest available public key and role IDs when you download the script.
--show-config	Displays the PrivX roles and principals that the target host’s sshd configuration allows. This option checks only the configuration on the target host. It does not verify the corresponding host configuration in PrivX.

Deployment-Script Examples

The following example configures several target-account access methods:

sudo /path/to/deploy.py --standalone \
--delegated-principals-all
--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"

This example configures the following:

• --standalone specifies an on-premises host or a host on an unsupported cloud platform.
• --delegated-principals-all automatically configures certificate authentication for accounts added to the host in the PrivX Web UI or through the PrivX API.
• --personal-account-roles allows members of Example Role 01 and Example Role 02 to use certificate authentication with their personal accounts.
• --principals allows members of Example Role to access the alice account and members of the privx-admin role to access the bob account.
• --user-defined-account-roles allows members of Example Role 01 and Example Role 02 to enter the target-account name when connecting. This option does not enable certificate authentication for these roles.

If connections to the target host are relayed through PrivX Extender v1, use --api-hostname to specify the Extender address and proxy port:

sudo /path/to/deploy.py --standalone \
--personal-account-roles "Example Role 01" \
--api-hostname "extender.example.com:8443"

To view the subject alternative names in the PrivX Extender TLS certificate, run:

sudo openssl x509 -text -noout -in /opt/privx/extender/extender.crt | grep -A 1 "Subject Alternative Name"

The default proxy port for PrivX Extender v1 is 8443. To verify the configured port, check the host_deployment_listen_address field in the PrivX Extender configuration file.

After you configure and verify certificate authentication on the target host, you can disable password authentication.

Configuring Access Using Host Tags

For cloud-based hosts, PrivX can import access settings and other host configuration from cloud-provider tags. With this method, you do not need to provide principals when you run the host-deployment script.

You can also use host tags when deploying multiple hosts that cannot connect directly to PrivX. The initial host must connect to PrivX during deployment, but subsequent clones of that host do not require connectivity to PrivX.

Setting Up Cloud Hosts with Host Tags

To configure a cloud host using host tags:

1. Add the required tags to the host in your cloud-provider management interface, such as Amazon EC2. The tags must define the required access rules and SSH/RDP services related to the host. The list of supported host tags is provided later in this section.

   Hosts can have the following types of tags:

   • User-defined tags: Added manually when you run the host-deployment script. You can also add these tags later in the PrivX Web UI or through the PrivX API.
   • Cloud-provider tags: Added to the host through the cloud-provider platform.
   important

   When configuring tags for cloud hosts, note the following:

   • Changes made to cloud-provider tags in PrivX are overwritten during the next host-directory scan. To make permanent changes, update the tags through the cloud-provider platform.
   • Do not enclose cloud-host tag values in double quotation marks.

2. Configure PrivX to import the tags:

   1. In Administration → Directories, click Edit to edit the directory to which the target host belongs.
   2. Enable the Import host instance tags from the directory option and click Save to apply your changes.

3. Deploy the host manually or with the host-deployment script. After deployment, PrivX users in the specified roles can use certificate authentication to access the target accounts defined in the imported host tags.

PrivX supports host tags in the following categories:

1. Target Account Access Tags: Define target accounts, permitted PrivX roles, and target domains.
2. Service Port Tags: Configure ports for SSH, RDP, and VNC services.
3. Connection and Integration Tags: Configure SSH certificates, PrivX Extender, PrivX Carrier, web connections, and connection justification.
4. Access Group Tags: Assign hosts to PrivX access groups.
5. Auditing and Host Key Verification Tags: Configure auditing and SSH host-key verification.

Some cloud-provider interfaces provide separate fields for tag keys and values. To learn how to enter the supported host tags in this format, see Host Tags in Key-Value Format.

1. Target Account Access Tags

Use the following tags to define which target accounts PrivX roles can access and how PrivX maps those accounts.
For more information about account types, see Account Types.

1.1. privx-ssh-principals

Description: Allows specified PrivX roles to access target accounts over SSH.

Account type: Explicit.

Syntax: privx-ssh-principals=<target>=<roles1>:<target2>=<roles2>:...
Define access to each target account by using the <target>=<roles> syntax, where <target> is the account name and <roles> is a comma-separated list of PrivX role names. Separate mappings with a colon (:).

Example: The following tag allows the privx-admin and Role 01 roles to access the alice target account and the Role 02 role to access the bob target account:

privx-ssh-principals=alice=Role 01,privx-admin:bob=Role 02

1.2. privx-rdp-principals

Description: Allows specified PrivX roles to access target accounts over RDP.

Account type: Explicit.

Syntax: privx-rdp-principals=<target1>=<roles1>:<target2>=<roles2>:...
Define access to each target account by using the <target>=<roles> syntax, where <target> is the account name and <roles> is a comma-separated list of PrivX role names. Separate mappings with a colon (:).

1.3. privx-vnc-principals

Description: Allows specified PrivX roles to access target accounts over VNC.

Account type: Explicit.

Syntax: privx-vnc-principals=<target1>=<roles1>:<target2>=<roles2>:...
Define access to each target account by using the <target>=<roles> syntax, where <target> is the account name and <roles> is a comma-separated list of PrivX role names. Separate mappings with a colon (:).

1.4. privx-web-principals

Description: Allows specified PrivX roles to access target accounts through web connections.

Account type: Explicit.

Syntax: privx-web-principals=<target1>=<roles1>:<target2>=<roles2>:...
Define access to each target account by using the <target>=<roles> syntax, where <target> is the account name and <roles> is a comma-separated list of PrivX role names. Separate mappings with a colon (:).

Example: The following tag allows members of the privx-admin role to use the root target account for web connections:

privx-web-principals=root=privx-admin

1.5. privx-ssh-personal-account-roles

Description: Allows members of specified PrivX roles to use SSH to log in with personal accounts whose names match their Windows or Unix usernames.

Account type: Directory.

Syntax: privx-ssh-personal-account-roles=<roles>
In <roles>, specify a comma-separated list of PrivX role names.

Example: The following tag allows members of Role 01 and Role 02 to log in with their personal accounts:

privx-ssh-personal-account-roles=Role 01,Role 02

1.6. privx-rdp-personal-account-roles

Description: Allows members of specified PrivX roles to use RDP to log in with personal accounts whose names match their Windows or Unix usernames.

Account type: Directory.

Syntax: privx-rdp-personal-account-roles=<roles>
In <roles>, specify a comma-separated list of PrivX role names.

1.7. privx-target-domain

Description: Maps target domains to target accounts.

Account type: Explicit or Directory.

Syntax: privx-target-domain=<target1>=<targetDomain1>:<targetDomain2>[,<usernameAttribute>]
Configure the mapping according to the account type. Separate multiple mappings with a colon (:).

• For an Explicit account, use the <target>=<targetDomain> syntax, where <target> is the name of an account defined in another host tag.
• For a Directory account, specify the target domain name <targetDomain>. To specify the directory account’s Username Attribute, use the <targetDomain>,<usernameAttribute> syntax.

1.8. privx-ssh-user-defined-account-roles

Description: Allows members of specified PrivX roles to select the target account when connecting over SSH. Access defined with this tag does not grant certificate-based authentication to the specified roles.

Account type: User-Defined.

Syntax: privx-ssh-user-defined-account-roles=<roles>
In <roles>, specify a comma-separated list of PrivX role names.

1.9. privx-rdp-user-defined-account-roles

Description: Allows members of specified PrivX roles to select the target account when connecting over RDP. Access defined with this tag does not grant certificate-based authentication to the specified roles.

Account type: User-Defined.

Syntax: privx-rdp-user-defined-account-roles=<roles>
In <roles>, specify a comma-separated list of PrivX role names.

2. Service Port Tags

Use these tags to configure service ports.

Tag	Description and Syntax	Default Port
privx-ssh-service-port	Specifies the SSH server port on the target host: privx-ssh-service-port=<port>	22
privx-rdp-service-port	Specifies the RDP server port on the target host: privx-rdp-service-port=<port>	3389
privx-vnc-service-port	Specifies the VNC server port on the target host: privx-vnc-service-port=<port>	5900
privx-vnc-tunnel-port	Specifies the SSH server port used to tunnel VNC connections: privx-vnc-tunnel-port=<port>	22

3. Connection and Integration Tags

Use the following tags to configure SSH certificates, connection routing, web connections, private IP address usage, and connection justification.

3.1. privx-ssh-certificate-template

Description: Specifies the SSH certificate template used for the host deployment.

Syntax: privx-ssh-certificate-template=<templatename>
In <templatename>, specify the name of an available certificate template. By default, the following certificate templates are available:

GitHub Enterprise
GitLab
default-openssh-sha1
default-openssh-sha2
default-x509v3-rfc6187
default-x509v3-tectia

Example: The following tag configures PrivX to use the default-openssh-sha2 certificate template:

privx-ssh-certificate-template=default-openssh-sha2

3.2. privx-extender

Description: Specifies the name of the PrivX Extender that relays connections to the host. For more information, see Proxying Connections to Hosts.

Syntax: privx-extender=<extendername>
In <extendername>, specify the name of the PrivX Extender.

Example: The following tag routes connections to the host through exampleExtender:

privx-extender=exampleExtender

3.3. privx-carrier

Description: Specifies the name of the PrivX Carrier used by default for web connections to the host.

Syntax: privx-carrier=<carriername>
In <carriername>, specify the name of the PrivX Carrier.

Example: The following tag configures exampleCarrier as the default PrivX Carrier for web connections to the host:

privx-carrier=exampleCarrier

3.4. privx-allow-modified-url-params

Description: Allows users to modify query parameters in the configured web service URL when launching a connection through PrivX Carrier. Use this tag to support dynamic query parameters for deep links.

Syntax: privx-allow-modified-url-params=yes
Set the value to yes to allow a web service connection when its URL differs from the URL in the host configuration. By default, PrivX blocks a connection if the web service URL differs from the URL in the host configuration.

3.5. privx-use-private-ips-only

Description: Defines whether PrivX uses only private IP addresses to connect to cloud hosts.

Syntax: privx-use-private-ips-only=<yes|no>
Set the value to yes to prevent PrivX from using scanned public IP addresses as connection addresses. Set the value to no to allow PrivX to use scanned public IP addresses.

3.6. privx-justify-conn

Description: Requires users to provide a justification before connecting to specified services: SSH, RDP, VNC, and web connections. Connection justification applies only to services registered during a host scan. The tag does not enable the services it describes.

Syntax: privx-justify-conn=<service-1=port-1,port-2,...>:<service-2>:...<service-n>
Specify a service type and, optionally, one or more service ports:

• Use an equals sign (=) to separate a service type from its ports.
• Use a comma (,) to separate multiple ports.
• Use a colon (:) to separate services.
• Omit the ports to require justification for all registered ports of a service.

Example: The following tag requires connection justification for SSH connections on ports 22 and 2222, RDP connections on port 3389, and VNC connections on port 5000:

privx-justify-conn=ssh=22,2222:rdp=3389:vnc=5000

To require justification for all registered SSH services, omit the SSH ports:

privx-justify-conn=ssh:rdp=3389:vnc=5000

4. Access Group Tags

Use these tags to add the host to an access group by name or ID.

4.1. privx-access-group

Description: Deploys the host to the named access group. For more information about access groups, see Access Groups.

Syntax: privx-access-group=<access_group_name>
In <access_group_name>, specify the name of the access group. If you do not specify this tag, PrivX deploys the host to the Default access group.

Example: The following tag deploys the host to the examplegroup01 access group:

privx-access-group=examplegroup01

4.2. privx-access-group-id

Description: Deploys the host to the access group with the specified ID. For more information about access groups, see Access Groups.

Syntax: privx-access-group-id=<access_group_id>
In <access_group_id>, specify the ID of the access group. If you do not specify this tag, PrivX deploys the host to the Default access group.

Example: The following tag deploys the host to the access group with the specified ID:

privx-access-group-id=0bbbc3ef-4771-4292-78af-684151b64428

5. Auditing and Host Key Verification Tags

Use these tags to configure auditing and how PrivX verifies SSH host keys.

5.1. privx-enable-auditing

Description: Enables or disables auditing for the host.

Syntax: privx-enable-auditing=<yes|no>
Set the value to yes to enable auditing or no to disable auditing. Default value: no.

5.2. privx-trust-on-first-use

Description: Enables or disables Trust on First Use. For more information about Trust on First Use, see Trusting Target-Host Identities.

Syntax: privx-trust-on-first-use=<yes|no>
Set the value to yes to allow regular users to connect to targets with unknown host keys. Set the value to no to require a superuser to accept an unknown host key during the first connection.

5.3. privx-trust-on-changed-host-keys

Description: Controls whether regular users can accept changed SSH host keys.

Syntax: privx-trust-on-changed-host-keys=<yes|no>
Set the value to yes to allow regular users to accept a changed SSH host key. Set the value to no to allow only privileged users to accept the changed host key. Default value: no. If a host-key mismatch occurs, the connection of a regular user is terminated.

warning

Keep this option disabled unless your network environment verifies host identities in another way. Allowing regular users to bypass host-key verification can expose them to man-in-the-middle attacks.

5.4. privx-ssh-host-key

Description: Specifies the SSH host key of the target host. This allows PrivX to add a new SSH target without prompting a user to accept the host key.

Syntax: privx-ssh-host-key=<key>
In <key>, specify the SSH host key, including its key type and Base64-encoded value.

note

Some cloud providers limit the length of tag values. If the SSH host key exceeds this limit, add the privx-ssh-host-key tag as a user-defined tag through the PrivX Web UI or API.

Example: The following tag specifies an Ed25519 host key:

privx-ssh-host-key=ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHw5FGozpZ+H9EFBv0JrGiJ9pSD5HxM3W7ZsSW6q2POq

Host Tags in Key-Value Format

Some cloud-provider interfaces require tags to be entered as separate keys and values. To convert a tag to key-value format, split its syntax at the first equals sign (=).

The following table shows some of the previous examples in key-value format:

Key	Value
privx-ssh-principals	alice=Role 01,privx-admin:bob=Role 02
privx-ssh-personal-account-roles	Role 01,Role 02
privx-ssh-service-port	22
privx-rdp-service-port	3389
privx-ssh-certificate-template	default-openssh-sha2
privx-extender	example-extender
privx-enable-auditing	yes
privx-use-private-ips-only	no
privx-trust-on-first-use	yes
privx-access-group	examplegroup01
privx-access-group-id	0bbbc3ef-4771-4292-78af-684151b64428
privx-ssh-host-key	ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHw5FGozpZ+H9EFBv0JrGiJ9pSD5HxM3W7ZsSW6q2POq

Host External ID and Deployment Script

When the deployment script registers a new host in PrivX, it assigns the host a unique external ID. The source of the external ID depends on the host type:

• For cloud hosts, PrivX uses the instance ID retrieved from the cloud-instance metadata. The deployment script selects the instance ID automatically when you use --aws, --azure, --google-cloud, --openstack, --oracle-cloud, --proxmox or --vmware deployment options.
• For on-premises hosts and hosts deployed without a cloud-provider option, PrivX uses the machine ID.

Before you run the deployment script on cloned VMs or on-premises hosts:

• Make sure that each host has a unique machine ID. This requirement also applies to on-premises hosts running PrivX Servers. Running PrivX HA instances on hosts with duplicate machine IDs can cause license-activation issues.
• If the deployment script cannot determine the machine ID, the deployment fails. For more information about machine IDs, see machine-id(5) — Linux manual page.

The deployment script can use either of the following values as the host machine ID:

• Linux machine ID: Stored in /etc/machine-id. To view it, run cat /etc/machine-id.
• System UUID: Assigned to the system hardware or VM. To view it, run sudo dmidecode --string system-uuid.

These values identify the host independently and are not expected to match. The Linux machine ID is generated during operating-system installation and can be changed. Cloning a VM can also copy this value, so make sure that each cloned host has a unique Linux machine ID.

Depending on the operating system, use one of the following commands to regenerate a machine ID for a cloned VM:

systemd-machine-id-setup
setup-machine-id
uuidgen > /etc/machine-id

For cloned macOS instances, the machine ID is stored in the platform registry. To change it, modify or reset the NVRAM.

Redeploying Hosts

When you rerun the deployment script, PrivX uses the external ID to identify and update the existing host. For security reasons, enable the host’s deployable flag before rerunning the script:

• If PrivX does not contain a host with the same external ID, the script creates a new host.
• If a host-directory scan previously discovered the host, its external ID matches the ID generated by the deployment script, and the script updates the existing host.

Do not configure multiple identical host directories that discover the same instances. If multiple directories are required, use host tags and the Fetch Hosts with Tag setting in the PrivX host directory to exclude unwanted hosts from each directory.

Hosts added manually in the PrivX Web UI are stored in 'local hosts' and do not have external IDs. You cannot redeploy these hosts with the deployment script. Configure them manually or use an automation tool instead.