Connecting to Your Targets
A user's guide on connecting to your targets
Use the tiles below to jump to your desired target connection guide.
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 Servers
Start a shell session with your remote host using the zli
.
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 examplename@company.com
, 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
If you're looking for guidance on connecting to a passwordless database, take a look at our how-to guides here.
Begin your connection to your database using the zli
.
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
.
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.
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
:
Optional: Install kube-ps1
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.
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.
Windows RDP and SQL Servers
To connect to your Windows RDP or SQL Server targets from the zli
, use the following command:
This command will return a target string, which is a localhost
address containing a specific port number (i.e., Started RDP daemon at localhost:64271 for rdp-target1
). This is where your RDP or SQL Server connection is being hosted.
For Windows users, connecting to an RDP or SQL Server target automatically launches an appropriate desktop application to facilitate the connection (i.e., Microsoft Remote Desktop or SQL Server Management Studio). This default behavior can be disabled with zli configure set noAppStart true
.
For those on Linux or Mac, you can interact with your RDP and SQL Server target using the tool of your choice.
Once you add your connection, enter your username and password credentials as you normally would.
Web Servers
Connect to your web server using the zli
.
For example, if the web server 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 web server.
SSH Tunnels and File Copy
Tunnel to a remote host using the zli
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:
Method 1: Use BastionZero's SSH config management capability.
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:
Running this command will also provide the following context in your bzero-bz-config
file to help you navigate:
Now, you can connect to any of the listed hosts using native SSH. You may need to specify a user if you have multiple users defined by policy (i.e., ssh root@my-target
). Use the directions in the context above to do so.
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 examplename@company.com
, 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.
Method 2: Manually update your SSH config with the output of zli generate ssh-proxy
to proxy your SSH connections through BastionZero.
zli generate ssh-proxy
to proxy your SSH connections through BastionZero.Run the following and copy the output into your SSH config file.
The output will look something like the following:
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.
Examples
To SSH as
root
to the targetcentos
, this will look likessh root@centos
(if you used method 1) orssh 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
.
Disambiguating between SSH targets
If your organization has SSH targets that share the same name and are in the same environment, you will need to connect to your target using its target ID and prepending the bzero-
prefix to ensure the connection routes through BastionZero.
Target IDs can be found by using the following command: zli lt -i
.
Once you've found the target ID, to connect, your command may look like:
ssh root@bzero-0009f4e0-3ab8-4cde-8935-0ad50ccc8dce
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 updated