Skip to main content
Version: v45

Setting Up PrivX Components

This article describes setting up and maintaining PrivX components. To get started with PrivX, set up at least one PrivX server.

Setting Up PrivX Servers​

PrivX servers provide PrivX services, such as the PrivX Web UI and certificate-based authentication services.

Preparing for Installation​

Before installing PrivX, please update your host to ensure the latest packages:

yum update

If your system uses dnf instead of yum to manage packages, run:

dnf update

Installing PrivX Packages​

To set up a PrivX server:

  1. Set up repositories for downloading PrivX packages and dependencies.

    • On Red Hat/Rocky Linux 9:

      yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm
      yum install postgresql-server # or postgresql if using an external DB
      yum install firewalld
      dnf module enable postgresql:16
      yum install postgresql-server # or postgresql if using external DB
      rpm --import https://product-repository.ssh.com/info.fi-ssh.com-pubkey.asc
      curl https://product-repository.ssh.com/rhel9/ssh-products.repo -o /etc/yum.repos.d/ssh-products.repo

    • On Red Hat/Rocky Linux 8:

      yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
      yum install epel-release
      yum install firewalld
      dnf module enable postgresql:16
      yum install postgresql-server # or postgresql if using external DB
      rpm --import https://product-repository.ssh.com/info.fi-ssh.com-pubkey.asc
      curl https://product-repository.ssh.com/rhel8/ssh-products.repo -o /etc/yum.repos.d/ssh-products.repo

    • On Amazon Linux 2023:

      dnf install postgresql15-server # or postgresql15 if using external DB
      dnf install libxcrypt-compat firewalld
      rpm --import https://product-repository.ssh.com/info.fi-ssh.com-pubkey.asc
      curl https://product-repository.ssh.com/rhel8/ssh-products.repo -o /etc/yum.repos.d/ssh-products.repo

  2. Install the latest PrivX packages with:

    yum install PrivX

    The PrivX application binaries are saved to the /opt/privx/bin/ directory. Configuration files are located in /opt/privx/etc/, and utility scripts can be found in /opt/privx/scripts/.

  3. To automate PrivX configuration, you may define post-installation settings using environment variables. The post-installation script will skip any prompts for values that are already set via environment variables.

    A list of supported environment variables is available at /opt/privx/scripts/postinstall_env.

    To export the variables, run:

    source /opt/privx/scripts/postinstall_env

  4. Run the post-installation script to configure the server:

    /opt/privx/scripts/postinstall.sh

    Unless defined via environment variables, the post-installation script will prompt you for the following settings:

    • PKCS#11 key vault settings: Enable and configure this only if using an external Hardware Security Module (HSM). For detailed instructions, refer to the HSM setup articles.
    • Number of load balancers in front of PrivX servers: Set to 0 for single-server deployments.
    • NTP server address: Used for time synchronization.
    • DNS and IP address(es) of the server.
    • External database settings (if applicable):
      • Database address (IP or FQDN), e.g., database.example.com
      • Arbitrary name for the PrivX database
      • Arbitrary username and password for the PrivX database user
      • Password for the PostgreSQL postgres user
      • Notification back-end: select the existing PostgreSQL database
        note

        For an unsupervised installation with a pre-created PostgreSQL DB and a pre-created PrivX DB user, set the following environment variables before running the post-installation script:

        export DB_EXTERNAL_CREATE_PSQL_USER=false
        export DB_EXTERNAL_CREATE_PSQL_DATABASE=false

        Otherwise, the installer creates the DB resources and prompts for PostgreSQL administrative credentials.

    • Initial superuser credentials: Required to create the first admin account.
    note

    If you encounter an "unable to open pg_trgm.control" error, ensure that the pg_trgm PostgreSQL extension is installed. Learn more here.

  5. Install the PrivX license to enable product functionality.

    Open your browser and navigate to the PrivX web interface (replace privx.example.com with your server's FQDN or IP address) at https://privx.example.com/.

    Log in using your superuser credentials.

    In the PrivX UI, go to Settings→License. Under Online license update, enter your license code and click Update. PrivX will automatically contact the license server to retrieve and apply your license. Make sure your system clock is correctly set to allow license activation.

    For more details on license types and activation management, see License Management.

    note

    PrivX licenses allow a limited number of activations. If you deactivate any PrivX server, be sure to release the license activation according to the instructions in License Management.

    Without a valid license, PrivX will not allow you to add hosts or establish SSH, RDP, or Web connections.

You have now successfully set up a PrivX server.

To verify that all PrivX microservices are running correctly, visit the status page (replace privx.example.com with your server's FQDN or IP address):

https://privx.example.com/status.html

To prevent unintentional PrivX upgrades, you can disable the PrivX repository until you are ready to update. For instructions, see Disable PrivX Repository.

note

In large-scale deployments, PrivX can generate substantial log data. To avoid running out of disk space, we recommend configuring log rotation for both syslog and PrivX microservice logs.

You can also set up Disk-Space Alerts to be automatically notified when disk usage becomes critical on PrivX servers or components.

Managing TLS Server Certificates​

During installation, PrivX runs init_nginx.sh to generate a TLS server certificate for HTTPS connections to the PrivX Web UI and API. The generated certificate is valid for 200 days.

For production deployments, we recommend replacing the generated certificate with a certificate issued by a trusted certificate authority (CA). For more information, see Trusted Server Certificates.

If you keep the generated certificate, renew it before it expires by rerunning init_nginx.sh. For more information, see Renewing Certificates. For certificates issued by an external CA, arrange renewal with that CA.

Installing PrivX From Downloaded RPM Packages​

Instead of installing PrivX packages from the SSH product repository, you may install the PrivX package manually as follows:

  1. Obtain the PrivX RPM package. The package should be named PrivX-***.x86_64.rpm, where *** represents the product version. See Getting PrivX Software for more information about package download.

  2. Copy the PrivX RPM file to the target server.

  3. Install the PrivX package (replace PrivX-***.x86_64.rpm with the name of your RPM file):

    yum install PrivX-***.x86_64.rpm

Setting Up PrivX Extenders​

PrivX Extenders relay host connections, allowing connections to target hosts that are inaccessible from PrivX servers.

To set up PrivX Extender:

  1. Obtain an Extender configuration. Either:

    • Create a new Extender configuration, or
    • Download an existing Extender configuration.

    You can create and download Extender configurations via the PrivX Web UI at Administration → Deployment → Deploy PrivX VPC/VPN Extenders. Note that there are separate packages for FIPS and non-FIPS Extenders.

    note

    In Extender configurations, Addresses and Subnets should only be set after you have verified successful connections via the Extender.

    If you plan to set up multiple Extenders for high-availability (HA), identify the HA clusters using the Routing prefix as described in High-Availability Deployment.

  2. Install the PrivX Extender software on the Extender host in either of the following ways:
    Install from the SSH product repository. To do this, set up the repository and install the software package:

    • On Red Hat or Rocky Linux 8:

      sudo rpm --import https://product-repository.ssh.com/info.fi-ssh.com-pubkey.asc
      sudo curl https://product-repository.ssh.com/rhel8/ssh-products.repo -o /etc/yum.repos.d/ssh-products.repo
      sudo yum install firewalld
      sudo yum install PrivX-Extender

    • On Red Hat or Rocky Linux 9 with FIPS:

      sudo rpm --import https://product-repository.ssh.com/info.fi-ssh.com-pubkey.asc
      sudo curl https://product-repository.ssh.com/rhel9/ssh-products.repo -o /etc/yum.repos.d/ssh-products.repo
      sudo yum install firewalld
      sudo yum install PrivX-Extender-FIPS

    • On Red Hat or Rocky Linux 9 without FIPS:

      sudo rpm --import https://product-repository.ssh.com/info.fi-ssh.com-pubkey.asc
      sudo curl https://product-repository.ssh.com/rhel9/ssh-products.repo -o /etc/yum.repos.d/ssh-products.repo
      sudo yum install firewalld
      sudo yum install PrivX-Extender

    • Alternatively, you may manually obtain the RPM. To do this, go to Settings→Deployment→Deploy PrivX VPC/VPN Extenders and click Download PrivX Extender. Then copy the rpm to the Extender host and install it with (replace /path/to/PrivX-Extender.*.rpm with the path to which you placed the Extender package):

      yum install /path/to/PrivX-Extender-*.rpm

  3. Save the Extender configuration to the following path on the Extender host:
    /opt/privx/etc/extender-config.toml

  4. Run postinstall to complete the setup:

    sudo /opt/privx/scripts/extender-postinstall.sh

    The PrivX Extender is now set up. You may verify back on the Settings → Deployment → Deploy PrivX VPC/VPN Extenders page that the Status is Registered.

    If the Extender failed to register to PrivX, you may find additional troubleshooting information from the Extender host at /var/log/privx/privx-extender.log

  5. Configure the target host(s) for access via Extenders. For more information about accessing targets through Extenders, see Proxying Connection.

Setting Up PrivX Carriers and Web Proxies​

This section provides setup instructions for PrivX Carriers and Web Proxies, which allow connecting to HTTP/HTTPS targets. The high-level workflow involves:

  1. Create or download a web-access-gateway configuration.
  2. Set up a PrivX Carrier.
  3. Set up a PrivX Web Proxy.
caution

For best system security, you should set up Carrier and Web Proxy components on separate hosts.

Creating and Downloading Web Access Gateway Configurations​

  1. In the PrivX Web UI, navigate to Settings → Deployment → Deploy PrivX web-access gateways.

  2. Obtain a web access gateway configuration. Either:

    • Create a new configuration, or
    • Download an existing configuration.

    You can create and download web access gateway configurations via the PrivX Web UI at Administration → Deployment → Deploy PrivX web-access gateways.

    In web access gateway configurations, Addresses and Subnets should only be set after you have verified successful connections via the Carrier and Web Proxy.

    If you plan to set up multiple Carriers and Web Proxies for high-availability (HA), identify the HA clusters using the Routing prefix as described in High-Availability Deployment.

    note

    The Web Proxy address must be a valid IP or DNS address without schema headers and port numbers, pointing to the address of the server where the Web Proxy will be installed to. Loopback addresses are not allowed.

  3. Download the configurations (required later for setting up Carriers and Web Proxies). To do this, click next to your configuration, then click Download Carrier Config and Download Proxy Config.

Setting Up PrivX Carriers​

  1. Install the prerequisites and the Carrier package:

    • On Red Hat 9 or Rocky Linux 9:

      sudo yum config-manager --add-repo=https://download.docker.com/linux/centos/docker-ce.repo
      sudo yum install docker-ce
      sudo rpm --import https://product-repository.ssh.com/info.fi-ssh.com-pubkey.asc
      sudo curl https://product-repository.ssh.com/rhel9/ssh-products.repo -o /etc/yum.repos.d/ssh-products.repo
      sudo yum install PrivX-Carrier

    • On Red Hat 8 or Rocky Linux 8:

      sudo yum config-manager --add-repo=https://download.docker.com/linux/centos/docker-ce.repo
      sudo yum install docker-ce
      sudo rpm --import https://product-repository.ssh.com/info.fi-ssh.com-pubkey.asc
      sudo curl https://product-repository.ssh.com/rhel8/ssh-products.repo -o /etc/yum.repos.d/ssh-products.repo
      sudo yum install PrivX-Carrier

    • On Amazon Linux 2023:

      sudo yum install docker
      sudo rpm --import https://product-repository.ssh.com/info.fi-ssh.com-pubkey.asc
      sudo curl https://product-repository.ssh.com/rhel8/ssh-products.repo -o /etc/yum.repos.d/ssh-products.repo
      sudo yum install PrivX-Carrier
note

You may install the Carrier package via RPM obtained from Getting PrivX software (instead of SSH repositories). This can be useful in environments without Internet access. Note that you will still need to install the prerequisites first.

note

If you are upgrading from Carrier 34 or older version and want to switch Docker to Podman, you can do this by deleting the privx user on the Carrier host first. After that, follow the regular install procedure and run carrier-postinstall.sh afterwards.

  1. Copy your Carrier-configuration file to your Carrier machine, to the following path:
    /opt/privx/etc/carrier-config.toml

  2. To finalize setup and register the Carrier with PrivX, run:

    sudo /opt/privx/scripts/carrier-postinstall.sh
note

The Carrier machine must be able to connect to port 443 on the PrivX server.

Setting Up PrivX Web Proxies​

  1. Install prerequisites and the Web Proxy package:

    • On Red Hat 9 or Rocky Linux 9:

      sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm
      sudo rpm --import https://product-repository.ssh.com/info.fi-ssh.com-pubkey.asc
      sudo curl https://product-repository.ssh.com/rhel9/ssh-products.repo -o /etc/yum.repos.d/ssh-products.repo
      sudo yum install firewalld
      sudo yum install PrivX-Web-Proxy

    • On Red Hat 8 or Rocky Linux 8:

      sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
      sudo rpm --import https://product-repository.ssh.com/info.fi-ssh.com-pubkey.asc
      sudo curl https://product-repository.ssh.com/rhel8/ssh-products.repo -o /etc/yum.repos.d/ssh-products.repo
      sudo yum install firewalld
      sudo yum install PrivX-Web-Proxy
    note

    You may install the Web-Proxy package via RPM obtained from Get PrivX software (instead of SSH repositories). This can be useful in environments without Internet access. Note that you will still need to install the prerequisites first.

  2. Copy the Web-Proxy configuration file to the machine, to the following location:
    /opt/privx/etc/web-proxy-config.toml

  3. Allow the Carrier host to access the Web-Proxy host (ports 18080, 18443 and 18444):

    sudo firewall-cmd --permanent --add-port=18080/tcp
    sudo firewall-cmd --permanent --add-port=18443/tcp
    sudo firewall-cmd --permanent --add-port=18444/tcp
    sudo firewall-cmd --reload

  4. To finalize setup and register the Web Proxy with PrivX, run:

    sudo /opt/privx/scripts/web-proxy-postinstall.sh
note

Make sure the Web-Proxy host is able to connect to port 443 on the PrivX server. The host running the PrivX Carrier must also be able to connect to ports 18080 and 18443 on the Web-Proxy host.

After you have the required Carrier and Web-Proxy components, add target websites as known targets. To do this, go to Settings → Hosts and Add hosts with Web-type services. For more information about configuring Web-type services, see Web Targets.

For advanced configuration of PrivX Carrier and Web Proxy components, see Carrier and Web Proxy Configuration.

Setting Up PrivX Routers​

A PrivX Router is Linux iptables-based component, required for accessing network targets. PrivX Routers are controlled by PrivX and must be placed on the path between the VPN server and the protected targets.

For PrivX Router setup instructions, see PrivX Router Configuration.

Setting Up UEBA Servers​

UEBA Servers allow PrivX to use machine learning to detect potentially anomalous connections. PrivX deployments support up to one UEBA server.

To set up a UEBA Server:

  1. Ensure that your machine satisfies the requirements at User and Entity Behavioural Analytics (UEBA). Particularly, note that the default Docker version included with some OS distributions may need to be upgraded to support UEBA.

  2. Provide the UEBA server details via the PrivX Web UI: At Administration → Deployment → User Behavior Analytics, click Edit and provide at least the UEBA-server address and TLS trust anchor.

    note

    If you do not see Administration → Deployment → User Behavior Analytics option, ensure that your PrivX license allows UEBA. You may enquire more about license details from the SSH licensing team at orders@ssh.com.

    Then on the same page, obtain the UEBA startup script by clicking Download UEBA Server Configuration.

  3. Gain root terminal access to the UEBA server machine. Copy the UEBA startup script to this machine.

  4. Install UEBA-server software with:

    sudo chmod u+x ueba-startup.sh
    sudo ./ueba-startup.sh ueba-tls.crt ueba-tls.key

    In the previous commands, replace example values as follows:

    • ueba-startup.sh - path to the UEBA startup script
    • ueba-tls.crt - path to the UEBA-server TLS certificate
    • ueba-tls.key - path to the UEBA-server TLS key

    After successful setup you may verify the UEBA Server status on the PrivX Web UI Home page, under Service Status.

Page updated on