Connecting to Your Targets
A user's guide on connecting to your targets
Last updated
A user's guide on connecting to your targets
Last updated
Copyright © 2024
Moving forward, we are natively rebuilding BastionZero’s technology as Cloudflare’s Access for Infrastructure service.
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.
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.
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.
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:
kube-ps1kube-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.
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.
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.
zliIf you have not configured your local machine to connect via tunnel, update your SSH configuration before connecting. This can be accomplished in two ways:
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.
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.
To SSH 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.
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
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.
Linux Servers
Databases
Kubernetes Clusters
Windows RDP and SQL Servers
Web Servers
SSH Tunnels and File Copy
