Table of Contents
This chapter provides instructions for customizing PrivX components to suit the needs of your environment.
This section describes the configuration topics related to SSL/TLS security.
Freshly set-up PrivX servers are equipped with self-signed server certificates. For production deployments we recommend replacing the self-signed server certificate with a server certificate issued by a trusted Certificate Authority (CA).
Note
The self-signed server certificate should only be trusted in evaluation deployments. In production environments, we strongly recommend that you acquire and use a trusted server certificate. You can obtain a trusted server certificate by enrolling the certificate-signing request with your corporate CA.
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:
The server certificate.
The CA-certificate chain of the CA itself.
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
PrivX Authorizer issues access certificates using its own CA, which is self-signed by default. For production deployments we recommend replacing the Authorizer CA with one signed by a trusted certificate authority.
Note
The following procedures use <key_id>
and <cert_id>
to substitute for PrivX-CA-key ID and the Authorizer-certificate ID respectively. Be careful not to mix them up.
To set up PrivX Authorizer with a trusted CA certificate:
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.csrThis 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:
keyUsage must include:
Digital Signature, Key Agreement, Certificate Sign, CRL Sign
basicConstraints must be:
CA:TRUE, pathlen:0
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, replaceprivx-im-ca.crt
with the path to the signed certificate):# /opt/privx/bin/cert-tool -command import -type authorizer-ca \ -key
<key_id>
-inprivx-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.
Connections to the PrivX GUI are secured using TLS. The allowed SSL protocols and SSL ciphers may be adjusted if some browsers cannot establish connections to the PrivX GUI, or if you want to harden the PrivX instance.
The allowed SSL protocols and SSL ciphers are defined in the Nginx configuration file /etc/nginx/conf.d/privx.conf
, by the parameters ssl_protocols
and ssl_ciphers
respectively, similarly to the following:
...
http {
sendfile on;
server_tokens off;
ssl_protocols TLSv1.2;
ssl_ciphers 'AESGCM+EECDH:AESGCM+EDH:AES+EECDH: ... ';
tcp_nodelay on;
...
After any adjustments to Nginx settings, restart the Nginx web server to apply the changes:
# systemctl restart nginx
This section provides instructions for rotating PrivX cryptographic keys, which should be done regularly for improved security. You can rotate the following keys:
PrivX CA keys, which issue certificates for certificate-based access.
Authentication keys, which issue PrivX-user access and session tokens.
To rotate PrivX CA keys:
Run the rotation script from a PrivX server in the deployment:
# /opt/privx/scripts/rotate_privx_ca.sh
The old PrivX CA certificates are deleted and new ones are generated. The script will then restart PrivX.
On hosts with certificate authentication enabled, configure trust for the new PrivX CA. To do this:
On target hosts with certificate-based SSH authentication: run the host-deployment script with the
--rotate-ca
option:# deploy.py --rotate-ca
Alternatively, manually configure the host to trust the new PrivX CA as described in the section called “Trusting PrivX Certificates”.
If you use certificate-based RDP authentication: Set up trust for the new PrivX CA as described in the section called “Steps for RDP Certificate-Authentication-Setup”.
To rotate PrivX authentication keys:
Run the rotation command on a PrivX server in the deployment:
# /opt/privx/bin/keyvault-tool rotate-auth-keys
This generates new authentication keys.
On all PrivX servers, restart the PrivX services:
# systemctl restart privx
Note
PrivX-user logins may fail during the time between authentication-key generation and restarting PrivX services.
By default, regular and audit events are logged to syslog. Audit events use the namespace SSH-PRIVX-AUDIT
, and other (info/debug/error) messages use the namespace SSH_PRIVX
.
You can adjust the locations to which PrivX writes logs, and the log level of each microservice.
The log locations are configured by settings defined in /opt/privx/etc/shared-config.toml
# Should we send PrivX system events to logs under /var/log/privx # send_regular_events_to_stdout = false send_regular_events_to_stdout = false # Should we send PrivX audit events to syslog # send_regular_events_to_syslog = true send_audit_events_to_syslog = true # Should we send PrivX system events to syslog # send_regular_events_to_syslog = true send_regular_events_to_syslog = true
To enable debug output for a microservice:
Edit /opt/privx/scripts/<microservice_name>.sh (replace
<microservice_name>
with the name of the microservice) and set the SSH_TRACE parameter:dir="/opt/privx/bin" cmd="SSH_LOG_LEVEL=DEBUG SSH_TRACE=6 /opt/privx/bin/auth" user="privx"
By default, the system-logging service
rsyslog
is configured to show INFO-level messages only, which blocks DEBUG messages. To configurersyslog
to show DEBUG-level messages, find the following line in thersyslog
configuration file,/etc/rsyslog.conf
:*.info;mail.none;authpriv.none;cron.none /var/log/messages
And change it to, for example:
*.debug;mail.none;authpriv.none;cron.none /var/log/messages
Restart
rsyslog
to apply the changes:systemctl restart rsyslog
Restart the privx service to apply any changes to configuration files:
# systemctl restart privx
This section describes configuration topics for PrivX Extenders.
By default PrivX Extender logs info and errors to /var/log/privx/privx-extender.log
If you want to enable logging to syslog, specify the rsyslog address and protocol in /opt/privx/etc/extender-config.toml
, similar to the following:
syslog_protocol="tcp" syslog_address="localhost:514"
Restart PrivX Extender to apply the changes. In addition make sure rsyslog is enabled on the extender host:
systemctl restart privx-extender systemctl restart rsyslog
To allow proxying native-client connections via PrivX Extenders:
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 usingHost
blocks that at least specify:The target
HostName
inextender-name/target-host-address
format.The
ProxyCommand
:privx-nc -x $PRIVX_AGENT_PROXY %h %p
For example:
Host
bilberry
HostNameexample-extender/bilberry.example.com
ProxyCommand privx-nc -x $PRIVX_AGENT_PROXY %h %p
After setup, you can connect to target hosts as follows:
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
If you are using a custom load balancer, ensure that its session-affinity cookie (also known as a sticky-session cookie) is accepted by all your PrivX Extenders:
Add the name of the session-affinity cookie to the
known_lb_cookies
setting. The setting is located in the following configuration file on the Extender:/opt/privx/etc/extender-config.toml
Restart the Extender with:
# systemctl restart privx-extender
Note
If your PrivX HA deployment also includes PrivX Carriers and PrivX Web Proxies, configure those to accept your session-affinity cookie as well, as per instructions in the section called “Custom Load-Balancer Support”.
This section describes configuration topics for the PrivX Carrier and PrivX Web Proxy.
This section describes modifying the allowed target ports for PrivX Web Proxies. These instructions assume you to have some familiarity with Squid configuration.
By default PrivX only allows access to HTTP/HTTPS targets running on certain ports. The allowed ports are available toward the start of your Squid configuration file.
To allow access to targets at nonstandard ports:
Verify and set the allowed target ports on your Web-Proxy machines in
/opt/privx/etc/squid.conf
For HTTP and HTTPS targets, ensure the target port is included in the
Safe_ports
list. You can add the target port by adding a similar line immediately after otheracl Safe_ports
directives (replace<target_port>
with the port of your HTTP/HTTPS service):acl
Safe_ports
port<target_port>
Additionally for HTTPS targets, ensure the target port is included in the
SSL_ports
list. You can add the target port by adding a similar line immediately after otheracl SSL_ports
directives (replace<target_port>
with the port of your HTTPS service):acl
SSL_ports
port<target_port>
For example, to allow access to HTTPS target running on port 9443, you would need to add the port to
SSL_ports
:acl SSL_ports port 443 acl SSL_ports port 9443 acl Safe_ports port 80 # http acl Safe_ports port 21 # ftp acl Safe_ports port 443 # https acl Safe_ports port 1025-65535 # unregistered ports acl CONNECT method CONNECT
Port 9443 is already included in
Safe_ports
by default.Restart the
squid
service to apply the changes:# systemctl restart squid
You can control access to specific websites for specific PrivX roles. With this you can prevent users from accessing arbitrary websites by entering URLs, and via links on web targets.
Role-based access control is configured via Squid on PrivX Web Proxies. These instructions assume you have some familiarity with Squid configuration. This section provides some basic examples about access control. For more comprehensive descriptions about Squid's access-control settings, see their vendor documentation at https://wiki.squid-cache.org/SquidFaq/SquidAcl
To control access for a PrivX role, you will typically need to specify the following in the Squid configuration:
Define an
acl
matching the members of the PrivX role. You can determine PrivX users' roles from theirUser-Agent
header.Define
acl
s for the restricted address(es).Define rules allowing/denying matching members to access restricted address(es).
For example, to only allow privx-admin
members to access while denying all other PrivX users access to www.example.com, perform the following on all your PrivX Web Proxies:
Add rules like the following to the Squid configuration at
/opt/privx/etc/squid.conf
# Match all PrivX users belonging to the privx-admin role acl is_privx_admin req_header User-Agent Role\=privx-admin # Define restricted address(es) acl restricted_to_certain_privx_roles ssl::server_name www.example.com # Allow privx-admins to access restricted address(es) http_access allow is_privx_admin restricted_to_certain_privx_roles # Deny others access to restricted address(es) http_access deny restricted_to_certain_privx_roles
Restart the
squid
service to apply the changes:# systemctl restart squid
Configure trust for any web targets that use self-signed certificates, for the following benefits:
PrivX users connecting to web targets no longer receive security warnings about insecure server certificates.
Support websocket connections from the web target.
Note
We recommend setting up web targets before configuring trust for them. For more information about setting up targets in PrivX, see the section called “Setting up Known Targets”.
To trust a web target:
On your PrivX Web Proxy, add the CA-certificate chain of the web target to the system trust anchors: Save the CA-certificate-chain file under
/etc/pki/ca-trust/source/anchors/
Then run:
# update-ca-trust extract
Restart the Squid service to apply the changes:
# systemctl restart squid
(Optional) Perform this step if you need to enable websocket connections from the web target.
On your PrivX Carrier, add the CA-certificate chain of the web target to your PrivX-Carrier configuration at:
/opt/privx/etc/carrier-config.toml
Then restart the Carrier and Docker services to apply the changes:
# systemctl restart privx-carrier # systemctl restart docker
To change the Web Proxy ports, you need to edit the following:
Note
In the following examples, replace the port numbers 18080
and 18443
with the ports you want to use.
On the Carrier host, change the ports in the
/opt/privx/etc/carrier-container.toml
file:[web_container] # Web proxy ports for HTTP and HTTPS. The port numbers and Carrier host IP \ address should match the Squid configuration file in /opt/privx/etc/squid.conf # Proxy server IP address is configured via PrivX UI. http_proxy_port =
18080
https_proxy_port =18443
After editing the file, restart the Carrier service:
# systemctl restart privx-carrier
On the Web Proxy host, edit the Squid configuration file in
/opt/privx/etc/squid.conf
to match the port numbers you entered previously:http_port
18080
http_port18443
ssl-bump cert=/opt/privx/squid_cert/squid.crt \ key=/opt/privx/squid_cert/squid.key generate-host-certificates=on \ dynamic_cert_mem_cache_size=4MBAfter editing the file, restart the Web Proxy and Squid services:
# systemctl restart privx-web-proxy squid
The Web Proxy host's firewall should allow access to the ports you have specified. Run:
# firewall-cmd --permanent --add-port=
18443
/tcp # firewall-cmd --permanent --add-port=18080
/tcp # firewall-cmd --reload
If you are using a custom load balancer in a PrivX HA deployment, you will need to ensure that its session-affinity cookie (also known as a sticky-session cookie) is accepted by all your PrivX Carriers and PrivX Web-Proxies:
Add the name of the session-affinity cookie to the
known_lb_cookies
setting. The setting is located in the following configuration files, for Carriers and Web-Proxies respectively:/opt/privx/etc/carrier-config.toml
/opt/privx/etc/web-proxy-config.toml
Restart the Carrier and Web-Proxy services. On your Carriers, run:
# systemctl restart privx-carrier
And on your Web-Proxies, run:
# systemctl restart privx-web-proxy
Note
If your PrivX HA deployment also includes Extenders, configure those to accept your session-affinity cookie as well, according to the instructions at the section called “Custom Load-Balancer Support”.
You can automate PrivX administrative tasks via the PrivX API.
You can use any RESTful client with OAuth2 support to access the PrivX API, such as curl
. You may also use the PrivX SDK for Python available at https://github.com/SSHcom/privx-sdk-for-python
High-level setup steps include:
Providing role-based permissions for the API client.
OAuth2 authentication with the API client.
First define the permissions of the API client:
Create an API-client entry in PrivX.
In the PrivX GUI, go to Settings→Deployment→Integrate with PrivX using API clients, then click Add API Client.
Provide a Name for the API client. To provide permissions, also add some Roles for the API client.
Click Save to save your API client.
Back on the API clients page, expand Credentials of your API client. These are required later for authentication.
After creating your API-client entry, authenticate using your API client as follows:
Provide your API-client Credentials to the
/auth/api/v1/oauth/token
endpoint. For example, usingcurl
(replace<privx.example.com>
with your PrivX address, replace<oauth_client_id>, <oauth_client_secret>, <api_client_id>, and <api_client_secret>
with the respective values from your API-client Credentials):$ curl -X POST \ https://
<privx.example.com>
/auth/api/v1/oauth/token \ -u<oauth_client_id>
:<oauth_client_secret>
\ --data-urlencode 'grant_type=password' \ --data-urlencode 'username=<api_client_id>
' \ --data-urlencode 'password=<api_client_secret>
'Note
Unlike other PrivX-API endpoints, the
/auth/api/v1/oauth/token
endpoint only accepts content in application/x-www-form-urlencoded format (not in application/JSON format).Upon successful authentication you will receive an access token in JSON format, similar to the following:
{ "access_token": "
<access_token>
", "token_type": "bearer", "expires_in": 1800You can now use the access token to perform PrivX actions using other endpoints. For example, to list all hosts in PrivX:
$ curl -X GET \ -H "Authorization: Bearer
<access_token>
" \ https://<privx.example.com>
/host-store/api/v1/hosts
You can set a custom instance name to better distinguish between multiple PrivX servers. Custom instance names are displayed in the PrivX GUI, and added to the audit events generated from the server.
To set a custom instance name for a PrivX server:
Gain root-terminal access to the PrivX server.
Edit the shared configuration at:
/opt/privx/etc/shared-config.toml
In this file, set the custom instance name with
privx_instance_name
. For example:# A custom PrivX instance name to be shown in the header privx_instance_name = "
PrivX Example Deployment 01
"Save your changes to the file.
Restart the PrivX services to apply the changes:
# systemctl restart privx

To show messages to PrivX users upon login, configure the privx_disclaimer
setting in /opt/privx/etc/shared-config.toml
In the
privx_disclaimer
setting, specify the disclaimer message in JSON format, similar to the following:privx_disclaimer = '''
[
{
title: 'Disclaimer',
text: 'Disclaimer message',
accept: 'I have read and agree to the terms and conditions',
mode: 'float', // float/local/popup
acceptable: true,
closeable: false
}
]
'''You can customize the disclaimer content and visibility with the following parameters:
title: Title for the disclaimer.
text: Message shown in the disclaimer.
accept: Text for the checkbox that allows users to accept the disclaimer.
mode: How the disclaimer looks on the page. Choices are
float
,local
, andpopup
acceptable: Allow users to accept and close the disclaimer. Can be
true
orfalse
.After a user accepts the disclaimer it will not be displayed on subsequent logins, until users clear browser cookies. Unless
closeable
is also set totrue
, the user must accept the disclaimer to proceed.closeable: Allow users to close the disclaimer without accepting it. Can be
true
orfalse
.Closed disclaimers are redisplayed on subsequent logins.
Restart PrivX services to apply the changes:
# systemctl restart privx
If you have forgotten the PrivX superuser's password, you can reset it as follows:
On a PrivX server, obtain an encrypted version of your new password (replace
example_password
with your new password):# /opt/privx/bin/keyvault-tool bcrypt
<example_password>
Access the PrivX database using
psql
with write permissions. Change the superuser password (Replaceencrypted_password
andsuperuser
with the encrypted password and your superuser-account name respectively):# UPDATE localuser SET password='
encrypted_password
' WHERE username='superuser
'You can now log into PrivX as superuser using the new password.