Connecting to Your Targets

Use the tiles below to jump to your desired target connection guide.
​
Linux hosts
​
​
Databases
​
​
Kubernetes clusters 
​
​
Web servers
​
​
SSH tunnels and file copy
​
Most connections to secured targets begin with a zli connect, with the exception being SSH tunnels. In many cases, this will follow the format zli connect {target-name}. If the target has only one target role associated with it, BastionZero will assume that target role and try to establish a connection. If there are multiple target users for a single target, then the zli will prompt you to connect with the explicit user role. This will look like zli connect {user}@{target-name}.
To verify user roles or target names, run zli lt -d before your connect command.
Linux remote hosts
Start a shell session with your remote host using the zli.
zli connect {target-name}
For example, if the remote host is named centos, connecting looks like zli connect centos.
BastionZero supports connecting to your remote Linux hosts using your IdP username as the target user. For example, if the email you use to authenticate with BastionZero is [email protected], then connecting to your target looks like zli connect examplename@centos. For more information on how to set up your target connect policies to support this, navigate to our policy management page.
Databases
Begin your connection to your database using the zli.
zli connect {database target name}
For example, if the database target name is postgres, connecting looks like zli connect postgres.
The zli will return a local port number that can be used in your database client to connect. For example, if using psql, the command would be psql -U {username} -h localhost -p {port number}, where the port number was returned in the output of the zli connection command.
Kubernetes Clusters
Connect to your Kubernetes cluster using the zli.
zli connect {user}@{clusterName}
Substitute {user} and {clusterName} with the Kube user and cluster name you have configured in policy.
After running zli connect, the zli updates your default kubeconfig file located at ~/.kube/config with an additional, BastionZero-managed context entry: bzero-{user}@{clusterName}. This context entry provides access to your cluster through BastionZero. The zli also sets your current-context to this newly created entry, so that you can use your Kubernetes tools immediately without having to switch your context.
The zli respects the KUBECONFIG environment variable. Set KUBECONFIG to a different filepath before running zli connect if you would like a different kubeconfig to be updated rather than the default one.
Verify your current-context has been updated.
$ kubectl config current-context
bzero-{user}@{clusterName}
Once your current-context is set, you can use kubectl or other Kubernetes tools (e.g. Lens) to access your cluster.
Additionally, the zli can forward your commands to kubectl if you use zli kube -- {your kubectl command}. The benefit of using the zli kube command is that it captures human-readable commands in the BastionZero logs (i.e. get pods) whereas direct kubectl commands will appear only as API calls.
The zli permits you to connect to multiple Kubernetes clusters at once, or the same cluster multiple times as long as the {user} is distinct from any existing connections to the same target you've made on your machine. Each new Kubernetes connection results in an additional context entry following the same bzero- format mentioned above. If you ever forget the context name for your current Kubernetes connections, run zli ld kube to display a list of your Kube connections and their corresponding context name.
Switch between different cluster connections by using kubectl config use-context {contextName}, or a third-party tool such as kubectx. kubectl config get-contexts -o name will display all contexts by name.
Recommendation: Install fzf as well as kubectx, so that you can use an interactive, fuzzy-finder menu to switch between your contexts. See kubectx's documentation here for more information.
To see all of your open Kubernetes connections (or if you've forgotten the cluster name or Kube role configured) across all of your machines where you've connected via the zli, run zli lc -t kube:
$ zli lc -t kube
┌──────┬──────────────────────────────────────┬─────────────┬────────────────┬───────────────────┐
│ Type │ Connection ID                        │ Target User │ Target         │ Time Created      │
├──────┼──────────────────────────────────────┼─────────────┼────────────────┼───────────────────┤
│ Kube │ 947f3990-4219-4148-85be-233802d976ba │ dev-user    │ my-cluster-1   │ 11/17/22, 1:29 PM │
├──────┼──────────────────────────────────────┼─────────────┼────────────────┼───────────────────┤
│ Kube │ fde9997d-780f-49a3-bef3-b1b26d1251cf │ test-user   │ my-cluster-1   │ 11/17/22, 1:30 PM │
├──────┼──────────────────────────────────────┼─────────────┼────────────────┼───────────────────┤
│ Kube │ 3a0be20a-f7c3-4c39-88a8-9c908d957805 │ dev-user    │ othercluster   │ 11/17/22, 1:50 PM │
└──────┴──────────────────────────────────────┴─────────────┴────────────────┴───────────────────┘
Optional: Install kube-ps1
​kube-ps1 is a third-party tool that adds your current-context and namespace configured in your kubeconfig file to your Bash/Zsh prompt.
(⎈|bzero-developer@my-cluster:default) $ 
This is a helpful tool because BastionZero's context names include both the {role} and {clusterName} for all your connections to your Kubernetes targets. Since kube-ps1 adds your current-context to your terminal prompt, you'll always know which cluster and role you are currently connected as before issuing a kubectl command.
Web Servers
Connect to your webserver using the zli.
zli connect {webserver-name}
For example, if the webserver target name is grafana, connecting looks like zli connect grafana.
Your default browser will launch a new tab or window with the connection to your webserver.
SSH Tunnels and File Copy
Tunnel to a remote host using the zli
If you have not configured your local machine to connect via tunnel, update your SSH configuration before connecting. This can be accomplished in two ways:
1.Use BastionZero to find a list of targets to which you have tunnel or scp access and automatically include them in your SSH config file with the following command:
zli generate sshConfig
Running this command will also provide the following context in your bzero-bz-config file to help you navigate:
#********************************************************************************
#
# BastionZero auto-generated SSH configuration file
#
# This file is auto-generated based on your SSH policy as specified by the
# administrator(s) of your BastionZero account.
#
# All SSH connections are secured through the BastionZero ZLI, ensuring you are secured
# with our MrZAP (multi-roots of trust) protocol.
#
# This file includes the following:
#
# If you have a target access / shell policy, you may use SSH
# to any host within that policy by using the format:
#
# ssh targetUser@bzero-targetHostname
#
# This will proxy the SSH connection through BastionZero as the 'bzero-' wildcard will
# match the proxy entry below.
#
# BastionZero makes specific use of the %n and %s in our configuration statements
# below. %n will pass and proxy the host name as the entry exists. %s will convert it to
# lowercase. Please be cautious if changing these values.
#
# Users
# -----
# If your administrator has provided SSH access with more than one target user, the
# full list has been provided in a comment under the host. To set a default simply
# add the appropriate user line by copying and modifying the line. For example:
#
# # User postgres, centos, user1, ec2-user
#
# Becomes:
#
# # User postgres, centos, user1, ec2-user
# User ec2-user
#
# Target Names
# ------------
# Each host name is formatted in two ways: 
# 1. <target name> and
# 2. <target name>.<environment name>
# This allows you to connect based on environment name for targets that 
# may share the same name.
#
#********************************************************************************
Now, you can connect to any of the listed hosts using native SSH. Note that you may need to specify a user if you have multiple users defined by policy. Use the directions in the context above to do so.
We strongly encourage running the latest version of the zli. In case you aren't, here are a few notable updates we've made:
zli v. 6.9.5, you may set a default target user for SSH and SCP connections. You can find more information on that here.
zli v. 6.8.5, your /.ssh/config and bzero-bz-config files provide context for users to understand quickly the contents of the file. To update your configuration files to include these new descriptions, re-run zli generate sshConfig.
zli v. 6.8.1, after running zli generate sshConfig, you may connect to a target via SSH using the dot environment feature to disambiguate targets with the same name. For example, if you have target named bzero-target in an environment test-environment. You will now be able to connect to the target via ssh bzero-target.test-environment. You can find more information on the dot environment feature here.
BastionZero supports connecting to your remote Linux hosts via ssh using your IdP username as the target user. For example, if the email you use to authenticate with BastionZero is [email protected], then connecting to your target via ssh looks like ssh examplename@centos. For more information on how to set up your target connect policies to support this, navigate to our policy management page.
1.You can also run the following and copy the output into your SSH config file.
zli generate ssh-proxy
The output will look something like this:
Host bzero-*
IdentityFile /Users/ansambor/Library/Preferences/bastionzero-zli-nodejs/bzero-temp-key
ProxyCommand zli ssh-proxy  -s %n %r %p /Users/ansambor/Library/Preferences/bastionzero-zli-nodejs/bzero-temp-key
Once you've added this to your SSH config file, connect to any remote host using native ssh by appending bzero to the beginning of the hostname.
For example,
To begin a shell session as root to the target centos, this will look like ssh root@centos (if you used method 1) or ssh root@bzero-centos (if you used method 2)
Tunneling to a remote server application may look like ssh -L 6100:127.0.0.1:5432 root@bzero-postgres.
Tunneling using a client browser to reach an HTTP application on your local network may look like ssh -L 8080:10.0.0.1:80 root@bzero-httpRedirectServer.
Copying files with SCP / SFTP
Because scp and sftp are both built on top of SSH connections, you can use either command to perform file upload/download operations on any remote host for which you have a Tunnel or File Transfer policy. For example, if you followed method 1 above to configure SSH, you could upload a file to the remote machine's home directory with scp file-to-upload.txt centos:~.
When copying files, your data is secured using the same cryptographic protocol that underpins all BastionZero connections.
Note that File Transfer access to a target can only be used to perform uploads and downloads. If you don't have Tunnel access to the same target, you will not be able to execute remote commands, acquire a login shell, or set up port forwarding.
For additional information on SSH, scp, and sftp with BastionZero, check out its ZLI Reference Manual entry.
Last modified 3mo ago
Connecting to Your Targets

Use the tiles below to jump to your desired target connection guide.

Linux remote hosts

Databases

Kubernetes Clusters

Optional: Install `kube-ps1`

Web Servers

SSH Tunnels and File Copy

Tunnel to a remote host using the `zli`

Copying files with SCP / SFTP
