# BastionXP Host Mode Setup

BastionXP is a single-binary that can be configured to perform multiple functions. BastionXP can be configured to function in 3 different modes:

"Proxy" Mode - Functions as PKI/CA + SSH Jump Bastion Host
"Auth" Mode - Functions as PKI/CA only
"Host" Mode - Functions as a Reverse Proxy client and/or SSHd Server

You can configure BastionXP to run in the "Host" mode as a reverse proxy client enabling SSH login to your host/server/VM from the BastionXP Cloud Web Portal using the SSH web terminal. This is extremely useful if you have IoT devices or servers behind NAT router or firewall, and requires secure remote access.

Note for BastionXP Cloud Users:

BastionXP Cloud SSH Key Manager: If you want to use the BastionXP Cloud SSH Key Manager, you must download, install and configure the bastionxp software to run (in "Host" mode) in all your host machines, servers or VMs, so that SSH public keys could be managed on these servers for user logins. The bastionxp service running in the "host" mode will download SSH public keys from the BastionXP Cloud SSH Key Manager and place them in the appropriate location ($HOME/.ssh/authorized_keys) for user login.

BastionXP Cloud SSH Certificate Manager (CA): If you plan to use BastionXP Cloud SSH Certificate Manager, then you can skip running bastionxp (in "host" mode). You can use the bsh client utility to download SSH host certificates and SSH CA certificate on all your host machines. In SSH certificate based authentication, there is no need to manage SSH user certificates in the host machines. That's the beauty and simplicity of SSH certificate based authentication.

# BastionXP as SSHd

You can also configure BastionXP to function as an SSHd server in your host machines instead of using the OpenSSH SSHd server.

Following are the advantages of running BastionXP as SSHd instead of using OpenSSH SSHd server:

# Advantages of BastionXP SSHd

Simple, lightweight and easy to use. Pre-configured SSHd server that comes out-of-the-box.
Automates SSH host certificate renewal and rotation.
SSH session recording and replay function is possible only when BastionXP is used as the SSHd in host machines.
Connect to hosts/IoT devices in any private network behind NAT router and Firewall (using BastionXP's built-in mTLS reverse proxy tunnels).
BastionXP SSHd can run along with any existing OpenSSH SSHd server. BastionXP SSHd listens on port 4022 by default. Useful for initial testing.

# Prerequisites

A host VM
Open up TCP port 4022 in the host VM. By default, BastionXP SSHd listens on port 4022. It can be configured to listen on port 22.

Here are the steps to download, install, configure and setup BastionXP as an SSHd server in host machines:

# Host Mode Setup and Configuration

# Step 1.1 - Download and Install

On the Host Server or VM, follow the instructions here to download and install (opens new window) the appropriate BastionXP binary package for your Linux distro as RPM or Debian package.

BastionXP CA will be installed and running as a Linux Systemd Daemon in the background.

# 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/bastionxp directory with the following contents. Create the directory /etc/bastionxp before you begin. Add the following configuration to the /etc/bastionxp/config.json file.

Option #1: Reverse Proxy Client Config:

{
    "mode": "host",
    "gateway_domain": "bastionxp.example.com",
    "host": "host1.example.com",
    "authtoken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpX..."
}

Option #2: Reverse Proxy Client Plus SSHd Server Config:

{
    "mode": "host",
    "gateway_domain": "bastionxp.example.com",
    "host": "host1.example.com",
    "sshd_enable": true,
    "authtoken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpX..."
}

Note:

Please don't forget to update the gateway_domain to your domain name. The host name can be any locally unique domain name within your organization.

If you are using BastionXP Cloud SSH CA (opens new window), update the gateway_domain to cloud.bastionxp.com.

Login to the BastionXP web portal as a primary user using your SSO provider. 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. Paste the authtoken into the config.json file created above.

Note:

For security reasons, the HOST_CERTIFICATE type authtoken is valid only for 10 minutes. If you failed to configure BastionXP as SSHd in the host machine before the token expires, you need to get a new authtoken from BastionXP web portal again.

You can find the BastionXP SSHd logs in the log file located at: /var/lib/bastionxp/bastionxp-host.log

# Step 1.3 - Restart

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

sudo systemctl restart bastionxp

You can check the bastionxp logs as shown below:

tail -f /var/lib/bastionxp/bastionxp-host.log

The newly downloaded host SSH and TLS certificate keys can be found here:

$ ls ~/.bsh
ssh_host-cert.pub   ssh_host   ssh_user_ca.pub
tls_ca-cert.pem tls_server-cert.pem

# Connecting to your host machine

Now that the bastionxp software is running in the "host" mode in your host/server, you can SSH login to your host either from the BastionXP web portal's SSH web terminal, or using your preferred SSH client.

← SSH Key Manager - Getting Started Roles Based Access Control (RBAC) →