SSH.COM PrivX Documentation Hub

Welcome to the SSH.COM PrivX documentation! Here you'll find the PrivX administration manual, use case specific guides as well as API specifications.

Documentation    API Reference

SSH Connections with Native Clients

This section describes how to establish SSH connections with native clients.

Users can connect to target hosts/accounts using the SSH clients installed on their workstations, without needing to use the PrivX GUI. Connections are authenticated against PrivX. For example, if PrivX allows you to access a target account with certificate authentication, your native clients will also connect using certificate authentication without prompting you for target-account credentials.


  • Specify which roles may be used for SSH-native-client connections.

  • Your PrivX license must allow using native client connections.

  • After ugrading PrivX, you may need to re-download the extender-config.toml file for the native client connections to work with via Extenders. For more instructions about extender configuration file, see Setting up PrivX Components.

  • For agent-based connections only:

    • The ​Use with PrivX agent​ option is enabled in the relevant users' roles, at ​Settings→Roles​​.

    • PrivX agent must be set up on the user's workstation. For instructions setting up PrivX agents, see PrivX-Agent Setup.

Connecting via PrivX Bastion

Using native SSH clients, you can connect to targets via PrivX SSH Bastion. By default PrivX SSH Bastion runs on port 2222. PrivX SSH Bastion provides the following connection modes:

  • ​​Interactive​​: Access PrivX Bastion to list and select possible targets.

  • ​​Direct​​: Specify your connection target directly to the native client.

  • Direct using ProxyCommand: Specify your PrivX username via ssh_config.



PrivX-Bastion connections are verified against the PrivX-Bastion host key. You may verify and install these host keys from the ​Connections→Native Clients​​ page.

​​Connecting Interactively​​

To connect via PrivX Bastion interactively:

  1. Connect to PrivX SSH Bastion using your PrivX account. For example, with ​ssh​​, ​sftp​​, or ​scp​​:

    $ ssh -p 2222 ​privxuser​​@​​​
    $ sftp -P 2222 ​privxuser​​@​​​
    $ scp -P 2222 ​local/path privxuser​​@​​​:​remote/path​​
    $ scp -P 2222 ​privxuser​​@​​​:​remote/path ​​​local/path​​

    Replace the example values as follows:

    • ​​privxuser​​ - Your PrivX-user name.

    • ​​​​ - Your PrivX-server address.

    • ​​local/path​​ - Local file/directory path for scp.

    • ​​remote/path​​ - Remote file/directory path for scp.

    Provide your PrivX-user password when prompted.

  2. You will be presented with a list of possible targets. Select a target to connect to it.

​​Connecting Directly​​

To directly connect via PrivX Bastion, provide:

  • Target-user name

  • Target-host address

  • PrivX-user name

  • PrivX-server address

  • ​​(Optional)​​ Extender name

  • ​​(Optional)​​ Target port

By default bastion runs on your PrivX servers, port 2222.

Full bastion syntax is as follows:

targetuser%extender%targethost%targetport%[email protected]

Common case leaves out the extender and the target port, leaving the syntax as following:

targetuser%targethost%[email protected]

Following are examples of ssh, scp and sftp usage with the connection string:

$ ssh -p 2222 targetuser%targethost%[email protected]
$ scp -P 2222 targetuser%targethost%[email protected]:example.txt \
$ sftp -P 2222 targetuser%targethost%[email protected]

Following is an example using PrivX Extender:

$ ssh -P 2222 targetuser%extender%targethost%[email protected]
$ scp -P 2222 example.txt \
targetuser%extender%targethost%[email protected]:/tmp

If you use native-client connections with bastion syntax often, consider specifying the connection parameters in the users' client configuration (typically at ​/etc/ssh/ssh_config​ or ​~/.ssh/config​​) using ​Host​​ blocks. For example:

    Port 2222
    User targetuser%targethost%privx-user

After which you can connect with much simpler syntax:

$ ssh

User sessions with native SSH clients can be monitored. For more information about viewing session audit data, see Viewing Audit Data​​. For more information about setting up session recording for a host, see Session-Recording Setup.

SSH-Bastion connections prompt you to log in to PrivX. For automated, scripted access, set up public-key authentication as described in Public-Key Authentication (SSH Bastion).

Connecting Directly Using ProxyCommand

Connecting directly via PrivX Bastion using ProxyCommand allows you to apply most configurations in the client-users' SSH configuration. This method requires you to use public-key authentication to PrivX Bastion. The SSH-client user must have an SSH keypair.

To connect directly using ProxyCommand:

  1. Add PrivX-Bastion host keys to the SSH-client's known-hosts file. You can get the Bastion host keys from the ​Connections→Native Clients​​ page.

  2. Add the client-user's authorized key to their PrivX account, as described in Public-Key Authentication (SSH Bastion).

  3. Configure SSH client to use public-key authentication and a proxy when connecting to target hosts. These configuration options can be specified in the client-user's client configuration (typically at /etc/ssh/ssh_config​ or ​~/.ssh/config​​), for example:

    Host *
        IdentityFile ~/.ssh/privx-bastion
        HostKeyAlias []:2222
        ProxyCommand nc -X connect -x %h %p

    In the example, replace privx.example.comwith your PrivX address.

    Note that the parameters your nc command accepts may be different from the example. You can substitute nc with another proxy command that supports http connect or SOCKS5/4a proxy protocol.

    By default PrivX Bastion listens for proxy connections on port 1080.

  4. Connect to target. If you provided the configuration options in the client-user's client configuration:

    ssh [email protected]

    Alternatively you may provide the configuration options in the ssh command, for example:

    ssh -o "IdentityFile ~/.ssh/privx-bastion" \
    -o "HostKeyAlias []:2222" \
    -o "ProxyCommand nc -X connect -x %h %p" \
    [email protected]

    Your connection will be routed via PrivX Bastion to the final target. Connection to PrivX Bastion is authenticated using public-key authentication.

Connecting via PrivX Agent

Linux and MacOS

After PrivX agent is set up for your workstation account, you can establish connections to targets using native clients with the agent. To do this on Linux or MacOS:

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

    You may verify that the agent is running with:

    $ privx-agent-ctl status

    The command should return a message similar to the following:

    PrivX SSH Agent Status
      PrivX Server
      Login status          logged out

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

    $ ./privx-agent-unix bash
  2. Via the terminal, authenticate against PrivX using your PrivX credentials. For example (replace ​username​​ with your PrivX user name):

    $ privx-agent-ctl login ​username​​

    You may verify your login status with:

    $ privx-agent-ctl status

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

    $ privx-agent-ctl target list
    Accessible targets and granting roles:
          [email protected]:222           Example Role 01

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

    $ ssh [email protected] -p 222


After PrivX agent is set up for your workstation account, you can establish connections to targets using native clients with the agent. To do this on Windows:

  1. Use the PrivX agent to authenticate with PrivX. To do this, right click the PrivX-agent tray icon, then click ​Login​​. Log in using your PrivX credentials. Complete multi-factor authentication if required.



    If PrivX-agent login fails with ​Failed: Login through web UI is required​​, then please use a web browser to log into PrivX GUI and complete MFA setup as described in Multi-Factor Authentication.

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

    Provide the following connection settings:

    • ​​Role (optional)​​: You may choose to log in with the permissions of a specifc PrivX role. By default, you are logged in using any applicable role.

    • ​​Target​​: The target host.

    • ​​Client​​: The native client used for connecting; PuTTY for connecting through SSH or PSFTP through SFTP.

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

Updated 26 days ago

SSH Connections with Native Clients

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.