ctl: Getting Started

Installing the ctl command-line tool and getting it talking to an appliance for the first time. Eight steps, start to finish, assuming you have never used it before.

Naming: this article uses the v5.5.4 product names - Gateway (formerly CSG) and Manager (formerly XCM). Appliances on older versions, and their documentation, use the old names for the same things.

Contents

1. Web UI - Make sure your account is allowed to use ctl
2. Your computer - Download and extract ctl
3. Your computer - Decide now whether you need --insecure
4. Your computer - Point ctl at the appliance
5. Web UI - Create a key on your Profile page
6. Your computer - Log in
7. Your computer - Prove it works
8. Your computer - Optional: turn on shell completion

What ctl is, and what it is not

ctl is a single executable you run on your own computer. It talks to an appliance's API over HTTPS and does the same administrative work you would otherwise do by clicking around the web UI - listing connections, adding users, checking status - except you can script it.

ℹ Three things worth knowing before you start

It does not install onto the appliance. You download it, put it on your laptop or a jump host, and point it at an appliance address.

It can do anything your account can do. ctl inherits your permissions exactly - no more, no less. An account with limited rights gets a limited ctl.

It is not the X-Connect Agent. Different tool, different job. Don't go looking for one in the other's documentation.

Before you start

• ☐ The address of the appliance you want to manage, and network access to it on TCP 443
• ☐ A user account on that appliance that you can log in to the web UI with
• ☐ That account holding the API Access system permission - step 1 covers this

1. Web UI - Make sure your account is allowed to use ctl

Your account needs the API Access system permission. Two shortcuts: the built-in admin account always has it, and members of the Admins group get it by default.

For anyone else, an administrator grants it under Settings → Security → Permissions. Without it, every ctl command fails no matter how correctly the rest of this article is followed.

2. Your computer - Download and extract ctl

Log in to the appliance's web UI and open its Help page. The platform bundles are published there.

Extract the bundle and put the ctl executable somewhere on your PATH, so you can run it by name from any directory. Then check it runs at all:

The bundle holds a single executable - there is nothing to install and no installer to run. The first ctl command you run, including ctl version, creates your config file at $HOME/.ctl.

3. Your computer - Decide now whether you need --insecure

Answer this before the next step, not after it. If the appliance is still using its factory default self-signed certificate, ctl refuses to trust it and every command fails the same way - including the one in step 4:

The fix is the --insecure flag, and you only have to pass it once - on the command in step 4. It is written into your config file and applies to everything afterwards, which is why the rest of this article shows commands without it.

⚠ Treat --insecure as temporary

It disables verification of the appliance's certificate, which is the check that proves you are talking to the appliance you think you are. Every command then prints WARNING: You have disabled TLS server certificate verification, which is your reminder that it is still on. The real fix is installing a CA-signed certificate on the appliance; then run the step 4 command again without the flag to clear the setting.

4. Your computer - Point ctl at the appliance

Assuming the appliance has a valid license installed, this also detects which type of appliance it is, and says so - switching product configuration to: XCM or : CSG. That matters, because the available subcommands differ between a Gateway and a Manager - if a command you expect is missing, check what you are pointed at before assuming the tool is broken.

Your settings are saved in $HOME/.ctl. If an older $HOME/.xonactl file exists and .ctl does not, that legacy file is used instead - which is how a machine that used the tool under its old name keeps working.

5. Web UI - Create a key on your Profile page

ctl does not log in with your password. It uses a key, and you create it in the web UI. Pick one of these.

Option A - API key (simplest, start here)

1. Log in to the web UI and open your Profile page
2. Press Add API Key
3. Press Copy Secret and paste it somewhere safe for the next step

Option B - SSH key

1. Generate an OpenSSH-compatible key pair, for example with ssh-keygen
2. On your Profile page, paste the public key (the contents of id_rsa.pub) into SSH Key 1
3. Press Save

⚠ Encrypted private keys are not supported

If you protected the private key with a passphrase, ctl cannot use it. Generate one without a passphrase, and protect the file itself instead.

⛔ These keys skip MFA - protect them accordingly

Key-based login does not issue a TOTP or WebAuthn challenge. That is by design, because scripts cannot answer one - but it means the key alone is enough to act as you. Store it like a password, rotate it on a schedule, and never commit it to a repository.

6. Your computer - Log in

Use the command that matches the key you created. Both take your username on that appliance.

⚠ Logging in stores the secret in clear text

A successful login writes your API key secret, session token and renew key into $HOME/.ctl as plain text, so later commands do not re-prompt. There is no ctl logout - to remove them, delete the file. Treat $HOME/.ctl as a credential: keep it off shared machines, and out of backups and repositories.

Logging in to a Gateway with a Manager account? Try your bare username first. If it is rejected, try it prefixed - MGR\jsmith, or XCM\jsmith for accounts created before v5.5.3. The bare form only works when no Gateway-local account already uses that same name, which is exactly why admin is the one that catches people out: every appliance has its own.

7. Your computer - Prove it works

A successful reply looks like this, and means everything above is correct - network path, address, permission, and key:

Then try a real read, which proves your permissions work and not just your login:

8. Your computer - Optional: turn on shell completion

Worth the two minutes - it makes the subcommands discoverable by pressing Tab instead of reading a manual. Completion is available for bash, zsh, fish and PowerShell.

Substitute bash, fish or powershell as needed; the appliance's own CLI documentation lists the exact install path for each shell.

If it does not work

Two habits to pick up early

Quote passwords, and use --. Special characters in a shell will otherwise mangle the value, and a password starting with - gets read as a flag:

Know what revoking a key actually does. There is no way to revoke one individual API key:

If that user has keys in more than one place - a script, a scheduled job, their laptop - all of them stop working at once. Plan the replacement before you run it.

Where to go next

• ctl: Bulk List Commands - Reading many objects at once instead of clicking through the web UI
• ctl: Bulk Import Commands - Adding connections, users, groups and relays in bulk

✓ You are set up when

ctl update info returns a version, and ctl conn list returns your connections. Everything else in the tool builds on those two working.