This chapter provides instructions for customizing PrivX components to suit the needs of your environment.

SSL/TLS Security

This section describes the configuration topics related to SSL/TLS security.

Setting Up a Trusted Server Certificate

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).


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.

  1. 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:


    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 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.

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


    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
  3. 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/ update-trust /path/to/ca_chain.crt


    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. 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.

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

    # systemctl restart nginx
    # systemctl restart privx

Setting Up a Trusted CA Certificate

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.


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:

  1. 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
  2. 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.

  3. 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 
  4. 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
  5. 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.

Allowed SSL Protocols and Ciphers for GUI Connections

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;

tcp_nodelay on;

After any adjustments to Nginx settings, restart the Nginx web server to apply the changes:

# systemctl restart nginx

Rotating Encryption Keys

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:

  1. Run the rotation script from a PrivX server in the deployment:

    # /opt/privx/scripts/

    The old PrivX CA certificates are deleted and new ones are generated. The script will then restart PrivX.

  2. 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:

      # --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:

  1. Run the rotation command on a PrivX server in the deployment:

    # /opt/privx/bin/keyvault-tool rotate-auth-keys

    This generates new authentication keys.

  2. On all PrivX servers, restart the PrivX services:

    # systemctl restart privx


PrivX-user logins may fail during the time between authentication-key generation and restarting PrivX services.

PrivX Log Settings

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:

  1. Edit /opt/privx/scripts/<microservice_name>.sh (replace <microservice_name> with the name of the microservice) and set the SSH_TRACE parameter:

    cmd="SSH_LOG_LEVEL=DEBUG SSH_TRACE=6 /opt/privx/bin/auth"
  2. By default, the system-logging service rsyslog is configured to show INFO-level messages only, which blocks DEBUG messages. To configure rsyslog to show DEBUG-level messages, find the following line in the rsyslog 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
  3. Restart the privx service to apply any changes to configuration files:

    # systemctl restart privx

PrivX-Extender Configuration

This section describes configuration topics for PrivX Extenders.

Configuring Extender Log Location

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:


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

Proxying Native-Client Connections

To allow proxying native-client connections via PrivX Extenders:

  1. 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


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

  2. 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”.

  3. (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:

    • The target HostName in extender-name/target-host-address format.

    • The ProxyCommand: privx-nc -x $PRIVX_AGENT_PROXY %h %p

    For example:

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

After setup, you can connect to target hosts as follows:

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

  2. 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" \
    $ sftp -o "ProxyCommand privx-nc -x $PRIVX_AGENT_PROXY %h %p" \
    $ scp -o "ProxyCommand privx-nc -x $PRIVX_AGENT_PROXY example-extender/%h %p"\

PrivX-Carrier and Web Proxy Configuration

This section describes configuration topics for the PrivX Carrier and PrivX Web Proxy.

Allowing HTTP/HTTPS Targets at Unusual Ports

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:

  1. Verify and set the allowed target ports on your Web Proxy machines in /etc/squid/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 other acl 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 other acl 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.

Changing Web Proxy Port Numbers

To change the Web Proxy ports, you need to edit the following:


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 proxy ports for HTTP and HTTPS. The port numbers and Carrier host IP \
    address should match the Squid configuration file in /etc/squid/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 /etc/squid/squid.conf to match the port numbers you entered previously:

    http_port 18080
    http_port 18443 ssl-bump cert=/opt/privx/squid_cert/squid.crt \
    key=/opt/privx/squid_cert/squid.key generate-host-certificates=on \

    After 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

Setting Custom Instance Names

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.

Custom instance name in the GUI header and audit events

Figure 5.1. Custom instance name in the GUI header and audit events

To set a custom instance name for a PrivX server:

  1. Gain root-terminal access to the PrivX server.

  2. Edit the shared configuration at:


    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.

  3. Restart the PrivX services to apply the changes:

    # systemctl restart privx

Resetting the Superuser Password

If you have forgotten the PrivX superuser's password, you can reset it as follows:

  1. 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>
  2. Access the PrivX database using psql with write permissions. Change the superuser password (Replace encrypted_password and superuser 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.