# Getting Started

Follow the steps below to install and run BastionXP as your PKI/CA with built-in SSH bastion host support.

# Prerequisites

You need to have the following to install and run BastionXP server

  • Two Linux VMs: one for the BastionXP (bastion host) and one for the host.
  • A registered domain name like bashost.example.com
  • SSL certificate for the registered domain name
  • GitHub OAuth Credentials for SSO Login
  • Open up TCP ports 4020 and 4021 in the bastion host VM and port 4022 in the host VM.

# Overview

We'll use the following bastion host setup for our reference. We'll be configuring only one SSH host and one SSH client in this Getting Started guide.

SocketXP Bastion Host Solution

# Goal

The goal of this documentation guide is to show you:

  1. How to setup BastionXP server(VM) as a PKI/CA that issues SSH certificates to hosts(VM) in your private cloud and to end users who wants access to these hosts. The BastionXP instance would also act like an SSH bastion host or jump host to access the hosts in your private cloud that are not exposed to the internet directly.
  2. How to setup the BastionXP client utility named bsh on the host machines and how to use bsh to login and download SSH host certificates from the BastionXP PKI/CA instance.
  3. How to setup the BastionXP client bsh on the end user laptops running Windows/MacOS/Linux and how to use bsh to login and download SSH user certificates from the BastionXP PKI/CA instance.
  4. How to login from the SSH client machine (Laptop/PC) into the SSH host machines (VMs) via the BastionXP SSH proxy (VM) using SSH Certificates.

# BastionXP VM Setup

# Step 1.1 - Download and Install

On the BastionXP VM, download the appropriate BastionXP binary package for your Linux distro as RPM or Debian package. Use the appropriate package manager in your Linux distro to install the downloaded BastionXP package.

# Redhat/Centos/Fedora

curl -O https://portal.socketxp.com/download/bashost/bashost-0.0.1-1.x86_64.rpm
sudo yum install ./bashost-0.0.1-1.x86_64.rpm

# Debian/Ubuntu

curl -O https://portal.socketxp.com/download/bashost/bashost_0.0.1-1_amd64.deb
sudo apt install ./bashost_0.0.1-1_amd64.deb

# Step 1.2 - Configuration

You need to setup the following configurations.

# Setup 1.2.1 - Configuration File

Create a config.json file in the /etc/bashost directory with the following contents. Create the directory /etc/bashost before you begin.

    "mode": "proxy",
    "gateway_domain": "bashost.example.com",
    "primary_user_email": "[email protected]"


Please don't forget to update the gateway_domain to your own domain name.

Also update the primary_user_email field with your GitHub email address which is the primary verified email address associated with your GitHub account. This is required to allow the BastionXP admin to login via GitHub OAuth SSO into the BastionXP web portal.

If you want to run the bashost in "auth" mode (that is, you want the PKI/CA functionality only) without the SSH proxy functionality, change the mode to "auth" instead of "proxy" in the config.json file. Use the "auth" only mode, when you prefer to use the OpenSSH server to act like an SSH jump host or bastion host.

# Step 1.2.2 - SSL Certificate

You need to get a valid SSL Certificate from an SSL certificate provider to host your BastionXP instance publicly so that your team could access it via HTTPS. You can get a free SSL certificate from Let's Encrypt (opens new window).

Alternatively, you can also generate a self-signed SSL certificate yourself using the command below:

sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout server.key -out server.crt

You could enter the appropriate info for your organization when prompted. Here is an example:

Country Name (2 letter code) [XX]:US
State or Province Name (full name) []:CA
Locality Name (eg, city) [Default City]:SFO 
Organization Name (eg, company) [Default Company Ltd]:Example Inc
Organizational Unit Name (eg, section) []:Dev Team
Common Name (eg, your name or your server's hostname) []:bashost.example.com
Email Address []:[email protected]

SSL Certificate Warning:

Self-signed SSL certificate is not recommended for production deployments. Use it only for testing or trial purposes.

If you use a self-signed SSL certificate, when you try to access the BastionXP web portal you'll see a warning from your browser that the SSL certificate is issued by an unknown authority. You should accept the warning, create an exception and continue to access the BastionXP web portal.

Finally, copy and paste the SSL certificate and the private key file into the /var/lib/bashost folder.

sudo cp server.* /var/lib/bashost

# Step 1.2.3 - GitHub OAuth Credentials

Sign up and get your free GitHub OAuth creditials for the BastionXP app from GitHub as explainedhere (opens new window)

To configure the BastionXP server to use your GitHub credentials, create a file named github_oauth.json in the /var/lib/bashost directory with the following contents:

  "client_id": "your-github-client-id",
  "secret": "your-github-secret"


Enterprise version of the software has support for G-Suite, Microsoft Office 365, Okta and more. The free version has the support for GitHub SSO login only.

# Step 1.3 - Restart

Now restart the BastionXP service already running in the background, to pickup the above configuration changes.

sudo systemctl restart bashost

You can check the bashost logs as shown below:

tail -f /var/lib/bashost/bashost-proxy.log

# Step 1.4 - Login to the web portal

Now point your web browser to https://bashost.example.com (replace your domain name for example.com). Login using your GitHub credentials as an admin user [Use the primary_user_email specified in the configuration file ].

After you login, go to the "Teams" section, edit your email account listed there. Add the login names you would use to login to your host machines, eg: root, ec2-user, dev-team, alice, dave etc. Perform this action before you login and download SSH user certificates from your client machines. The SSH user certificates issued will have these login names in the principals directive. The host machine will not allow SSH login by an end user, if the SSH user certificate doesn't contain a valid login name in the principals.

Add the email IDs of your team members and update the roles and logins manually for each user.


Make sure that TCP ports 443 and 4020 are opened up in BastionXP VM under the firewall settings. SocketXP web portal and auth server are reachable via the port 443. TCP port 4020 is the BastionXP proxy port.

# Host VM Setup

# Step 2.1 - Download BastionXP Client

On the host VM, download the BastionXP client utility named bsh using the following command:

curl -O https://bashost.example.com/download/linux/bsh
chmod +x bsh
sudo mv ./bsh /usr/local/bin

Replace the domain name in the above URL to match your registered domain name. The client is downloaded from your bashost instance.

Next we need to download the SSH Host Certificate for the host VM. For this we need to get an authtoken from the web portal as an admin user.

# Step 2.2 - Authtoken

Login to the BastionXP web portal using GitHub SSO as a primary user. Go to the Authtoken page and create a new token with the purpose selected as HOST_CERTIFICATE. Once a new HOST_CERTIFICATE token is created, expand the row and copy the authtoken.

Use the authtoken in the below command to download a host certificate for the host VM.


Note that this is a short-lived authtoken and it will expire in 10 minutes. If it expires, you need to recreate a new token for the same purpose.

# Step 2.3 - Login and Download SSH Host Certificate

bsh login --proxy bashost.example.com  --host --token <authtoken>

View the SSH host certificates downloaded from the BastionXP server VM as part of the login process.

$ ls ~/.bsh
ssh_host-cert.pub   ssh_host   ssh_user_ca.pub

Move these files to the /etc/ssh folder.

sudo mv ~/.bsh/* /etc/ssh

# Step 2.4 - Update SSHd configuration

Now we need to make the SSHd server to start using the SSH host certificate. Edit the /etc/ssh/sshd_config file as a sudo user and update the following configuration settings.

$ nano /etc/ssh/sshd_config


Host /etc/ssh/ssh_host
HostCertificate /etc/ssh/ssh_host-cert.pub
TrustedUserCAKeys /etc/ssh/ssh_user_ca.pub


# Step 2.5 - Restart SSHd Service

Finally, restart the SSHd service to make the configuration changes take effect. Verify if the SSHd is online, after the restart.

sudo systemctl restart sshd
sudo systemctl status sshd

# SSH Client Setup

# Step 3.1 - Download BastionXP Client

On your SSH client machine, download the BastionXP client bsh using the following command:

# Windows

Download the Windows version of the bsh client from here:

Windows Client Download Link:


# MacOs

curl -O https://bashost.example.com/download/darwin/bsh
chmod +x bsh
sudo mv ./bsh /usr/local/bin

# Linux

curl -O https://bashost.example.com/download/linux/bsh
chmod +x bsh
sudo mv ./bsh /usr/local/bin

Replace the domain name in the above URL to match your BastionXP instance's registered domain name.

Next we need to download the SSH user certificate for the SSH client from the BastionXP PKI/CA.

# Step 3.2 - Login and Download SSH User Certificate

bsh login --proxy bashost.example.com  

You'll be redirected to a web browser where you'll be asked to login into your GitHub account using your username, password and the two-Factor Authentication(2FA).

You could optionally use a --no-redirect flag to prevent redirecting to your default browser.

Check if the user certificate has been downloaded to the .bsh folder in the user's HOME directory, at the end of the login process.

$ ls -l ~/.bsh
ssh_user-cert.pub   ssh_user   ssh_host_ca-cert.pub

# Step 3.3 - Update the SSH Client Configuration

Update the OpenSSH client config file ssh_config to use the SocketXP BastionXP as the bastion host or jump host. Also, make the SSH client to use the SSH user certificate as an identity, as shown below for an example user alice:

$ nano ~/.ssh/ssh_config

Host host1
Hostname host1.example.com
ProxyJump jumphost
User alice
IdentityFile  /home/alice/.bsh/ssh_user

Host jumphost
Hostname bashost.example.com
Port 4020
User alice
IdentityFile /home/alice/.bsh/ssh_user


You could use the host VM's internal IP, in the place of its domain name.

Next, edit the SSH client's known_hosts file and add the Host CA's SSH certificate as the certificate authority for the host, using the @cert-authority directive. This config will ensure that the SSH client will accept any SSH host certificate signed by the SSH host CA. It will not display any Trust On First Use (TOFU) message when the SSH client connects to the host. Please note that you need to copy paste the contents of the ssh_host_ca-cert.pub file into the known_hosts file as shown below.

$ nano ~/.ssh/known_hosts

# Accept any host in *.example.com, whose certificate is signed by the following CA
@cert-authority *.example.com ssh-rsa AAXasdyeBN....


Delete all stale known names for the host from the known_hosts file.

# Step 3.4 - SSH Login

Now SSH login to the host VM using the SSH client as shown below

ssh host1

Alternatively, you could use the .bsh client to ssh into the host VM as shown below:

bsh ssh --proxy bashost.example.com [email protected]


If you have any questions or suggestions, please email us at: [email protected]