This chapter provides basic instructions for setting up and maintaining PrivX components.

To get started with PrivX you will need to set up at least one PrivX server as described in the section called “PrivX Server Setup”.

PrivX Server Setup

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

To set up a PrivX server:

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

    Add the EPEL repository:

    • On Red Hat 7:

      # yum install \
      https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
    • On Red Hat 8:

      # yum install \
      https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
    • On CentOS 7 and 8:

      # yum install epel-release

    Then add the PrivX repository:

    • On Red Hat or CentOS 7:

      # rpm --import https://product-repository.ssh.com/info.fi-ssh.com-pubkey.asc
      # curl https://product-repository.ssh.com/ssh-products.repo \
      -o /etc/yum.repos.d/ssh-products.repo
    • On Red Hat or CentOS 8:

      # 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 application binaries are installed to the /opt/privx/bin/ directory. The configuration is installed to /opt/privx/etc/ directory. Utility scripts are found in the /opt/privx/scripts/ directory.

  3. To automate PrivX configuration, you may optionally define post-installation settings using environment variables. The post-installation script skips prompting for any settings found in environment variables.

    Environment variables for the post-installation script are listed in:

    /opt/privx/scripts/postinstall_env

    Export the environment variables with:

    # source /opt/privx/scripts/postinstall_env
  4. Run the post-installation script to configure the server:

    # /opt/privx/scripts/postinstall.sh

    Unless specified in environment variables, you will be prompted for:

    • PKCS #11-keyvault settings. Enable and configure this only if using external HSM. For additional HSM-setup instructions, see the Advanced Deployment articles from https://help.ssh.com/

    • DNS and IP address(es) of the server.

    • Database settings (if using an external database):

      • Address of the database in IP or DNS-name format. For example: database.example.com

      • Arbitrary name for the PrivX database.

      • Arbitrary name and password for the PrivX-database user.

      • Password of the PostgreSQL user postgres.

    • Address and password to the external Redis server (if using an external database).

    • Credentials for the initial superuser account.

  5. Install the PrivX license to enable product functionality. You can do this by browsing to the PrivX GUI located at (replace privx.example.com with the DNS or IP address of the PrivX server):

    https://privx.example.com/

    Log in using the superuser credentials.

    In the GUI, navigate to Settings → License in the PrivX UI, and provide your license code under Online license update. Click Update, PrivX automatically contacts the license server to obtain and install your license.

    Note

    PrivX licenses provide a limited number of activations. When deactivating PrivX servers, also remember to free up activations according to instructions in the section called “Deactivating PrivX Licenses”.

    Unlicensed product does not allow adding hosts nor establishing SSH or RDP connections. For your license to be activated, ensure that the system time is set correctly.

    You have now set up a PrivX server.

  6. You may verify the status of the PrivX microservices on the status page, located at the following address (replace privx.example.com with the DNS or IP address of the PrivX server):

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

Note

Particularly in large production deployments, PrivX may accumulate large amounts of log data over time. We recommend that you configure log rotation for syslog and the microservice logs to prevent PrivX servers from running out of disk space.

Setting Up Optional Components

This section provides setup instructions for optional PrivX components.

PrivX Extender Setup

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

To set up PrivX Extender:

  1. Create a PrivX Extender.

    On Settings→Deployment→Deploy PrivX VPC/VPN Extenders, click Add Extender.

    Provide at least the Extender Name. Addresses and Subnets are optional, and should only be set after you have verified successful connections via the Extender.

    Click Save to create the Extender, and to download the Extender configuration. This file is later required for setting up the Extender host.

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

        # rpm --import https://product-repository.ssh.com/info.fi-ssh.com-pubkey.asc
        # curl https://product-repository.ssh.com/ssh-products.repo \
        -o /etc/yum.repos.d/ssh-products.repo
      • On Red Hat or CentOS 8:

        # 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

      Run:

      # yum install PrivX-Extender
    • To manually obtain the rpm, 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:

    # /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) that are to be accessed via a PrivX Extender. For more information about targets accessible via Extenders, see the section called “Proxying Connections to Hosts”.

PrivX Carrier and Web Proxy Setup

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 a Carrier and Web-Proxy configuration.

  2. Set up a PrivX Carrier.

  3. Set up a PrivX Web Proxy.

First, to create and download the necessary configurations:

  1. In the PrivX GUI navigate to Settings→Deployment→Deploy PrivX web-access gateways.

  2. To create the configurations, click Add Web-Access Gateway. Provide at least the Name and Proxy Address for the configuration.

    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.

To set up a PrivX Carrier:

  1. Ensure the machine has access to docker packages by enabling the required repositories:

    • On Red Hat 7:

      # subscription-manager repos --enable rhel-7-server-extras-rpms
    • On AWS Red-Hat-7 instances:

      # yum-config-manager --enable "Red Hat Enterprise Linux Server 7 Extra(RPMs)"
    • On CentOS 7:

      # yum install epel-release
    • On Red Hat 8 and CentOS 8:

      # yum-config-manager \
      --add-repo=https://download.docker.com/linux/centos/docker-ce.repo
  2. Install the Carrier package in either of the following ways:

    • If the machine has internet access, we recommend setting up and installing packages from the PrivX repository:

      • On Red Hat or CentOS 7:

        # rpm --import https://product-repository.ssh.com/info.fi-ssh.com-pubkey.asc
        # curl https://product-repository.ssh.com/ssh-products.repo \
        -o /etc/yum.repos.d/ssh-products.repo
      • On Red Hat or CentOS 8:

        # 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

      Run:

      # yum install PrivX-Carrier
    • Otherwise, you can obtain the Carrier package from https://help.ssh.com, under the Downloads article. Then install the package with:

      # yum install PrivX-Carrier-*.rpm
  3. Copy your Carrier-configuration file to your Carrier machine, to the following path:

    /opt/privx/etc/carrier-config.toml

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

    # /opt/privx/scripts/carrier-postinstall.sh

    Note

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

To set up a PrivX Web Proxy:

  1. If installing on Red Hat or CentOS 7 or 8, enable the EPEL repository:

    • On Red Hat 7:

      # yum install \
      https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
    • One Red Hat 8:

      # yum install \
      https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
    • On CentOS 7 and 8:

      # yum install epel-release
  2. Install the Web-Proxy package in either of the following ways:

    • If the machine has internet access, we recommend setting up and installing packages from the PrivX repository:

      • On Red Hat or CentOS 7:

        # rpm --import https://product-repository.ssh.com/info.fi-ssh.com-pubkey.asc
        # curl https://product-repository.ssh.com/ssh-products.repo \
        -o /etc/yum.repos.d/ssh-products.repo
      • On Red Hat or CentOS 8:

        # 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

      Run:

      # yum install PrivX-Web-Proxy
    • Otherwise, you can obtain the Web-Proxy package from https://help.ssh.com, under the Downloads article. Then install the package with:

      # yum install PrivX-Web-Proxy-*.rpm
  3. Copy the Web-Proxy configuration file to the machine, to the following location:

    /opt/privx/etc/web-proxy-config.toml

  4. Allow the Carrier host to access the Web-Proxy host (ports 18080 and 18443). You will need to add an access rule to the Squid configuration on the Web-Proxy host, at /etc/squid/squid.conf (replace <carrier_address> with the address of your Carrier host in CIDR format):

    ...
    acl localnet src fc00::/7
    acl localnet src fe80::/10
    acl localnet src <carrier_address>
    ...
  5. To finalize setup and register the Web Proxy with PrivX, run:

    # /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 the section called “Web Targets”.

For advanced configuration of PrivX Carrier and Web Proxy components, see the section called “PrivX-Carrier and Web Proxy Configuration”

PrivX Agent Setup

This section provides instructions for installing PrivX agents, which allow PrivX users to connect using SSH native clients.

Unix Setup

To set up native clients against PrivX for a user on a Unix workstation:

  1. Obtain the PrivX-agent software, available as a zip package at:

    https://info.ssh.com/hubfs/Downloads/Features/Agents/Agents.zip

    Save the zip package to the workstation.

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

    /usr/local/bin/privx-agent-unix
    /usr/local/bin/privx-agent-ctl
    /usr/local/bin/privx-nc

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

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

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

  5. You may verify setup by running:

    $ privx-agent-ctl status

    This should output similarly to the following:

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

MacOS Setup

To set up native clients against PrivX for a user on a MacOS workstation:

  1. Obtain the PrivX-agent software, available as a zip package at:

    https://info.ssh.com/hubfs/Downloads/Features/Agents/Agents.zip

    Save the zip package to the workstation.

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

    /usr/local/bin/privx-agent-unix
    /usr/local/bin/privx-agent-ctl
    /usr/local/bin/privx-agent-start.sh
    /usr/local/bin/privx-nc

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

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

  5. You may verify setup by running:

    $ privx-agent-ctl status

    This should output similarly to the following:

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

Windows Setup

To set up native clients against PrivX for a user on a Windows workstation:

  1. Ensure that the native clients on the workstation are in the system PATH.

  2. Obtain the PrivX-agent software, available as a zip package at:

    https://info.ssh.com/hubfs/Downloads/Features/Agents/Agents.zip

    Save the zip package to the workstation.

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

  4. Start the PrivX agent in Start MenuSSH Communications SecurityPrivX Windows Agent.

    Tip

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

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

    You may verify the PrivX-server certificate:

    1. Click View to open the Certificate Properties.

    2. Check the certificate details. You do not need to install the certificate to the system.

    Click OK to save your settings.

    Note

    If native-client paths change after setup, the PrivX agent has to be restarted to apply these path changes.

PrivX License Management

This section describes the supported licensing methods, and license deactivation.

Ensure that you have a valid PrivX license code for taking PrivX into use. For license-subscription-related enquiries, please contact SSH Communications Security support at privx-sales@ssh.com

Online Licensing

Online licensing is the recommended way to license PrivX. This method is easy to set up, and after setup the license is automatically updated according to your subscription.

For online licensing to work, your PrivX servers must have Internet connectivity for certain operations:

  • Upon initial license activation: PrivX contacts license servers to fetch your license.

  • Upon license renewal: PrivX contacts license servers to automatically fetch your new license.

  • Upon license expiry: PrivX contacts license servers to fetch the grace period associated to your license.

To activate a PrivX license with the online method:

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

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

In online licensing mode, PrivX checks for license updates every 12 hours and automatically installs any new licenses found for your subscription. To trigger an immediate license-update check, click next to the Last refreshed section, then click Refresh.

Note

If you opt to not send product analytics, you may disable internet connectivity while no license updates are available. For more information about analytics, see Appendix C.

Note that if PrivX servers do not have Internet access when their license expires, the license expires immediately without entering grace period.

Deactivating PrivX Licenses

PrivX licenses can be activated only a limited number of times. To free up activations you must first deactivate a license.

To deactivate a PrivX license, go to the Settings→License page. Next to Status, click , then click Deactivate.

High-Availability Deployment

This section provides a high-level description about the components of a high-availability (HA) deployment, along with high-level instructions about setting up a HA deployment.

For fault tolerance and load balancing, you can set up multiple PrivX servers as part of a single PrivX deployment. HA deployments consist of:

  • A load balancer for distributing user connections to PrivX servers. The load balancer should also be responsible for disconnecting dead PrivX servers and adjusting the number of PrivX servers based on system load.

  • Multiple PrivX servers for serving user sessions. More PrivX servers results in better performance and greater fault tolerance. In cloud-based environments, we recommend setting up automatic scaling to add and remove PrivX servers according to system load.

  • System storage consisting of:

    • A PostgreSQL database for storing system data. For greater fault tolerance we recommend setting up database replication, and configuring automatic switchover to secondary database(s).

    • A cache used for synchronizing microservice states. We recommend setting up cache replication for greater fault tolerance.

    • External trail storage (only needed for storing session replays).

PrivX HA Deployment

Figure 3.1. PrivX HA Deployment


To set up a PrivX HA deployment:

  1. Set up system storage. You will at least need to set up a PostgreSQL database and a Redis cache. For production environments we recommend enabling replication and automatic failover for the database and the cache.

    If needed, also set up a secure NAS share used for trail storage. For additional information about trail-storage requirements, see the section called “Session Recording Setup”.

  2. Set up the first PrivX server according to the instructions in the section called “PrivX Server Setup”, with the following in mind:

    • Configure the PrivX server to use the external PostgreSQL database and Redis server.

    • If the PostgreSQL superuser is other than postgres, define the actual PostgreSQL-superuser name in the environment variable PRIVX_POSTGRES_USER for the post-install duration. You may set this (and additional environment variables) in /opt/privx/scripts/postinstall_env as described in the section called “PrivX Server Setup”.

  3. Set up additional PrivX servers by duplicating the initial PrivX server:

    • If using virtual servers: Clone the initial PrivX server and create additional instances from the clone.

      Note

      When cloning an instance in OpenStack or Virtualbox, the machine-id of the virtual server does not change from that of the cloned source. The machine-ids of the cloned virtual servers must be changed manually on each of them, as follows:

      • Remove the cloned servers machine-id by running the following command on it:

        # rm /etc/machine-id
      • Run the following to create a new value for machine-id:

        # systemd-machine-id-setup

      You can check the current machine-id of the virtual server by viewing the file /etc/machine-id .

    • If using physical servers: Create a backup of the initial PrivX server, then restore the backup to additional machines. Manual backup and restore is described in the section called “Manual PrivX-Server Backup and Restore”.

    Note

    Ensure that all PrivX server clocks are synchronized.

    When creating additional servers via cloning or backups, all servers will have the same server and CA certificates. If you want to create unique server certificates for a PrivX server, run the following on the target server:

    # /opt/privx/scripts/init_nginx.sh
  4. Set up a load balancer for the deployment. The load balancer must distribute users to PrivX servers using sticky sessions. If you intend to enable native-client connections via PrivX Bastion, the load balancer must also support TCP load balancing.

    An example configuration for an Nginx load balancer is provided in Appendix A.

  5. Update the trust anchor for PrivX microservices. To do this, run the following command (replace /path/to/load_balancer_ca_chain.crt with the path to the CA chain of your load-balancer certificate):

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

Backing Up and Restoring PrivX Deployments

Back up your PrivX deployment in case of failures. You should at least back up your PrivX deployment before notable maintenance actions (such as system upgrades).

To allow system restore, back up at least the following components:

  • The PrivX database.

  • One PrivX server.

To create a backup of your PrivX Deployment:

  1. If the PrivX database is external, back it up according to your database-vendor instructions.

    In single-server deployments the database is backed up along with your PrivX server.

  2. Back up your PrivX servers.

    • In virtual environments, we recommend creating snapshots of your PrivX servers.

    • In physical environments, manually create and download a PrivX-server backup as described in the section called “Manual PrivX-Server Backup and Restore”. The data on all PrivX servers should be identical, so you only need to do this on one PrivX server.

  3. (Optional) In virtual environments, we recommend creating snapshots of the optional PrivX components as well, allowing you to restore them using snapshots instead of by reinstalling.

To restore a PrivX deployment:

  1. If the PrivX database is external, restore it according to your database-vendor instructions.

  2. Restore your PrivX servers.

    • If using snapshots, restore them now. Remember to ensure afterwards that the system times on your PrivX server(s) are correct.

    • If using manual backups, restore your backup to all your PrivX server(s), as described in the section called “Manual PrivX-Server Backup and Restore”.

  3. Restore any other components in your deployment. If using snapshots, restore them now. Otherwise, reinstall them as described in the section called “Setting Up Optional Components”. Remember to ensure afterwards that the system times on these components is correct.

Manual PrivX-Server Backup and Restore

To manually back up a PrivX server:

  1. Create a backup by running:

    # /opt/privx/scripts/backup.sh

    This creates a backup directory to:

    /var/backups/privx/<hostname>_<date>

    Where <hostname> and <date> are the name of the host and the backup timestamp. A working example of a backup-directory path would be:

    /var/backups/privx/privx_2017-12-31-2350

    Note

    By default, PrivX servers create daily backups. Automatic backups are created under:

    /var/backups/privx/

    If you have configured the server to store its certificates in non-default locations, or to use a non-default local database name. Check and adjust the Default options in backup.sh before running it.

    By default backup.sh backs up:

    • PrivX keyvault at /opt/privx/keyvault

    • PrivX configurations under /opt/privx/etc

    • SSL certificate files located under /etc/pki/CA and /etc/nginx/ssl

    • PrivX-CA trust anchor: files matching privx-*.pem under /etc/pki/ca-trust/course/anchors/

    • Local PostgreSQL database named privx (only if using local databases).

  2. Copy the backup to a secure, external backup location.

To restore a PrivX server from a manual backup, reinstall PrivX and apply the backup files as follows:

  1. Uninstall PrivX-server software according to the instructions in the section called “Uninstalling PrivX”.

  2. Install the PrivX version from which your backups were taken.

  3. Stop all PrivX services to prevent system changes during restore:

    # systemctl stop privx
  4. Restore the PrivX local data. Do this by running (replace /path/to/backup with the path of the backup directory):

    # /opt/privx/scripts/restore.sh /path/to/backup
  5. On all the PrivX servers, run the post-installation script to apply the restored configurations, and to restart the PrivX service:

    # /opt/privx/scripts/postinstall.sh

Upgrading PrivX Deployment

This section provides instructions for upgrading your PrivX deployment.

Note

Before upgrade, we strongly recommend you to create a backup of your PrivX server(s), and of the PrivX database. If upgrade fails, you can restore your old PrivX version from these backups. For more information about backing up and restoring PrivX servers, see the section called “Backing Up and Restoring PrivX Deployments”.

Single-Server-Deployment Upgrade

To upgrade the PrivX server, gain root-terminal access to your PrivX server and run:

# yum install PrivX

The system fetches and sets up the latest PrivX package. Upgrade is complete once the command completes.

High-Availability-Deployment Upgrade

This section describes the requirements for upgrading a high-availability (HA) PrivX deployment. This section also provides steps in which you may upgrade your HA deployment.

When upgrading a HA PrivX deployment, note the following requirements:

  • PrivX servers must not service any users while their PrivX software is being upgraded.

  • Ensure that PrivX servers never write to PrivX databases with different product versions.

    Note

    By default, upgrading the PrivX software also upgrades the connected PrivX database. If you need to postpone automatic database upgrade, set the environment variable SKIP_POSTINSTALL before upgrading the PrivX software package:

    # export SKIP_POSTINSTALL=1

    On PrivX servers upgraded like this, you will later need to run postinstall to finalize upgrade:

    # /opt/privx/scripts/postinstall.sh

One way to upgrade HA deployments is by performing the operations on a duplicate database. This method allows un-upgraded portions of the deployment to run during the procedure. To upgrade a HA deployment in this way:

  1. Duplicate the PrivX database.

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

  2. Upgrade one PrivX server along with the duplicate database:

    1. Disconnect the PrivX server from the load balancer to prevent users from connecting to it.

    2. To prevent database activity, stop the PrivX services:

      # systemctl stop privx
    3. Connect to the duplicate database by providing its connection parameters. You only need to provide those database-connection parameters that differ between the original and the duplicate database.

      • The database-server address and port can be changed in /opt/privx/etc/shared-config.toml, under the [db] section.

      • To change the database name (replace <db_name> with the database name):

        # /opt/privx/bin/keyvault-tool -name db-name \
        -value <db_name> set-passphrase
      • To change the database-user name (replace <db_user with the database-user name):

        # /opt/privx/bin/keyvault-tool -name db-user \
        -value <db_user> set-passphrase
      • To change the password of the database user (replace <db_pwd> with the password):

        # /opt/privx/bin/keyvault-tool -name db-password \
        -value <db_pwd> set-passphrase
    4. Upgrade the PrivX software and the connected database:

      # yum install PrivX
    5. Reconnect the PrivX server to the load balancer.

  3. Set up additional PrivX servers into your upgraded environment:

    1. Duplicate the setup of the already-upgraded PrivX server. In virtual environments, you can clone the upgraded PrivX server.

      In physical environments, you can manually back up the upgraded PrivX server and apply that backup to other machines. For more information about manual PrivX-server backup and restore, see the section called “Manual PrivX-Server Backup and Restore”.

    2. Connect the additional PrivX server to the load balancer.

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

Upgrading Optional Components

PrivX Extenders, Carriers, and Web Proxies can be upgraded after PrivX-server and database upgrade. The typical workflow for upgrading any of these components is:

  1. Install the latest software package.

  2. Run postinstall to complete setup.

The specific steps for each optional component are provided in the following subsections.

Upgrading PrivX Extenders

To upgrade PrivX Extenders, run these steps on all your Extender machines:

  1. Install the latest Extender package in either of the following ways:

    • If the PrivX repository is enabled on the machine. Install the package with:

      # yum install PrivX-Extender
    • Without the PrivX repository, 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
  2. Run postinstall to complete the upgrade:

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

Upgrading PrivX Carriers and PrivX Web Proxies

PrivX Carriers and Web Proxies together enable web connections, and should be upgraded together.

To upgrade PrivX Carriers:

  1. Install the latest Carrier package in either of the following ways:

    • If the PrivX repository is enabled on the machine. Install the package with:

      # yum install PrivX-Carrier
    • Without the PrivX repository, go to Settings→Deployment→Deploy PrivX web access gateways and click Download PrivX Web Access Gateway Components:

      Then copy the rpm to the Carrier host and install it with (replace /path/to/PrivX-Carrier.*.rpm with the path to which you placed the Carrier package):

      # yum install /path/to/PrivX-Carrier-*.rpm
  2. Run postinstall to complete the upgrade:

    # /opt/privx/scripts/carrier-postinstall.sh

To upgrade PrivX Web Proxies:

  1. Install the latest Web-Proxy package in either of the following ways:

    • If the PrivX repository is enabled on the machine. Install the package with:

      # yum install PrivX-Web-Proxy
    • Without the PrivX repository, go to Settings→Deployment→Deploy PrivX web access gateways and click Download PrivX Web Access Gateway Components:

      Then copy the rpm to the Web-Proxy host and install it with (replace /path/to/PrivX-Web-Proxy.*.rpm with the path to which you placed the Web-Proxy package):

      # yum install /path/to/PrivX-Web-Proxy-*.rpm
  2. Run postinstall to complete the upgrade:

    # /opt/privx/scripts/web-proxy-postinstall.sh

Uninstalling PrivX

This section provides steps for completely removing PrivX from a machine. These steps may be used in preparation for PrivX reinstallation.

Note

Before uninstalling PrivX, make sure to deactivate the license to free up activations. For more information about deactivating licenses, see the section called “Deactivating PrivX Licenses”.

To delete all PrivX related data from a PrivX server:

  1. Uninstall the PrivX package:

    # yum erase PrivX
  2. Remove the leftover PrivX installation directory (includes configurations and keyvault data):

    # rm -rf /opt/privx
  3. If using a local database, remove PostgreSQL and its data directory:

    # yum erase postgresql
    # rm -rf /var/lib/pgsql/
  4. Remove Nginx:

    # yum erase nginx

    Also remove the leftover Nginx server configuration and SSL-certificate files:

    # rm -rf /etc/nginx
  5. Finally remove the leftover privx-cert.json-file:

    # rm /tmp/privx-cert.json

Manual PrivX Package Installation

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 PrivX RPM package is a file with a name like the following:

    PrivX-*.x86_64.rpm

    Where * is to be replaced with the product version.

  2. Copy the PrivX RPM to your target server.

  3. Install the PrivX RPM (replace PrivX-*.x86_64.rpm with the path of the PrivX RPM):

    # yum install PrivX-*.x86_64.rpm