Configure kziti

Before running any operational command, kziti needs to know how to reach your OpenZiti controller. This page explains the configuration model and covers the commands for setting it up.

What a profile is

A profile is a named set of credentials that kziti uses to authenticate against one OpenZiti controller. Every profile contains:

• A path to an enrolled identity JSON file (the standard way), or
• A raw management API URL + cert/key pair (for environments where a pre-existing PKI manages the controller credential).

All operational commands (network, service, access, router, …) read from the active profile. Switching profiles switches the target controller entirely — there is no mixing of credentials within a single command.

One profile exists by default and is named default. Most operators running a single controller never need more than one.

First-time setup

The interactive wizard creates a new admin identity, enrolls it against the controller, and stores the resulting JSON file automatically:

kziti config init

It prompts for the controller URL, admin credentials, and an identity name, then writes a config file at ~/.config/kziti/config.toml.

For scripted or CI environments, use config set-ziti directly:

kziti config set-ziti \
  --host https://ziti.example.com:1280 \
  --user admin \
  --password '<admin-password>'

This runs the same enrollment flow non-interactively and updates the active profile. To point a profile at an existing identity file instead:

kziti config set-ziti --identity /path/to/existing-identity.json

Verify the connection:

kziti status

Multiple profiles

Use separate profiles when you have more than one controller — staging and production, multiple customer deployments, or a primary and DR controller.

Create a profile for a second controller

# Create a blank profile
kziti config profiles create staging

# Enroll a new identity against the staging controller into that profile
kziti config set-ziti \
  --profile staging \
  --host https://ziti-staging.example.com:1280 \
  --user admin \
  --password '<staging-password>'

Switch the active profile

All commands run against whichever profile is currently active:

kziti config profiles use staging
kziti network list   # now talks to the staging controller

kziti config profiles use default
kziti network list   # back to production

Use a profile for a single command

The global --profile flag overrides the active profile for one invocation without changing the persisted setting:

kziti --profile staging service list
kziti --profile staging access grant alice@example.com net-demo

This is useful in scripts where the caller controls which environment a command targets.

Clone a profile

To create a staging profile that starts from the same settings as production:

kziti config profiles create staging --from default
# Then update just the Ziti credentials
kziti config set-ziti --profile staging --host https://ziti-staging.example.com:1280 ...

View current configuration

kziti config show

Shows all profiles, which is active, and the connection settings for each (secrets redacted). For a single profile:

kziti config profiles show staging

Profile commands reference

Command	What it does
kziti config init	Interactive wizard — prompts for controller URL, credentials, and identity name
kziti config set-ziti --host … --user … --password …	Non-interactive enrollment — creates and enrolls a new admin identity
kziti config set-ziti --identity /path/to/file.json	Point a profile at an existing identity JSON file
kziti config show	Show all profiles and their settings
kziti config path	Print the config file path
kziti config profiles list	List profile names and indicate which is active
kziti config profiles create <name>	Create a new empty profile
kziti config profiles create <name> --from <other>	Clone an existing profile
kziti config profiles use <name>	Set the persistent active profile
kziti config profiles show <name>	Show settings for one profile
kziti config profiles delete <name>	Delete a profile (cannot delete the last one)

Config file location

The config file lives at ~/.config/kziti/config.toml by default, respecting XDG_CONFIG_HOME when set. When running under sudo, kziti resolves the path against the invoking user's home so that deploy commands (which require root) and operational commands (which do not) see the same config.

Enrolled identity JSON files are stored under ~/.config/kziti/identities/<profile-name>/.