Access the PrivX GUI and navigate to the Settings→License page.

Under the License code section, enter your license code, and click Update License.

PrivX automatically installs your license, which enables PrivX functionality according to your license subscription.

Duplicate the PrivX database.

Upgrade shall be performed against the duplicate database, without modifying the original database.

Upgrade one PrivX server along with the duplicate database:

Set up additional PrivX servers into your upgraded environment:

After all the PrivX servers have been upgraded successfully, you should replicate any new data accumulated during the upgrade from the original database to the duplicate database. This completes the upgrade.

You may remove the original database and leftover PrivX servers after successful upgrade.

The initial setup has generated a certificate-signing request (CSR), which can be enrolled with a trusted CA for a trusted server certificate. The CSR is located at the following path on the PrivX server:

/etc/nginx/ssl/nginx.csr

Enroll this CSR with your CA. In response, the CA should provide you with the following:

	Note
	Note to certificate-signing authorities: The PrivX CSR contains subjectAltName definitions for DNS and IP addresses. These are critical to PrivX operation and must be preserved in the signed server certificate.

Copy the PEM (Base64) encoded server-certificate file to the ssl_certificate location on the PrivX instance. By default, the location is:

/etc/nginx/ssl/nginx.crt

Ensure that the server-certificate file has correct ownership, permissions, and SELinux context:

# chown root:nginx /etc/nginx/ssl/nginx.crt
# chmod 0640 /etc/nginx/ssl/nginx.crt
# restorecon /etc/nginx/ssl/nginx.crt

Update the trust anchor for PrivX microservices. To do this, run the following command (replace /path/to/ca_chain.crt with the path to the CA-certificate-chain file):

# /opt/privx/scripts/init_nginx.sh update-trust /path/to/ca_chain.crt

	Note
	In single-server deployments, provide the CA chain of the PrivX-server certificate. In HA deployments, provide the CA chain of the load-balancer certificate. init_nginx.sh requires PEM-encoded certificate files to have Unix line endings. If the command fails, ensure correct line endings in the CA-certificate-chain file, then rerun the command.

Finally, restart the Nginx and PrivX services to start using the new server certificate:

# systemctl restart nginx
# systemctl restart privx

Gain root-terminal access to a PrivX server, and display the PrivX-CA-key ID by running:

# /opt/privx/bin/keyvault-tool -name "PrivX CA Key" list-asymmetric

Generate a Certificate-Signing Request (CSR) for the CA private key (replace <key_id> with the PrivX-CA-key ID):

# /opt/privx/bin/cert-tool -command create -type authorizer-ca \
-subject "OU=PrivX Authorizer CA/CN=PrivX CA" \
-key <key_id> -csr -csrout privx-im-ca.csr

This creates the CSR to the file privx-im-ca.csr in your current working directory.

Request a trusted CA to sign the CSR with the following constraints:

After the trusted CA provides you with the signed certificate, you may verify its constraints with (replace privx-im-ca.crt  with the path to the signed certificate):

$ openssl x509 -text -noout -in privx-im-ca.crt 

Replace the Authorizer certificate. First, obtain the ID of the current Authorizer certificate:

# /opt/privx/bin/cert-tool -command list -type authorizer-ca

Then delete the current Authorizer certificate (replace <cert_id> with the Authorizer-certificate ID):

# /opt/privx/bin/cert-tool -command delete -id <cert_id>

Finally, import the signed certificate (replace <key_id> with the PrivX-CA-key ID, replace privx-im-ca.crt  with the path to the signed certificate):

# /opt/privx/bin/cert-tool -command import -type authorizer-ca \
-key <key_id> -in privx-im-ca.crt

On all PrivX servers, restart the PrivX services to apply the changes:

# systemctl restart privx

Subsequent certificates issued by PrivX are signed using the new trusted Authorizer CA certificate.

Navigate to the Settings→Hosts page, and Edit the target host.

Under the Accounts section, specify mappings from roles to target users. Multiple roles may be mapped to one target user. If a role is mapped to multiple target users, the members of that role may choose which user to connect as.

Save your changes to the host. PrivX users belonging to the specified role(s) can now access the target host as the target user(s) they are mapped to. PrivX users can see accessible target hosts on the Connections→New Connection page.

For more information about connecting to target hosts see Chapter 8.

To enable automatic email notifications, configure PrivX against an existing SMTP server. You can set the relevant email settings from the PrivX GUI, on the Settings→Workflows page.

If the email-server connection uses TLS, the email-server root-CA certificate must be added to the system-wide trust anchors on your PrivX servers. To do this, copy the root-CA certificate under:

/etc/pki/ca-trust/source/anchors/

Then run:

# update-ca-trust extract

Ensure the directory-server certificate specifies the server DNS and/or IP addresses in the SubjectAltName field. You can do this, for example, using openssl (replace directory.example.com and 636 with the address and the port of the directory service):

$ echo "Q" | \
openssl s_client -connect directory.example.com:636 | \
openssl x509 -noout -text

On the PrivX server, place the directory-server CA certificate under the trust-anchors directory, located at:

/etc/pki/ca-trust/source/anchors/

Then to add the certificate to the system trust store, run:

# update-ca-trust extract

You may verify that the PrivX server correctly authenticates the directory server (replace directory.example.com and 636 with the address and the port of the directory service):

$ openssl s_client -connect directory.example.com:636

With the correct certificate setup, you should get:

Verify return code: 0 (ok).

Restart PrivX to apply the changes:

# systemctl restart privx

On the Settings→Directories page, Edit your user directory.

Under the Active directory settings section, specify a User filter for matching users on the user directory.

Click Save to apply your changes. Your new User filter overrides the default pre-filter.

To create a host-deployment script, navigate to the Settings→Deployment→Deploy and configure SSH target hosts page, select Configure using a deployment script, then click Add Script. Download the deploy.py script 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 principals (specifying which target accounts can be accessed, and by whom).

To specify the host type, use one of the following options:

To specify principals, use any of the following options:

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:

--principals target_account1=role1,role2,…:target_account2=role3,role4,…:… 

For example, to allow target account alice to be accessed by PrivX users belonging to the privx-admin role, set this option to:

--principals alice=privx-admin

As another example, to additionally allow accounts alice and bob to be accessed by members of Example Role:

--principals alice=privx-admin,"Example Role":bob="Example Role"

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

For a full list of options supported by the host-deployment-script, run:

$ /path/to/deploy.py help

Certificates issued by PrivX are very time-sensitive. Even a clock skew of few minutes may prevent certificates from working correctly.

Verify that the target-host time is correct. Adjust as necessary.

Ensure the system clocks are synchronized (for example, using NTP). The certificates issued by PrivX have very short validity periods: clock skew may cause authentication to fail.

The SSH server on the target host must be configured to trust certificates issued by PrivX (the section called “Trusting PrivX Certificates”).

For target user accounts, specify the principals that are allowed to connect. Depending on the target-host OpenSSH version, you can do this in either of the following methods:

To display the target hosts and accounts under known targets in PrivX, add the host to PrivX (the section called “Setting up Known Targets”).

For target hosts to trust PrivX certificates, you must publish the PrivX CA certificate in the Windows domain.

To obtain the PrivX CA certificate, go to the PrivX GUI. On the Settings→Deployment→Configure a Windows Domain for RDP Access page, click Download Certificate.

Add the PrivX CA certificate to the Trusted Root Certification Authorities for the domain.

For improved security, also restrict the purposes of the PrivX CA: In the general properties of the PrivX CA certificate, select Enable only the following purposes, then select the following purposes:

Save your changes to the certificate.

For more information, please refer to Microsoft documentation at https://docs.microsoft.com (search title: distribute certificates to client computers by using group policy).

Publish the PrivX CA certificate to the domain (replace privx_ca.crt with the path of the PrivX CA-certificate file):

$ certutil -dspublish -f privx_ca.pem NTAuthCA

Also ensure that the registry is updated by running:

certutil -addstore -enterprise NTAuth privx_ca.pem

On all target hosts, ensure that the host allows remote connections without Network Level Authentication.

Define which roles are allowed to access the target hosts, and as which target accounts. For more information about mapping roles to target accounts, see the section called “Setting up Known Targets”.

Certificates issued by PrivX are very time-sensitive. Even a clock skew of few minutes may prevent certificates from working correctly.

Verify that the system times on the target hosts is correct. Adjust as necessary.

On the Settings→Hosts page, Edit the target RDP server.

Under the RDP host certificate section, click

Upon next RDP connection, PrivX automatically accepts the new RDP-server certificate for subsequent RDP connections.

Modify the RDP proxy settings, located at the following path on your PrivX servers:

/opt/privx/etc/rdp-proxy.toml

Locate and modify the following settings:

These two settings are cumulative. For example, to allow the RDP-server certificate to be renewed from two months and 15 days before the current one expires:

[certificates]
update_automatically = true
renewal_period_months = 2
renewal_period_days = 15

Save your changes to the RDP-proxy configuration.

Restart the PrivX services to apply the new settings:

# systemctl restart privx

In your AWS management interface, create an IAM user for obtaining AWS roles. To do this, provide the AWS user with the following permission policies:

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "sts:GetFederationToken",
"Resource": [ "*" ]
},
{
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": [ "*" ]
},
{
"Effect": "Allow",
"Action": [
"iam:ListRoles",
"iam:ListAttachedRolePolicies",
"iam:GetPolicy",
"iam:GetPolicyVersion",
"iam:ListPolicies",
"iam:ListPolicyVersions",
"ec2:DescribeInstances",
"ec2:DescribeRegions"
],
"Resource": [ "*" ]
}
]
}

	Note
	The ec2:Describe* permissions are only required for scanning AWS hosts, which is functionality associated to all AWS directories in PrivX. The ec2:Describe* permissions may be omitted if you only want to import AWS roles, however note that doing so results in the AWS directory in PrivX having a constant error status.

PrivX uses this AWS user to import and delegate AWS roles. For this reason you must also create a Secret Access Key for the user. Copy the Access Key ID and the Secret Access Key of the user, which are required later for configuring PrivX.

In your AWS management interface, create AWS role(s) that grant access to AWS services. The AWS role(s) should have permissions like the following (replace the example Actions with services and actions this role should allow access to):

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:Get*",
"s3:List*"
],
"Resource": [ "*" ]
}
]
}

Also set the trust relationships of the AWS role similar to the following (replace <iam_user_arn> with the ARN of the previously-created IAM user):

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "<iam_user_arn>"
},
"Action": "sts:AssumeRole",
"Condition": {}
}
]
}

	Note
	To allow CLI users to assume the role via PrivX, the AWS role must have a unique Name tag.

	Tip
	Place PrivX-specific roles under a unique path (such as /privx/). PrivX can be configured to import roles from this path, ignoring irrelevant roles in your AWS environment.

On the Settings→Directories page of the PrivX GUI, add a directory of the type Amazon Web Services. Provide the Access key ID and Secret Access Key of the previously-created IAM user.

Also under Advanced AWS settings, select Enable AWS role federation. If you only want to import roles under a certain path, set this path to AWS role prefix for federated roles

Save the directory configuration. To verify that roles were imported successfully, ensure that the previously-configured AWS roles are visible on the page Settings→Deployment→Configure Amazon Web Service role grants.

Grant AWS roles to PrivX roles. To do this, go to the page Settings→Deployment→Configure Amazon Web Service role grants, and Edit the AWS roles. PrivX users belonging to specified roles can now gain access according to any AWS roles granted to them.

Log into the CLI account on your workstation, activate the PrivX agent if necessary.

Use the PrivX agent to log into PrivX (replace username with your PrivX-user name):

$ privx-agent-ctl login username

Determine and assume an AWS role available for your account (replace example_aws_role with the name of the role you want to assume):

$ privx-agent-ctl aws-role list

$ privx-agent-ctl aws-role set example_aws_role

You may verify that you have successfully assumed the role by listing the AWS roles. It should be marked with an asterisk (*). For example:

$ privx-agent-ctl aws-role list
Available AWS roles:
example_aws_role_0
*example_aws_role
example_ws_role_2
...

You are now permitted to run any AWS services permitted by the AWS role. For example, if the AWS role gives you read access to the s3 service, you can now run:

$ aws s3 ls s3://bucket.example.com/

Obtain the following, required for configuring native clients:

Extract and install the PrivX agents to the workstation. For example (replace PrivX-Agents-*.zip with the path to the agent-software package):

# unzip -j PrivX-Agents-*.zip linux-amd64/privx-* -d /usr/local/bin/

The example command installs the PrivX agent, the agent utility, and the agent proxy to:

The following steps assume the PrivX agent and the agent utility to be in these locations.

Enable PrivX agent to start automatically when the user logs into the workstation. You can do this by appending the following to the users' .profile file:

# Start PrivX Agent unless there is already an ssh-agent running
START_PRIVX_AGENT="yes"
PRIVX_AGENT_UNIX="/usr/local/bin/privx-agent-unix"
if [ -n "$START_PRIVX_AGENT" ] && [ -z "$SSH_AUTH_SOCK" ] && \
[ -x "$PRIVX_AGENT_UNIX" ]; then
PRIVX_AGENT_DIR=`mktemp -d /tmp/ssh-XXXXXXXXXX 2>/dev/null || \
mktemp -d -t 'mytmpdir'`
export PRIVX_AUTH_SOCK="$PRIVX_AGENT_DIR/agent.$$"
export PRIVX_AGENT_PROXY="$PRIVX_AGENT_DIR/proxy.$$"
nohup $PRIVX_AGENT_UNIX -a $PRIVX_AUTH_SOCK -x $PRIVX_AGENT_PROXY \
-config $HOME/.privx/agent.json > /dev/null 2>&1 &
export PRIVX_AGENT_PID=$!
export SSH_AUTH_SOCK="$PRIVX_AUTH_SOCK"
export SSH_AGENT_PID="$PRIVX_AGENT_PID"
trap 'test -n "$SSH_AGENT_PID" && kill $SSH_AGENT_PID' 0
fi

	Note
	The provided example commands for agent startup are not run if another application sets the SSH_AUTH_SOCK variable (such as a default ssh agent), nor if the PrivX agent is installed to a custom location. You may have to adjust the agent-startup conditions to suit your environment. The temporary-directory path /tmp/ssh-XXXXXXXXXX is used by the agent. Do not change this path.

Add PrivX servers to the agent. To do this, log in to the workstation as the user who will be using native clients (in order to start the agent), then run the following (replace https://privx.example.com with the address of your PrivX server):

$ privx-agent-ctl server probe https://privx.example.com

Unless the PrivX server certificate is trusted on the workstation, you will be presented with additional information, such as the SHA checksums of the certificate.

PrivX server 'https://privx.example.com' certificate is untrusted
Server TLS certificate:
Issuer        DC=com, DC=ssh, DC=fi, DC=hel, OU=QA, CN=MSCA-PKI-TEST2-ROOT-CA
Subject       OU=PrivX Web Server, CN=privx.hel.fi.ssh.com
Serial        2453081971937566630710942289116460769316175891
Not Before    2018-03-28 09:00:15 +0000 UTC
Not After     2028-03-28 09:10:15 +0000 UTC
Fingerprints
SHA1        B5 F3 70 E2 DB 61 56 D9 AC AE 03 4D AE DC 01 4C FB D2 AB C0
SHA256      17 22 63 69 D1 AA 77 34 96 BD B7 90 69 83 E7 30 97 A2 78 10 \
73 5C 93 D0 D6 01 99 5C 04 C5 55 B2

Would you like to add this server to trusted servers? Y/N:

You may ensure that these match to the checksums of the PrivX server certificate, which you can obtain by running the following on the PrivX server:

# openssl x509 -noout -fingerprint -sha1 -in /etc/nginx/ssl/nginx.crt
# openssl x509 -noout -fingerprint -sha256 -in /etc/nginx/ssl/nginx.crt

Once you have confirmed the server identity, enter Y to add the PrivX server.

Log into the workstation as the user for whom native clients have been set up.

Verify that the agent is running with:

$ privx-agent-ctl status

The command should return a message similar to the following:

PrivX SSH Agent Status
PrivX Server          https://privx.example.com
Login status          logged out

If necessary, you can manually start the PrivX agent with:

$ ./privx-agent-unix bash

Via the terminal, authenticate against PrivX using your PrivX credentials. For example (replace username with your PrivX user name):

$ privx-agent-ctl login username

You may verify your login status with:

$ privx-agent-ctl status

After entering your PrivX credentials correctly, your native SSH clients (such as ssh) will authenticate connections via PrivX. For a list of valid connection targets, run:

$ privx-agent-ctl target list

Accessible targets and granting roles:

bilberry
alice@10.1.55.144:222           Example Role 01
...

You could then connect to one of the listed targets. In this example, by running:

$ alice@10.1.55.144 -p 222

Obtain the following, required for configuring native clients:

Extract and install the PrivX agents to the workstation. For example (replace PrivX-Agents-*.zip with the path to the agent-software package):

# unzip PrivX-Agents-*.zip darwin-amd64/privx-*
# cp darwin-amd64/privx-agent-unix /usr/local/bin/
# cp darwin-amd64/privx-agent-ctl /usr/local/bin/
# cp darwin-amd64/privx-agent-start.sh /usr/local/bin/
# cp darwin-amd64/privx-nc /usr/local/bin/

The example commands install the PrivX agent, the agent utility, the agent-startup script, and the agent proxy to:

The following steps assume the PrivX agent, the agent utility, and the agent-startup script to be in these locations.

Enable PrivX agent to start automatically when the user logs into the workstation. To do this, first install the agent launcher with:

# cp darwin-amd64/com.privxagent.plist ~/Library/LaunchAgents/
# launchctl load -w ~/Library/LaunchAgents/com.privxagent.plist
# launchctl start ~/Library/LaunchAgents/com.privxagent.plist

Also append the following to the users' .bash_profile file:

# Register SSH_AUTH_SOCK & SSH_AGENT_PID to local environment
# if started by Launchd
if sock=$(launchctl getenv SSH_AUTH_SOCK); then
export SSH_AUTH_SOCK=$sock
fi

if pid=$(launchctl getenv SSH_AGENT_PID); then
export SSH_AGENT_PID=$pid
fi

Alternatively, users may manually start the PrivX agent with:

$ ./privx-agent-unix bash

Add PrivX servers to the agent. To do this, log in to the workstation as the user who will be using native clients (in order to start the agent), then run the following (replace https://privx.example.com with the address of your PrivX server):

$ privx-agent-ctl server probe https://privx.example.com

Unless the PrivX server certificate is trusted on the workstation, you will be presented with additional information, such as the SHA checksums of the certificate.

PrivX server 'https://privx.example.com' certificate is untrusted
Server TLS certificate:
Issuer        DC=com, DC=ssh, DC=fi, DC=hel, OU=QA, CN=MSCA-PKI-TEST2-ROOT-CA
Subject       OU=PrivX Web Server, CN=privx.hel.fi.ssh.com
Serial        2453081971937566630710942289116460769316175891
Not Before    2018-03-28 09:00:15 +0000 UTC
Not After     2028-03-28 09:10:15 +0000 UTC
Fingerprints
SHA1        B5 F3 70 E2 DB 61 56 D9 AC AE 03 4D AE DC 01 4C FB D2 AB C0
SHA256      17 22 63 69 D1 AA 77 34 96 BD B7 90 69 83 E7 30 97 A2 78 10 \
73 5C 93 D0 D6 01 99 5C 04 C5 55 B2

Would you like to add this server to trusted servers? Y/N:

You may ensure that these match to the checksums of the PrivX server certificate, which you can obtain by running the following on the PrivX server:

# openssl x509 -noout -fingerprint -sha1 -in /etc/nginx/ssl/nginx.crt
# openssl x509 -noout -fingerprint -sha256 -in /etc/nginx/ssl/nginx.crt

Enter Y to add the PrivX server.

Log into the workstation as the user for whom native clients have been set up.

Verify that the agent is running with:

$ privx-agent-ctl status

The command should return a message similar to the following:

PrivX SSH Agent Status
PrivX Server          https://privx.example.com
Login status          logged out

If necessary, you can manually start the PrivX agent with:

$ ./privx-agent-unix bash

Via the terminal, authenticate against PrivX using your PrivX credentials. For example (replace username with your PrivX user name):

$ privx-agent-ctl login username

You may verify your login status with:

$ privx-agent-ctl status

After entering your PrivX credentials correctly, your native SSH clients (such as ssh) will authenticate connections via PrivX. For a list of valid connection targets, run:

$ privx-agent-ctl target list

Accessible targets and granting roles:

bilberry
alice@192.0.2.144:222           Example Role 01
...

You could then connect to one of the listed targets. In this example, by running:

$ alice@10.1.55.144 -p 222

Obtain the following, required for configuring native clients:

Extract the PrivX agents to the workstation. Navigate to the extracted folder, and in its windows-386 folder, run the privx-agent-windows.msi file to install the PrivX agent.

Start the PrivX agent in Start Menu→SSH Communications Security→PrivX Windows Agent.

	Tip
	For easier access to the agent, you can pin the PrivX Windows Agent to Start, taskbar, or Quick Launch Menu.

Configure the agent to connect to PrivX: In the system tray, right click the PrivX icon and then select Settings.

Enter the PrivX server URL. To verify the connection, click Test.

	Note
	If the PrivX server is using an untrusted TLS certificate, you need to check that the certificate details are valid. Click View to open the Certificate Properties. Check the certificate details. You do not need to install the certificate to the system.

Click OK to save your settings.

Log in to PrivX server by right clicking the PrivX Agent tray icon and clicking Login. Log in using your PrivX username and password. Complete multi-factor authentication if required.

	Note
	If PrivX-agent login fails with Failed: Login through web UI is required, then please use a web browser to login in to PrivX GUI and complete MFA setup as described in the section called “Multi-Factor Authentication for PrivX Users”.

To connect to a target host, right click PrivX agent tray icon, and click Connections.

Provide the following connection settings:

After providing the connection settings, click Connect. Alternatively, you can directly use your SSH client for connecting.

To exit the agent, right click on the PrivX Agent tray icon and click Exit.

On all your PrivX servers, enable the forwarder_enabled setting in /opt/privx/etc/ssh-proxy.toml

And restart PrivX services to apply the changes:

systemctl restart privx

	Caution
	The forwarder relays all the data it receives (not just the native-client connections), and should not be enabled in high-security networks.

Session recording must be disabled on hosts that are to be accessed using proxied native-client connections. For more detailed instructions about toggling session recording, see the section called “Session Recording Setup”.

(Optional) To simplify native-client commands, specify the required connection parameters in the users' client configuration (typically at /etc/ssh/ssh_config or ~/.ssh/config). You can do this using Host blocks that at least specify:

For example:

Host bilberry
HostName example-extender/bilberry.example.com
ProxyCommand privx-nc -x $PRIVX_AGENT_PROXY %h %p

As the native-client user, start the PrivX agent (if not already started) and use it to log into PrivX.

If you have specified the required parameters in your SSH-client configuration, you can connect simply using the appropriate Host block. For example:

$ ssh target-user@bilberry

$ sftp target-user@bilberry

$ scp source/file/path target-user@bilberry:/target/file/path

Otherwise, you must additionally provide the ProxyCommand and the name of the PrivX Extender, similar to the following:

$ ssh -o "ProxyCommand privx-nc -x $PRIVX_AGENT_PROXY %h %p" \
target-user@example-extender/bilberry.example.com

$ sftp -o "ProxyCommand privx-nc -x $PRIVX_AGENT_PROXY %h %p" \
target-user@example-extender/bilberry.example.com

$ scp -o "ProxyCommand privx-nc -x $PRIVX_AGENT_PROXY example-extender/%h %p"\
source/file/path target-user@bilberry.example.com:/target/file/path