Connecting to Your Targets
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.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 [email protected]
. For more information on how to set up your target connect policies to support this, navigate to our policy management page.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.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.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 │
└──────┴──────────────────────────────────────┴─────────────┴────────────────┴───────────────────┘
kube-ps1
is a third-party tool that adds your current-context
and namespace configured in your kubeconfig
file to your Bash/Zsh prompt.(⎈|[email protected]: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.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.
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
orscp
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 [email protected]
#
# 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
andbzero-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-runzli generate sshConfig
.zli v. 6.8.1
, after runningzli 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 namedbzero-target
in an environmenttest-environment
. You will now be able to connect to the target viassh 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 [email protected]
. 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 targetcentos
, this will look likessh [email protected]
(if you used method 1) orssh [email protected]
(if you used method 2) - Tunneling to a remote server application may look like
ssh -L 6100:127.0.0.1:5432 [email protected]
. - 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 [email protected]
.
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 9d ago