How to use BastionZero to connect to a Linux Host using the ZLI

This guide demonstrates how to install the agent, set up policy, and connect to a Linux target using the ZLI


In this guide, I’ll demonstrate the most effective way to implement the BastionZero service directly on target systems you wish to access remotely without the need for a jump host.

Preparing our Account

For the purposes of this guide, I’lll assume you have already signed up for a BastionZero account, have your BastionZero account integrated with your IDP, and have the ZLI installed on your local machine. Once that is complete, we’ll do a few things in our BastionZero account to set ourselves up for success as outlined below:

  • Log into BastionZero web interface at

  • Create a registration key

  • (optional) Create an environment which we can associate our targets with

We can grab a registration key from the BastionZero web interface at Once you sign in, select "Create" in the upper righthand corner and choose "API Key."

For Registration keys, you must select the Registration Key box below the name field. Clicking "Generate API Key" will then display the new registration key ID and secret. Hang onto this secret for later! It won’t be available in the UI again once you close the dialogue.

After we have generated our registration key, we can optionally create an environment to associate our targets with. Creating an environment will allow us to group targets together so that later we can manage access policies more efficiently; when you bring up a target, you can associate it with an environment which should give access to anyone who has been granted permissions to that environment.

We’ll once again hit “Create” in the top right corner and select “Environment”. Give this environment a name (I’ll be using “test-environment” for this guide) and a description. You can configure the BastionZero platform to automatically remove offline targets after a certain period, which I’ve set to 7 days in our case.

After the environment has been created, you’ll want to find its UUID and save this for later. You can do this by checking the “Display: UUID” box and making note of the new environment’s UUID.

We’re now ready to install the agent on our target! We should have both our registration key and optional environment UUID at hand.

Install the BastionZero Agent on your target

There are a number of ways we can install the BastionZero agent on our target. Of note, you can install BastionZero alongside any current access technologies (like SSH) without issue. The primary installation methods are described here. For this blog post, we’ll assume you’re using a Debian based operating system for your target. We can take advantage of the Apt package manager for installation.

Let’s install the BastionZero agent on our target. Gain access to your target as a user with root privileges and run the following commands:

  1. Install the BastionZero public key from the Ubuntu key-server.

    sudo apt-key adv --keyserver --recv-keys E5C358E613982017
  2. For https, add the BastionZero repo with:

    sudo add-apt-repository 'deb stable main'
  3. For http (i.e., on an Ubuntu 14.x machine), add the BastionZero repo with:

    sudo add-apt-repository 'deb stable main'
  4. Update the apt cache.

    sudo apt update
  5. Install the agent bzero.

    sudo apt install -y bzero
  6. Register the agent with BastionZero

    sudo bzero -registrationKey *registration API key secret* -environmentId *UUID* -targetname *nameyourtarget*

You should be greeted with a prompt confirming success! Check that the target has become available in the web interface’s Targets section.

Configuring Policy

Before connecting to our new target through the ZLI, we need to create an access policy which allows us to assume a role on our target. We’ll point our browsers to the Policy section of BastionZero’s web interface and once again click “Create” in the top right hand corner. We can then build an access policy for our new target.

  • Policy Type: use “Target Access” which allows us to login directly to the target

  • Policy Action: use the “Shell” action to allow us to log in with the ZLI, and the “SSH Tunnel” action for SSH tunneling.

  • Users: select yourself here

  • Environment: select test-environment (or, if you skipped creating an environment, click “Targets” and select your registered target here)

  • Allowed Target Users: select which roles you’d like to be able to assume on the target. You may want to include root or the user you logged into as when installing the agent above.

Click “Save”. You should now be ready to connect to our target!

Connecting to your BastionZero Target using the ZLI

Let’s head to our terminal and substantiate a connection to our new target. You can login to the ZLI using the zli login command.

Once you’re logged in, you should run the zli lt command to check which targets are registered and available for connection.

Now we can substantiate a connection to our example-target using zli connect bzero-user@example-target.

You should now be connected to your target! Run a few commands and then head to the logs page and verify that your commands are being captured.

Success! We’ve been able to gain access to the target system using the ZLI.

Last updated

Copyright © 2024