ZLI Reference Manual
Overview
The BastionZero zli
is an exec level command line interface (CLI) that provides users the ability to connect to their targets. Administrators may also manage aspects of their BastionZero organization through the zli
, such as creating and updated policy.
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 zli
.
All commands are case-insensitive (e.g., zli login
is the same as zli LoGiN
).
Global Flag Options
The zli
includes a few global options that can be used with any command.
Command Manual
The following section documents each zli
command listed in the overview above.
Use zli help
for general command guidance or zli <command> --help
if you need additional information on a specific command.
Command arguments key:
<arg>
is required[arg]
is optional or in certain cases, may be required
agent
agent
The agent
command allows administrators to directly view and manage the agent software running on resources secured by BastionZero.
Synopsis
Description
The agent list
command lists all the organization's agents. Optional result filters can be applied by passing in flags as described below. The returned table includes the type, name, environment, and version of all agents by default, but other data can be shown.
Alias: la
Options
--by
: Group agents by a specific attribute; defaults totype
. Usezli la --help
to see full list of attributes.--desc
: Reverse the sorting applied with--by
--range
: Display a subset of results (e.g.1-100
). The first result has an index of 1. End index is inclusive.-t
,--type
: Filter on one or more agent types. Usezli la --help
to see full list of valid agent types.-e
,--env
: Filter on environment name, including substring match.-n
,--name
: Filter on agent name, including substring match.--status
: Filter on one or more agent statuses. Usezli la --help
to see full list of valid statuses.--uuid
: Filter on one or more agent UUIDs.-d
,--detail
: Returns extra detail in the output. The additional information includes the agent's status and region.-i
,--showId
: Display the agent's UUID in the output.-j
,--json
: Output the list of agents in JSON format.
Examples
zli la -t windows linux
- List all Windows and Linux agentszli la -i
- List all agents and show unique idszli la -n ubuntu --status online terminated
- List all agents whose name contains the string "ubuntu" that are online or terminatedzli la --by region
List all agents grouped by regionzli la --by region --range 100-200
List all agents grouped by region. Only display the 100th to 200th agentzli la -e prod --json --silent
- List all agents in prod, output as json, pipeable
Description
The agent restart
command causes an agent to gracefully shut down and restart itself. This can be used as a failsafe measure in case the agent is still communicating with BastionZero but is not accepting user connections.
Example
zli agent restart myLinuxAgent
- Restart the agent called "myLinuxAgent"
Description
The agent configure
admin-only command can be used to modify an agent's loglevel
. After you configure a new log level, you will need to restart the agent for the changes to take effect (zli agent restart <agent name>
).
Configuring log level will require zli
version >= 6.34.0
and agent version >= 8.2.0
.
Example
I'm an admin and I want to set the log level of bzero-agent
to trace
. I would run:
zli agent configure bzero-agent loglevel trace
zli agent restart bzero-agent
attach
attach
Synopsis
Description
The attach
command attaches to an open zli
connection. All connections are created when using the connect
command.
Options
See global options.
authorized-action
authorized-action
Synopsis
Description
Authorized-action
is an admin only command that manages the authorized Github Actions that can approve a JIT policy.
zli authorized-actions create <githubActionId>
authorizes the specified Github Action to be able to grant temporary access.
The Github Action ID structure follows the format: repo:{Github organization name}/{Github repository name}:ref:refs/heads/{Github branch}
. For example, zli authorized-action create repo:bastionzero/circle-ci-sa-example:ref:refs/heads/custom-runner
allows an action that lives in the Github organization bastionzero
, in the Github repository circle-ci-sa-example
, in the branch custom-runner
to create expiring JIT policies.
Options
See global options.
close
close
Synopsis
Description
The close
command closes an open shell, db, or Kube connection. A connection that has been closed can no longer be attached to.
Options
-a
,--all
: Closes all shell, db, and kube connections-t
,--type
: Filter for specific connection type when using the--all
flag
completion
completion
Synopsis
Description
Note: This auto-completion feature is only supported by yargs for bash and zsh shells.
The completion
command will generate an auto-completion script for the user to put into their shell configuration. The script will provide the user with installation commands that they may use. For example, if the user is using a zsh shell, the outputted script will look like the following:
Then run the following commands:
zli completion >> ~/.zshrc
source ~/.zshrc
If tab completion does not take effect after running the commands above, restart your terminal.
What does it do?
Pressing tab will attempt to complete the command, subcommand, or optional/required flags
If no command or flag exists with the specified prefix, then nothing happens
If there is more than one command or flag with the specified prefix, I.e the user enters
zli log
and hits tab, then all options that start withlog
will be presented to the user (zli login
andzli logout
). By continuing to press tab, the user will infinitely rotate through the presented options. Press space to pick one.If the user enters
zli li
, then it will autocompletezli list-
because both commands have this in common. Then, hitting tab again will listzli list-connections
andzli list-targets
When just
zli[space]
is entered, hitting tab will then show the commands alphabetically and rotate through them as the user keeps hitting tab.
Options
See global options.
configure
configure
Synopsis
Description
The configure
command returns the file path of both the zli
's configuration directory and the logs kept as part of normal client operation. These files do not need to be modified by a user.
zli configure default-targetuser [targetUser] [--reset]
allows the user to set a default target user for shell, SSH, and SCP.
For shell connections, if a target user is not set in the target string (i.e
bzerotarget.environment
), and the user configures a default target user using this command, then the zli will automatically use the set target user.For SSH and SCP, you will need to run this command in conjunction with
zli generate sshConfig
. If you have a default target user set, then when you runzli generate sshConfig
, it will overwrite theUser
field for all your configurations with the default configuration. To undo this or revert to original configuration, reset the default target user usingzli configure default-targetuser --reset
and then runzli generate sshConfig
.In all cases, if you set a target user in the target string (i.e
someuser@bzerotarget.environment
), then you will connect with this target user and not the default.
You must exclusively set the targetUser
or use the --reset
option. You cannot do both or neither.
Options
-r
,--reset
: Reset the local default target user for shell, SSH, and SCP
zli configure get [key]
allows the getting of values from the zli
's internal store.
These values are not verified against expected keys. When encountering an unknown or known but unset key, the resulting value will be
undefined
.
zli configure set [key] [value]
allows the setting of values to the zli
's internal store.
For users wishing to use a static callback port when launching the login page from the
zli
onzli login
, can set it using the following command:zli configure set callbackPort [port]
connect
connect
Synopsis
Description
The connect
command opens a connection to any type of target as indicated by the targetString
. The exact behavior depends on the target's type; connecting to a Shell
target spawns an interactive terminal window, while other target types open a portforwarding connection that integrates with other client applications (kubectl
, RDP, SSMS, etc).
You can connect to all available targets of a given type by omitting the targetString
and specifying a --targetType
. Currently this is only supported for Kubernetes targets (see examples).
In addition to the connect features listed in the following sections, the targetString
can specify the environment of the destination target. This argument is optional and is meant to allow a user to distinguish between two targets with the same name that are in different environments.
The targetString
can be in the format targetName.environmentName
or targetName.environmentId
.
targetName
: The name of the target. (Name of Linux/Windows target, Kubernetes cluster, Web target, or Db target)environmentId
/environmentName
: The ID or name of the destination target's environment.
There are two ways to connect to targets that were named before zli v.6.7.3
and contain one or more periods:
Use the target id. Find the target id by executing
zli lt -i
Use the target name as is. As long as the string after the first period is not also an environment name, the intended connection request will succeed. If for example, the target name is
example.target.name
andtarget.name
is not an environment, thenzli connect example.target.name
will succeed.
Other options to disambiguate targets: The user can use the --targetType
flag to disambiguate targets with the same name of different types. The user can also use the corresponding target ID instead of the target name. To list targets with their target IDs, run the command zli lt -i
.
The logged-in zli
user must still have the appropriate policies in place in order to connect. For Kubernetes, the user must have a Kubernetes policy that covers this targetUser
and target combination. For Web and Db targets, the user must have a Proxy policy that covers this targetName
.
When connecting to Kubernetes targets:
The targetString
must be in the format targetUser@targetName
:
targetUser
: The Kubernetes RBAC user to impersonate as. All Kubernetes API calls forwarded by thebctl
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.
Connecting to all Kubernetes targets in a single command:
When connecting with zli connect -t kubernetes
, the ZLI attempts to open a connection to every Kubernetes target you can access according to your organization's policies. For each target, a unique connection is opened for every available target user. You can switch between connections by updating your current Kube context.
See here for more details and helpful tips on connecting to Kubernetes targets.
When connecting to Web, DB and RDP targets:
The targetString
must be in the format targetName
:
targetName
: The name of the Web or DB or RDP target.
For Web or DB targets, the logged-in zli
user must have a Proxy policy that covers this targetName
.
For RDP targets, the logged-in zli
user must have a TargetConnect policy that allows the RDP
verb.
For Kubernetes, Web, DB and RDP 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, Microsoft Remote Desktop
etc.)
For Windows users, connecting to an RDP or SQL Server target automatically launches an appropriate desktop application to facilitate the connection. This default behavior can be disabled with zli configure set noAppStart true
.
Options
-t
,--type [dynamic, kubernetes, linux, windows, web, db]
: Specifies the type of target the connection is for.--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.--namespace
: For Kubernetes connections only, specifies the default namespace to use when creating the Kubernetes context for this connection. Certain Kubernetes tools, such askubectl
, support this parameter and use it as the default namespace before issuing any requests to a cluster. If unspecified,default
is used as the default namespace.--customPort
: Forces thebctl
daemon to run on a specific port.--noAppStart
: Connect to the target without launching a related application (applicable to Windows users making RDP and SQL Server connection)
Examples
zli connect admin@my-target
- Connect as UNIX useradmin
to the Linux targetmy-target
.zli connect -t kubernetes
- Connect as all available users to all available Kubernetes targets.zli connect my-target
- Connects as a default UNIX user if only exactly one is allowed by policy to the targetmy-target
.zli connect my-rdp-target
- Creates an RDP connection if one is allowed by policy to the targetmy-rdp-target
.zli connect john@1d3a89b0-1c99-46c2-b411-e5e21261e40f
- Connect as UNIX userjohn
to a target by referring to its unique UUID.zli connect ec2-user@my-dat-config --targetType dynamic
- Connect to a DAT backed by themy-dat-config
Dynamic Access configuration.zli connect alice@my-cluster --targetGroup system:masters
- Start thebctl
daemon and connect it tomy-cluster
as Kubernetes RBAC useralice
and RBAC groupsystem:masters
.zli connect ec2-user@bzero-target.environmentName
- Connects as UNIX userec2-user
to the targetbzero-target
in the environmentenvironmentName
.zli connect bzero-target.1d3a89b0-1c99-46c2-b411-e5e21261e40f
- Connects as default UNIX user to the targetbzero-target
in the environment1d3a89b0-1c99-46c2-b411-e5e21261e40f
.
default-targetgroup
default-targetgroup
Synopsis
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.
disconnect
disconnect
Synopsis
Description
The disconnect
command closes a zli
daemon (db, web or kube, rdp). You may specify closing a specific daemon type by using the targetType
positional with a value of kube, db, rdp, or web. By default, this command will close all open zli
daemons.
Options
See global options.
generate
generate
Synopsis
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
contains a context entry (bzero-{role}@{clusterName}
) for each open Kube connection running on the user's machine. The contexts allow for local Kubernetes tools to talk with the bctl
daemon. The bctl
daemon forwards all Kubernetes API calls to the respective Kubernetes cluster depending on which context is selected as the current one.
The zli generate kubeConfig
command is not required in order to connect. When you run zli connect
to your Kubernetes targets, the zli
automatically updates your kubeconfig
file for you. The generate kubeConfig
command exists in case you've accidentally modified a BastionZero-managed entry in your kubeconfig
and you want to reset it to its original declaration (zli generate kubeConfig --update
), or if you need to output a kubeconfig
containing only BastionZero-managed contexts (useful when interacting with Kubernetes SDKs).
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.
zli generate sshConfig
:
zli generate sshConfig
creates an SSH config file based on the targets to which you have SSH tunnel and file transfer 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/bzero-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.
Starting in zli
version 6.8.5, your /.ssh/config
and bzero-bz-config
files now provide context for users to quickly understand the contents of the file. To update your configuration files to include these new descriptions, re-run zli generate sshConfig
.
zli generate bash
:
zli generate bash
generates a bash script that is used to autodiscover a Linux target. The script should be executed on the target machine to connect with BastionZero.
zli generate powershell
:
zli generate
powershell
generates a Powershell script that is used to autodiscover a Windows 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-*
).
zli generate certificate
:
zli generate certificate
configures one or more database targets for SplitCert access. A new certificate with a corresponding split private key is created, and one of the key shards is distributed to the proxy targets linked to each database target. The proxy target must be online for this to work. The user is warned if any of the database targets they try to configure is unavailable.
Note that executing this command creates at most one certificate, shared by every database target specified by the user. If the command is run multiple times, a new certificate and split key are created. Any database target affected by multiple generate certificate
calls will only be accessible using the most recent certificate created for that database.
For example, suppose there are two database targets, A
and B
. If the user runs zli generate certificate --all
, both databases will be accessible using the same certificate. If the user subsequently runs zli generate certificate --targets A
, then target B will be accessible using the first certificate, but target A will only be accessible using the second certificate.
Options
--update
: Updates the user's existingkubeconfig
file (defaults to$HOME/.kube/config
unlessKUBECONFIG
is set). Requireskubectl
to be installed on the user's machine and exist in their$PATH
.--force
: Force generates new Kube daemon security settings. WARNING: Disconnects any running Kube daemons--labels
: Comma separated list of Kubernetes labels to add to thebctl-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 allbctl-agent
-related Kubernetes objects that are created during registration and used during the lifetime of the agent.--mySshPath
: (only used withgenerate sshConfig
) specify an alternate location for your personal SSH config file--bzSshPath
: (only used withgenerate sshConfig
) specify an alternate location for the BastionZero config file to be written-e
,--environment
: If used withbash
, specifies the environment the target will belong to once registered. Defaults to theDefault
environment if this flag is not provided. If used withcertificate
, optionally disambiguates a database target name--beta
: (only used withgenerate bash
) Use the latest beta release of the agent, instead of the latest production release-o
,--outputFile
: (only used withgenerate bash
) Writes the bash script to a file on the user's machine.--targetNameScheme
: (only used withgenerate bash
) Configures the target name from a specific source. Defaults to thehostname
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 totarget-%m%d-%H%M%S
, where the variables aredate
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'shostname
.
--targets
: (only used withgenerate certificate
) One or more database target names or IDs to which the certificate will authenticate--all
: (only used withgenerate certificate
) if set, the certificate will authenticate to all of your current database targets. If any targets cannot be configured, you will be asked whether to only configure the available targets-y
,--yes
: If set along with--all
, automatically respond affirmatively if prompted--selfHosted
: (only used withgenerate certificate
) if set, the server cert and server private key will be returned; you will use these when configuring your database--agentKey
: (only used withgenerate certificate
) if set, returns a copy of the RSA key shard sent to the targets; you can use this data to configure other proxy targets to access the database--outputDir
: only used withgenerate certificate
) Provide a directory into which all output files will be written. If none provided, will create a unique directory in the current working directory
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/configzli generate sshConfig
- Create and link an ssh config file based on your organization's policieszli 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 directoryzli generate certificate --all --selfHosted
- Generate a root certificate and configure all available database targets; returns extra data to configure any self-hosted targetszli generate certificate --targets target1 target2
- Generate a root certificate and configure target1 and target2
kube
kube
Synopsis
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:
kubectl
must be installed on the user's machine and exist in their$PATH
.The user's
current-context
configured in theirkubeconfig
file should be set to a BastionZero-managed context (seezli generate kubeConfig
or here for more information).
Options
See global options.
list-agents
list-agents
See zli agent list
list-connections
list-connections
Synopsis
Description
The list-connections
command lists open shell, db, and Kube connections the logged-in zli
user has made across all their machines.
Alias: lc
Options
-j
,--json
: Output the list of connections in JSON format.-t
,--type
: Filter for a specific connection type.
list-daemons
list-daemons
Synopsis
Description
The list-daemons
command lists all daemons running on this machine.
By default, all types of daemons are displayed. Appending the target type after list-daemons
filters for a specific daemon type.
Alias: ld
Options
See global options.
list-targets
list-targets
See zli target list
login
login
Synopsis
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.
logout
logout
Synopsis
Description
The logout
command de-authenticates the client. The user must run login
again to be able to run other zli
commands.
Options
See global options.
policy
policy
Synopsis
Description
The policy
commands allow the user to list existing policies and their BastionZero users, SSO groups, target users and target groups, update these fields for a specific policy, and create a new cluster, target connect, session recording, or proxy policy.
zli policy list [--type <policyType>]
returns the existing policies in the user's organization. These policies can also be filtered by type using the --type flag.
zli policy describe-cluster-policy <clusterName>
returns detailed information about what policies apply to the <clusterName>
cluster.
If you desire to author or modify a policy with spaces in the name, you must wrap the name in double quotes.
zli policy create-cluster [name][users][groups][clusters][environments][targetUsers][targetGroups]
creates a new cluster policy.
Note:
When creating a cluster policy, the following flags are required:
<name>
: Name of the policy
<users>
: SSO emails of users for the policy
<clusters>
OR <environments>
: Resources for the policy (must exclusively provide one).
The following flags are optional:
<groups>
: SSO groups for the policy
<targetUsers>
: Allowed target users for the policy
<targetGroups>
: Allowed target groups for the policy
<description>
: Description of the policy
You can use the resource UUID instead of name for the <clusters>
and <environments>
options.
zli policy create-tconnect [name][users][groups][targets][environments][targetUsers][verbs]
creates a new target connect policy.
Note:
When creating a target connect policy, the following flags are required:
<name>
: Name of the policy
<users>
: SSO emails of users for the policy
<targetUsers>
: Allowed target users for the policy - Optional only when the only verb specified in the policy is RDP
<verbs>
: Actions allowed by the policy. Choices: "shell", "tunnel", filetransfer", or "rdp"
<targets>
OR <environments>
: Resources for the policy (must exclusively provide one).
The following flags are optional:
<groups>
: SSO groups for the policy
<description>
: Description of the policy
You can use the resource UUID instead of name for the <targets>
and <environments>
options.
BastionZero supports connecting to Linux targets using the IdP username as the target user through the use of substitution parameters. For information on how to set up substitution parameters in target connect policies, navigate to our policy management page. For information on how to connect to your Linux targets using IdP username as the target user, navigate to our connecting to your targets page.
zli policy create-recording [name][users][groups][recordInput]
creates a new session recording policy.
Note:
When creating a session recording, the following flags are required:
<name>
: Name of the policy
<users>
: SSO emails of users for the policy
The following flags are optional:
<groups>
: SSO groups for the policy
<recordInput>
: Boolean indicating input should be recorded (any argument that is not "true" will be interpreted as false i.e "tru" equates to false)
<description>
: Description of the policy
zli policy create-proxy [name][users][groups][targets][targetUsers][environments]
creates a new proxy policy.
Note:
When creating a proxy policy, the following flags are required:
<name>
: Name of the policy
<users>
: SSO emails of users for the policy
<targets>
OR <environments>
: Resources for the policy (must exclusively provide one)
The following flags are optional:
<targetUsers>
: Allowed target users for the policy -- note that this is only used for SplitCert and passwordless database access, and is ignored for other types of proxy access
<groups>
: SSO groups for the policy
<description>
: Description of the policy
You can use the resource UUID instead of name for the <targets>
and <environments>
options.
zli policy users
zli policy users
zli policy users
returns the BastionZero users in the organization. The returned table includes the user's name, the user's <idpEmail>
, role in BastionZero (admin or user), and time of last login.
zli policy add-user <policyName> <idpEmail>
adds the specified SSO user to the specified policy.
zli policy delete-user <policyName> <idpEmail>
deletes the specified SSO user from the specified policy.
Note: When adding or deleting a user from a policy, both <policyName>
and <idpEmail>
must be provided. <policyName>
should refer to a policy that exists in the list of the organization's policies. To list all policies, you can run the zli policy list
command and optionally use the --type
flag to specify a policy type. <idpEmail>
should refer to the email of one of the organization's users.
zli policy groups
zli policy groups
zli policy groups
returns the organization's SSO groups. The returned table includes all of the organization's groups by name.
zli policy add-group <policyName> <groupName>
adds the specified SSO group to the specified policy.
zli policy delete-group <policyName> <groupName>
deletes the specified SSO group from the specified policy.
Note: When adding or deleting a group from a policy, both <policyName>
and <groupName>
must be provided. <policyName>
should refer to a policy that exists in the list of the organization's policies. To list all policies, you can run the zli policy list
command and optionally use the --type
flag to specify a policy type. <groupName>
should refer to the name of one of the organization's groups. <groupName>
is case sensitive.
zli policy targetusers
zli policy targetusers
zli policy targetusers <policyName>
returns the target users for a specific policy. Target users determine what UNIX users or Kubernetes RBAC users are permissible to use in the connect
and tunnel
commands respectively.
zli policy add-targetuser <policyName> <targetUser>
adds the specified target user to the specified policy.
zli policy delete-targetuser <policyName> <targetUser>
deletes the specified target user from the specified policy.
Note: When adding or deleting a target user from a policy, <targetUser>
must be provided. When editing a Target Connect policy, <targetUser>
refers to a UNIX username - that username is ignored in the RDP case. When editing a Kubernetes Access policy, <targetUser>
refers to a Kubernetes RBAC user.
zli policy targetgroups
zli policy targetgroups
zli policy targetgroups <policyName>
returns the target groups for a specific policy. Target groups determine which Kubernetes RBAC groups are permissible to use in the connect
command. This command only applies to Kubernetes Access policies.
zli policy add-targetgroup <policyName> <targetGroup>
adds the specified target user to the specified policy.
zli policy delete-targetgroup <policyName> <targetGroup>
deletes the specified target user from the specified policy.
Note: When adding or deleting a user from a policy, <targetGroup>
must be provided. <targetGroup>
refers to a Kubernetes RBAC group.
Options
-j
,--json
: Output the list of policies, users, groups, target users, or target groups in JSON format. Not applicable todescribe-cluster-policy
.
Examples
zli policy list --json --silent | jq
- List all policies. Output as JSON. Pipe intojq
for pretty formatting.zli policy list --type kubernetes
- List all Kubernetes policies. Regular table output.zli policy describe-cluster-policy test-cluster
- List all existing policies for test-cluster. Regular table output.zli policy create-cluster -n policy_name -u user@random.com -c test_cluster --targetUsers ec2-user
- Create a new cluster policy with the specified arguments.zli policy create-tconnect -n policy_name -u user@random.com -t bzero-target --targetUsers ec2-user -v shell
- Create a new target connect policy with the specified arguments.zli policy create-tconnect -n policy_name -u user@random.com -t rdp-target -v rdp
- Create a new target connect policy with the specified arguments.zli policy create-recording -n policy_name -u user@random.com -g Engineering Legal -r true
- Create a new session recording policy with the specified arguments.zli policy create-proxy -n policy_name -u user@random.com -g Engineering Legal -e test-environment
- Create a new proxy policy with the specified arguments.zli policy users --json --silent | jq
- List all of the organization's users. Output as JSON. Pipe intojq
for pretty formatting.zli policy add-user my-policy alice@org.com
- Adds SSO user with emailalice@org.com
to themy-policy
policy.zli policy delete-user my-policy bob@org.com
- Removes SSO user with emailbob@org.com
from themy-policy
policy.zli policy groups --json --silent | jq
- List all of the organization's groups. Output as JSON. Pipe intojq
for pretty formatting.zli policy add-group my-policy Engineering
- Adds SSO group with nameEngineering
to themy-policy
policy.zli policy delete-group my-policy Engineering
- Removes SSO group with nameEngineering
from themy-policy
policy.zli policy targetusers my-policy -j
- List all of the target users for a specific policy. Output as JSON, pipeable.zli policy add-targetuser my-policy ec2-user
- Adds a new target userec2-user
to themy-policy
policy.zli policy delete-targetuser my-policy ec2-user
- Removes the target user with nameec2-user
from themy-policy
policy.zli policy targetgroups my-policy -j
- List all of the target groups for a specific policy. Output as JSON, pipeable.zli policy add-targetgroup my-policy system:masters
- Adds a new target group with namesystem:masters
to themy-policy
policy.zli policy delete-targetgroup my-policy system:masters
- Removes the target group with namesystem:masters
from themy-policy
policy.
quickstart
quickstart
Synopsis
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.
The quickstart
command is only compatible with OpenSSH <= v. 8.8.
Options
-c
,--sshConfigFile
: Path tossh_config
file. Defaults to$HOME/.ssh/config
if this flag is not provided.
send-logs
send-logs
Synopsis
Description
The send-logs
compresses your local zli and daemon logs and sends them to BastionZero. This command also supports sending logs from a kube, linux, or windows target to BastionZero by using the target
or all
flags and entering the target's name or id. This command is useful if you are debugging an issue and need assistance.
We will receive all logs dating back to the previous day at 12:00am.
Options
-t
,--target
: Send logs for the specified kube, linux, or windows target. You can refer to the target using its name or id.-a
,--all
: Send logs for the specified kube, linux, or windows target in conjunction with your local zli and daemon logs.
service-account
service-account
Synopsis
Description
An admin only command to list, create, update and configure functionality for service accounts.
zli service-account list <providerCreds> [--bzeroCreds]
creates a new service account in the user's organization. Use <providerCreds>
to provide the relative/absolute path to your provider credentials json
file. Optionally, provide [--bzeroCreds]
to specify the path where the output BastionZero credentials will be stored. If not specified, the current path will be used. (Admin Only)
zli service-account configure [--target] [--all] [--serviceAccount]
configures one or more of your targets to be accessible by the specified service account. Also adds the pattern of the JWKS URL of this service account to the specified target(s). This way service accounts from the same domain will be pre-configured so you do not need to configure them as well. (Admin Only)
Note:
Upon registration of a target, all existing service accounts will be configured for convenience. Use this command to configure a target that is not already configured with a service account because the service account was created after the target's registration. Configuring an already configured target won't apply any changes.
When configuring a service account, the following flags are required:
[--serviceAccount]
: Email of the service account that will be added in the target(s)
[--all]
OR [--target]
: Targets that will be configured (must exclusively provide one of the flags). The [--target]
flag expects one or more comma separated target names or target IDs
zli service-account disable <serviceAccountEmail>
disables the specified service account so it cannot log in or take any other action. (Admin Only)
zli service-account disable <serviceAccountEmail>
enables the specified service account so it can log in again and take other actions. (Admin Only)
zli service-account list [--detail]
lists all service accounts in the user's organization. Use [--detail]
to see a detailed view of them, including their externalId
, JWKS URL
, JWKS URL Pattern
and enabled
status. (Admin Only)
zli service-account login [--providerCreds] [--bzeroCreds]
log in as the specified service account in the provider credentials file. Provide the path to your two roots of trust using the [--providerCreds]
flag to provide your relative/absolute path to your provider credentials json
file and the [--bzeroCreds]
flag to provide your relative/absolute path to your BastionZero credentials json
file.
zli service-account rotate-mfa <serviceAccountEmail>
rotates the MFA secret that is used as the specified service account's BastionZero credentials. Optionally, provide [--bzeroCreds]
to specify the output path for the new BastionZero credentials. If not specified, the current path will be used. (Admin Only)
zli service-account set-role <role> <serviceAccountEmail>
changes the role
of the specified service account. Acceptable values are admin
and user
. (Admin Only)
Examples
zli service-account create cool-service-account.json
- Create a new service account based off the provider credentials in cool-service-account.json and output a bzero-credentials.json file in the current directory.zli service-account create cool-service-account.json --bzeroCreds /mySecureFolder/my-bzero-creds.json
- Create a new service account based off the provider credentials in cool-service-account.json and output a my-bzero-creds.json file in the mySecureFolder directory.zli service-account configure --target my-cool-target --serviceAccount cool-service-account-email
- Configure agent my-cool-target to allow access to service accounts that follow the jwksUrl pattern of cool-service-account-email.zli service-account disable cool-service-account-email
- Disable service account cool-service-account-email. Applicable only if previously enabled.zli service-account enable cool-service-account-email
- Enable service account cool-service-account-email. Applicable only if previously disabled.zli service-account list
- List all service accounts, as regular table output.zli service-account list --json
- List all service accounts, output as json, pipeable.zli service-account list --detail
- List all service accounts, show all extra information.zli service-account login --providerCreds /path/to/providerCreds.json --bzeroCreds /path/to/bzeroCreds.json
- Login using a service account.zli service-account rotate-mfa cool-service-account-email
- Rotate the mfa shared secret of service account cool-service-account-email. Outputs a bzero-credentials.json file in the current directory.zli service-account rotate-mfa cool-service-account-email --bzeroCreds /mySecureFolder/my-bzero-creds.json
- Rotate the mfa shared secret of service account cool-service-account-email. Outputs a my-bzero-creds.json file in the mySecureFolder directory.zli service-account set-role admin cool-service-account-email
- Change the role of service account cool-service-account-email to admin. Allowed only if not an admin already.
Options
See global options.
ssh-proxy
ssh-proxy
Synopsis
Internal use only. This is not a user-facing command and is used by the BastionZero service to create SSH connections. When using SSH with BastionZero, you should always use native commands (ssh
, scp
, sftp
).
Description
The ssh-proxy
command allows for proxying an SSH connection to a 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 target's name or UUID in the case there are two or more targets with the same name. <userName>
is the UNIX username to log in as. <portNumber>
refers to the port number on the 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 Connecting to Your Targets for more information.
Some quick background on using SSH with BastionZero
To provide a seamless experience when using BastionZero for SSH workflows, BastionZero creates and maintains its own IdentityFile
and KnownHostsFile
. These files are no longer needed for security due to BastionZero's security model, but they are still necessary to conform to the SSH protocol.
By maintaining a BastionZero-specific copy of the KnownHostsFile
, BastionZero can rotate credentials frequently (no more long-lived credentials!) without requiring users to edit this file manually. In fact, as part of the BastionZero protocol, the KnownHostsFile
is overwritten during every connection. The IdentityFile
is based on your current session with the zli
.
Options
See global options.
target
target
Synopsis
Description
The target list
command lists all targets that are available to you based on configured policy. If you are an admin, it lists all the targets in your organization unless you include the -u
option with a given user's email address. Optional result filters can be applied by passing in flags as described below. The returned table of targets includes the type, name, and environment by default, but other data can be shown.
Alias: lt
Options
--by
: Group targets by a specific attribute; defaults totype
. Usezli lt --help
to see full list of attributes.--desc
: Reverse the sorting applied with--by
--range
: Display a subset of results (e.g.1-100
). The first result has an index of 1. End index is inclusive.-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 usezli user
to list all users.-t
,--targetType
: Filter on one or more target types. Usezli lt --help
to see full list of valid target types.-e
,--env
: Filter on environment name, including substring match.-n
,--name
: Filter on target name, including substring match.--status
: Filter on one or more target statuses. Usezli lt --help
to see full list of valid statuses.--uuid
: Filter on one or more target IDs-d
,--detail
: Returns extra detail in the output. The additional information includes the target's agent version, status, region, 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 kubernetes
- List all Kubernetes cluster targets. Display the target's UUID.zli lt --by type --desc
List all targets by type in descending orderzli lt --by type --desc --range 100-200
List all targets by type in descending order. Only display the 100th to 200th targetzli lt --json --silent | jq
- List all targets. Output as JSON. Pipe intojq
for pretty formatting.zli lt --user roleaccount@bastionzero.com
- Lists all targets thatroleaccount@bastionzero.com
has access to through policy
Options
See global options.
Last updated