ZLI Reference Manual

Product Pricing Main Site Sign In / Try Now
Search…
Overview
The BastionZero zli is an exec level command line interface client that provides users the ability to connect, tunnel, and manage their targets' policies.
Open Source & Distribution
The zli is an open-source project licensed under the Apache License, version 2.0. Details on how to download are available here.
Pro tip: For convenience, move your download of the zli into your bin $PATH. (Read more about $PATH)
Command Summary
The following tables list all the zli commands and their functions.
You can run zli help at any time to list all the available commands in the CLI.
Note: all commands are case-insensitive (lowercase and uppercase letters don't matter; e.g., zli login is the same as zli LoGiN)
Command
Description
​login​
Authenticates a user to the service using your SSO provider
​connect​
Connect to target
​tunnel (Deprecated)
Tunnel to a Kubernetes cluster
​default-targetgroup​
Update the default target group used when tunneling to a Kubernetes cluster
​policy​
List the organization's policies
​describe-cluster-policy​
Get detailed information about what policies apply to a certain cluster
​disconnect​
Disconnect the bctl daemon
​attach​
Attach to an open zli connection
​close​
Close an open zli connection
​list-targets, lt
List all targets
​list-connections, lc
List all open zli connections
​user​
List all of the organization's SSO users. Add or remove a policy's SSO users
​group​
List all of the organization's SSO groups. Add or remove a policy's SSO groups
​targetuser​
List, add, or remove a policy's target users
​targetgroup​
List, add, or remove a policy's target groups
​ssh-proxy-config (Deprecated)
Generate ssh configuration to be used with the ssh-proxy command
​ssh-proxy​
Tunnel an SSH connection to an SSM target
​configure​
Returns the configuration path for the zli client
​generate-bash (Deprecated)
Generate a bash script to autodiscover an SSM target
​quickstart​
Start an interactive onboarding session to add your SSH hosts to BastionZero
Global Flag Options
The zli includes a few global options that can be used with any command.
Flag Option
Description
--version
Show zli version number
--debug
Show debug events
-s, --silent
Silence all zli output messages
--help
Show command help
Command Manual
The following section documents each zli command operation listed in the overview above.
login
Synopsis
1
zli login [--mfa <code>]
Copied!
Description
The login command authenticates a user to the BastionZero service. When executed, a new window is opened in the user's default browser. The user may then select their SSO provider and authenticate by supplying their username and password. This is accomplished using the Open ID Connect (OIDC) specification.
Options
-m, --mfa: MFA code to pass to BastionZero if the organization has required MFA.
connect
Synopsis
1
zli connect <targetString> [--targetType dynamic]
Copied!
Description
The connect command spawns an interactive shell to any type of target (SSM, Kubernetes, Web, Db or dynamic access target (DAT)) as indicated by the <targetString>.
When connecting to SSM targets:
The <targetString> is required and must be in the format [targetUser]@targetName:
targetUser: The UNIX username to login as. In cases where only a single targetUser can be used to connect to this target via policy then targetUser may be omitted. In cases where there are more than one targetUsers that can be used to connect to this target targetUser is required and otherwise a warning will be printed and the command will fail. Use zli lt -d to see which target users are allowed for targets.
targetName: The name or UUID of an SSM target or DAT configuration. In cases where there is a name conflict, i.e., two or more targets with the same name, then the UUID must be supplied.
The logged-in zli user must have a Target Connect policy that covers this targetUser and target combination.
When connecting to Kuberentes targets:
The <targetString> must be in the format [email protected]:
targetUser: The Kubernetes RBAC user to impersonate as. All Kubernetes API calls forwarded by the bctl daemon will authenticate as this user and assume that user's role and cluster bindings.
targetName: The name of the Kubernetes cluster.
The logged-in zli user must have a Kubernetes policy that covers this targetUser and target combination.
When connecting to Web and DB targets:
The <targetString> must be in the format targetName:
targetName: The name of the Web or DB target.
The logged-in zli user must have a Proxy policy that covers this targetName.
For Kubernetes, Web and DB targets, this command spawns the bctl daemon on an available port of the user's machine. The daemon interacts with the target specified by the <targetString>. Once executed, users can interact with their target using various tools (e.g. kubectl, psql, Lens, etc.)
Note for Kubernetes targets users will have to point their kubeconfig file to the daemon's localhost HTTP server. You can learn more about using third party tools with BastionZero and Kubernetes here.
Options
--targetType dynamic: Specifies that this connection is to a DAT.
--targetGroup system:masters: For Kubernetes connections only, comma separated list of Kubernetes RBAC groups to impersonate as. In addition to authenticating as the specified targetUser, the bctl daemon will authenticate as these groups and assume their role and cluster bindings. The logged-in zli user must have a Kubernetes Access policy that covers this list of groups and cluster target.
--customPort: Forces the bctl daemon to run on a specific port.
Examples
zli connect [email protected] - Connect as UNIX user ssm-user to the uniquely named SSM target my-target.
zli connect my-target - Connects as a default UNIX user if only exactly one is allowed by policy to the uniquely named SSM target my-target
zli connect [email protected] - Connect as UNIX user john to an SSM target by referring to its unique UUID.
zli connect [email protected] --targetType dynamic - Connect to a DAT backed by the my-dat-config Dynamic Access configuration.
zli connect [email protected] - Start the bctl daemon and connect it to my-cluster as Kubernetes RBAC user admin.
zli connect [email protected] --targetGroup system:masters - Start the bctl daemon and connect it to my-cluster as Kubernetes RBAC user alice and RBAC group system:masters.
zli connect my-db-target - Start the bctl daemon and connect it to my-db-target.
tunnel
Tunnel has been deprecated in favor of connect in zli version 5.5.0
zli tunnel has been deprecated across all version of zli, to connect to Kubernetes targets please make sure to update zli to version >=5.5.0
default-targetgroup
Synopsis
1
zli default-targetgroup [--set <groupName>[,...]]
Copied!
Description
The default-targetgroup command updates a local configuration value that specifies the default target groups to use when executing zli tunnel. If no argument is provided, this command displays what is currently set as the default targetGroup.
Options
--set: Comma separated list of Kubernetes RBAC groups. Pass no value in order to remove any default target groups set (i.e. zli default-targetgroup -set). This will reset your default target group and no default will be assigned.
policy
Synopsis
1
zli policy [--type (targetconnect|organizationcontrols|sessionrecording|kubernetestunnel)] [--json]
Copied!
Description
The policy command lists the organization's policies.
Options
-t, --type: Policy type filter. If this flag is not provided, then all types of policies will be returned.
-j, --json: Output the list of policies in JSON format.
Examples
zli policy --json --silent | jq - List all policies. Output as JSON.
Pro tip: Pipe into jq for pretty formatting.
describe-cluster-policy
Synopsis
1
zli describe-cluster-policy <clusterName>
Copied!
Description
The describe-cluster-policy command returns detailed information about what policies apply to the <clusterName> cluster.
Options
There are no options for this command besides the global ones.
disconnect
Synopsis
1
zli disconnect
Copied!
Description
The disconnect command stops the tunnel connection to a Kubernetes cluster if there is one currently running. The bctl daemon process is killed.
Options
There are no options for this command besides the global ones.
attach
Synopsis
1
zli attach <connectionId>
Copied!
Description
The attach command attaches to an open zli connection. A zli connection is defined as one that exists in the cli-space; all connections created with the connect command exist in this space.
Options
There are no options for this command besides the global ones.
close
Synopsis
1
zli close (<connectionId>|--all)
Copied!
Description
The close command closes an open zli connection. A connection that has been closed can no longer be attached to. A zli connection is defined as one that exists in the cli-space; all connections created with the connect command exist in this space.
Options
-a, --all: Closes all connections in the cli-space.
list-targets
Synopsis
1
zli list-targets [--targetType (ssm|dynamic|cluster)] [--env <environmentName>] [--name <targetName>]
2
[--status (notactivated|offline|online|terminated|error)] [--user <userEmail>] [--detail] [--showId] [--json]
Copied!
Description
The list-targets command lists all the organization's targets. Optional result filters can be applied by passing in flags as described below. The returned table of targets includes the type, name, and environment of all targets.
Alias: lt
Options
-u, --user: Admin-only option. Filter targets based on targets that a particular user in your organization has access to via policy. A valid user email address must be provided. To help find the email address of any user in your organization you can use zli user to list all users.
-t, --targetType: Target type filter. Use zli lt --help to see full list of valid target types.
-e, --env: Environment name filter.
-n, --name: Target name filter.
-u, --status: Target status filter. Use zli lt --help to see full list of valid statuses.
-d, --detail: Returns extra detail in the output. The additional information includes the target's agent version, status, and suitable target users to use in the user portion of the <targetString> and <tunnelString> syntax.
-i, --showId: Display the target's UUID in the output.
-j, --json: Output the list of targets in JSON format.
Examples
zli lt -i -t cluster - List all Kubernetes cluster targets. Display the target's UUID.
zli lt --json --silent | jq - List all targets. Output as JSON. Pipe into jq for pretty formatting.
zli lt --user [email protected] - Lists all targets that [email protected] has access to through policy
list-connections
Synopsis
1
zli list-connections [--json]
Copied!
Description
The list-connections command lists all open zli connections. A zli connection is defined as one that exists in the cli-space; all connections created with the connect command exist in this space.
Alias: lc
Options
-j, --json: Output the list of connections in JSON format.
user
Synopsis
1
zli user [<policyName> <ssoUserEmail> (--add|--delete)]|[--json]
Copied!
Description
The user command lists all the organization's SSO users or adds/removes a user to/from a specific policy.
If no positional arguments are provided (i.e., zli user is executed by itself), then a list of all the organization's users is returned. The returned table includes the user's name, <ssoUserEmail>, role (admin or user), and time of last login.
When adding/removing a user (specified by --add or --delete), both <policyName> and <ssoUserEmail> must be provided. <policyName> should refer to a policy that exists in the list of the organization's policies (see the policy command). <ssoUserEmail> should refer to the email of one of the organization's users.
Options
-a, --add: Specifies that the provided user should be added to the policy.
-d, --delete: Specifies that the provided user should be removed from the policy.
-j, --json: Output the list of users in JSON format.
Examples
zli user my-policy [email protected] --add - Adds SSO user with email [email protected] to the my-policy policy.
zli user my-policy [email protected] --delete - Removes SSO user with email [email protected] from the my-policy policy.
zli user --json --silent | jq - List all the organization's users. Output as JSON. Pipe into jq for pretty formatting.
group
Synopsis
1
zli group [<policyName> <ssoGroupName> (--add|--delete)]|[--json]
Copied!
Description
The group command lists all the organization's SSO groups or adds/removes a group to/from a specific policy.
If no positional arguments are provided (i.e., zli group is executed by itself), then a list of all the organization's groups is returned.
When adding/removing a group (specified by --add or --delete), both <policyName> and <ssoGroupName> must be provided. <policyName> should refer to a policy that exists in the list of the organization's policies (see the policy command). <ssoGroupName> should refer to the name of one of the organization's groups.
Options
-a, --add: Specifies that the provided group should be added to the policy.
-d, --delete: Specifies that the provided group should be removed from the policy.
-j, --json: Output the list of groups in JSON format.
targetuser
Synopsis
1
zli targetuser <policyName> [<targetUser> (--add|--delete)]|[--json]
Copied!
Description
The targetuser command lists, adds, or removes a specific policy's target users. Target users determine what UNIX users or Kubernetes RBAC users are permissible to use in the connect and tunnel commands respectively.
If only the <policyName> positional argument is provided, then a list of that policy's target users is returned.
When adding/removing a target user (specified by --add or --delete), <targetUser> must be provided. <targetUser> refers to a UNIX username when editing a Target Connect policy. <targetUser> refers to a Kubernetes RBAC user when editing a Kubernetes Access policy.
Options
-a, --add: Specifies that the provided target user should be added to the policy.
-d, --delete: Specifies that the provided target user should be removed from the policy.
-j, --json: Output the list of target users in JSON format.
targetgroup
Synopsis
1
zli targetgroup <policyName> [<targetGroup> (--add|--delete)]|[--json]
Copied!
Description
The targetgroup command lists, adds, or removes a specific policy's target groups. Target groups determine which Kubernetes RBAC groups are permissible to use in the connect command. This command only applies to Kubernetes Access policies.
If only the <policyName> positional argument is provided, then a list of that policy's target groups is returned.
When adding/removing a target user (specified by --add or --delete),<targetGroup> must be provided. <targetGroup> refers to a Kubernetes RBAC group.
Options
-a, --add: Specifies that the provided target group should be added to the policy.
-d, --delete: Specifies that the provided target group should be removed from the policy.
-j, --json: Output the list of target groups in JSON format.
ssh-proxy-config
ssh-proxy-config has been deprecated in favor of generate ssh-proxy in zli version 6.0.8
Synopsis
1
zli ssh-proxy-config
Copied!
Description
The ssh-proxy-config command generates an ssh configuration block to be added to the user's ssh_config file. The generated configuration block allows the ssh command to tunnel SSH connections to SSM targets by calling the zli's ssh-proxy command behind the scenes.
This command only needs to be executed once, with the user taking the actions as specified in the output of the command to modify their ssh_config ($HOME/.ssh/config) file. After doing so, the user may utilize SSH tunneling by using ssh and specifying the correct hostname prefix (i.e., bzero-*).
See the following article for more information.
Options
There are no options for this command besides the global ones.
ssh-proxy
Synopsis
1
zli ssh-proxy <hostString> <userName> <portNumber> <identityFile>
Copied!
Description
The ssh-proxy command allows for proxying an SSH connection to an SSM target. The captured SSH connection can be an interactive shell or a port forwarding tunnel.
Users should typically not use this command directly. Instead, they should let ssh call it via the ProxyCommand directive.
<hostString> includes the SSM target's name or UUID in the case there are two or more targets with the same name. <userName> is the UNIX username to login as. <portNumber> refers to the port number on the SSM target running the sshd daemon. <identityFile> refers to the private SSH key generated by the zli.
The logged-in zli user must have a Target Connect policy that covers this userName and target combination. The Tunnel action must be enabled in the policy.
See the following article for more information.
Options
There are no options for this command besides the global ones.
configure
Synopsis
1
zli configure
Copied!
Description
The configure command returns the file path of both the zli's configuration and the logs kept as part of normal client operation. These files typically do not need to be configured or modified by a user.
Options
There are no options for this command besides the global ones.
generate-bash
generate-bash has been deprecated in favor of generate bash in zli version 6.0.8
Synopsis
1
zli generate-bash [--environment <environmentName>] [--agentVersion <version>] [--os (centos|ubuntu|universal)]
2
[--outputFile <filePath>] [(--targetName <name>|--targetNameScheme (do|aws|time|hostname))]
Copied!
Description
The generate-bash command generates a bash script that is used to autodiscover an SSM target. The script should be executed on the target machine to connect with BastionZero.
Options
-e, --environment: Specifies the environment the target will belong to once registered. Defaults to the Default environment if this flag is not provided.
--agentVersion: Use a specific version of the agent when installing the agent on the target. Defaults to the latest version if this flag is not provided.
--os: Force the script to assume the target is running a specific operating system. If this flag is not provided, the script will automatically infer the target machine's OS.
-o, --outputFile: Writes the bash script to a file on the user's machine.
-n, --targetName: Sets the target name explicitly.
--targetNameScheme: Configures the target name from a specific source. Defaults to the hostname source if this flag is not provided.
do: If the target machine is a DigitalOcean droplet, the target name will be set to the droplet's name.
aws: If the target machine is an AWS EC2 machine, the target name will be set to the instance's ID.
time: The target name will be set to target-%m%d-%H%M%S, where the variables are date formats. The formatted timestamp is the time the script is executed on the target machine.
hostname: The target name will be set to the machine's hostname.
quickstart
Synopsis
1
zli quickstart [--sshConfigFile <filePath>]
Copied!
Description
The quickstart command starts an interactive onboarding session that adds the user's SSH hosts, as specified by the the ssh_config file, to BastionZero.
See the following article for more information.
Options
-c, --sshConfigFile: Path to ssh_config file. Defaults to $HOME/.ssh/config if this flag is not provided.
generate
Synopsis
1
zli generate (kubeConfig [--customPort <portNumber>] [--outputFile <filePath>] [--update])
2
|            (kubeYaml <clusterName> [--labels <labelName>[,...]] [--environmentName <environmentName>] [--namespace <namespaceName>] [--outputFile <filePath>])
3
|            (sshConfig)
4
|            (ssh-proxy)
5
|            (bash [--environment <environmentName>] [--agentVersion <version>] [--os (centos|ubuntu|universal)] [--outputFile <filePath>] [(--targetName <name>|--targetNameScheme (do|aws|time|hostname))] )
Copied!
Description
The generate command generates files for Kubernetes or SSH
zli generate kubeConfig (Access):
zli generate kubeConfig creates the kubeconfig file that sets up the user's local Kubernetes tools (e.g. kubectl, Lens) to communicate with a registered Kubernetes cluster. The generated kubeconfig configures a new context, bctl-agent-context, which when set as the current-context, allows for local Kubernetes tools to talk with the bctl daemon. The bctl daemon forwards all Kubernetes API calls to the currently connected Kubernetes cluster (see connect command).
zli generate kubeYaml <clusterName> (Registration):
zli generate kubeYaml <clusterName> creates a Kubernetes .yaml file that can be applied via kubectl apply to a cluster the user wishes to register with BastionZero. See the following article for more information on using YAML.
zli generate sshConfig:
zli generate sshConfig creates an SSH config file based on the targets to which you have SSH tunnel access, so that your connection to those targets can be proxied through BastionZero. Specifically, it will write to a new file (stored by default in $HOME/.ssh/bz-config), and link it to your existing configuration (by default in $HOME/.ssh/config) via the Include keyword. After this file is generated, you will not need to provide an identity file or proxy command when SSHing to your BastionZero targets.
zli generate bash:
zli generate bash generates a bash script that is used to autodiscover an SSM target. The script should be executed on the target machine to connect with BastionZero.
zli generate ssh-proxy:
zli generate ssh-proxy generates an ssh configuration block to be added to the user's ssh_config file. The generated configuration block allows the ssh command to tunnel SSH connections to SSM targets by calling the zli's ssh-proxy command behind the scenes.
This command only needs to be executed once, with the user taking the actions as specified in the output of the command to modify their ssh_config ($HOME/.ssh/config) file. After doing so, the user may utilize SSH tunneling by using ssh and specifying the correct hostname prefix (i.e., bzero-*).
See the following article for more information.
Options
--customPort: Configures the bctl-agent-context to connect to the bctl daemon server on a different port than the one currently listed in the user's local configuration.
-o, --outputFile: Writes the generated configuration to a file on the user's machine.
--update: Updates the user's existing kubeconfig file (defaults to $HOME/.kube/config unless KUBECONFIG is set). Requires kubectl to be installed on the user's machine and exist in their $PATH.
--labels: Comma separated list of Kubernetes labels to add to the bctl-agent deployment that is installed when registering a cluster with BastionZero.
--environmentName: Sets the BastionZero environment this cluster should be added to once registered.
--namespace: Sets the namespace for all bctl-agent-related Kubernetes objects that are created during registration and used during the lifetime of the agent.
--mySshPath: (only used with generate sshConfig) specify an alternate location for your personal SSH config file
--bzSshPath: (only used with generate sshConfig) specify an alternate location for the BastionZero config file to be written
-e, --environment: (only used with generate bash) Specifies the environment the target will belong to once registered. Defaults to the Default environment if this flag is not provided.
--agentVersion: (only used with generate bash) Use a specific version of the agent when installing the agent on the target. Defaults to the latest version if this flag is not provided.
-o, --outputFile: (only used with generate bash) Writes the bash script to a file on the user's machine.
--targetNameScheme: (only used with generate bash) Configures the target name from a specific source. Defaults to the hostname source if this flag is not provided.
do: If the target machine is a DigitalOcean droplet, the target name will be set to the droplet's name.
aws: If the target machine is an AWS EC2 machine, the target name will be set to the instance's ID.
time: The target name will be set to target-%m%d-%H%M%S, where the variables are date formats. The formatted timestamp is the time the script is executed on the target machine.
hostname: The target name will be set to the machine's hostname.
Examples
zli generate kubeYaml testcluster
zli generate kubeYaml --labels testkey:testvalue
zli generate kubeConfig
zli generate kubeConfig --update kube config - Defaults KUBECONFIG to $HOME/.kube/config
zli generate sshConfig - Create and link an ssh config file based on your organization's policies
zli generate sshConfig --mySshPath path/to/config --bzSshPath path/to/bz-config - Optionally specify filepaths (defaults to $HOME/.ssh/config and $HOME/.ssh/bz-config respectively)
zli generate bash --targetNameScheme time
zli generate bash -o script.sh - Writes the script to a file "script.sh" in the current directory
zli generate ssh-proxy
logout
Synopsis
1
zli logout
Copied!
Description
The logout command de-authenticates the client. The user must run login again to be able to run other zli commands.
Options
There are no options for this command besides the global ones.
kube
Synopsis
1
zli kube -- <kubeCtlArg> ...
Copied!
Description
The kube command passes all the supplied <kubeCtlArg> arguments to the kubectl CLI tool.
The user should not run this command unless the following requirements have been met:
The bctl daemon must be running and connected to a Kubernetes cluster (see connect command).
kubectl must be installed on the user's machine and exist in their $PATH.
The user's current-context configured in their kubeconfig file should be set to the bctl context (see zli generate kubeConfig).
Options
There are no options for this command besides the global ones.
User Guide - Previous
Troubleshooting Guide
Getting Help
Last modified 29d ago