ctl: Bulk Import Commands

Adding many connections, users, groups or relays at once with ctl, instead of one at a time in the web UI. To read or export objects instead, see ctl: Bulk List Commands.

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.

ℹ First time using ctl?

This article assumes ctl is installed, pointed at your appliance and logged in. If it is not, work through ctl: Getting Started first - there is no username-and-password login, so the first API key has to be created in the web UI before ctl can log in at all.

⚠ There is no bulk permissions command

If what you need is “give this group access to 50 connections at once,” ctl cannot do it today - talk to your Xona representative. This article only covers creating connections, users, groups and relays.

Before you run a real import

• ☐ Your input file is a CSV (or JSON for X-Connections). Excel, Google Sheets and Numbers can all export .csv
• ☐ Test on a 2-3 row file first. It takes seconds and confirms your column names and formatting before you commit to a large import
• ☐ You know whether you are on a Gateway or an Manager - on a Manager most commands need one extra argument, see below
• ☐ You have read How a bad row is handled - the behaviour differs by object type and it matters

ctl <command> --help shows a command's exact options at any time.

At a glance

How a bad row is handled - read this before a large import

This is the single most important thing to know before importing onto a live system, because the two behaviours demand opposite preparation.

NO - Connections & X-Connections: all or nothing

50 rows, 1 problem - a duplicate name, a name already in use, a disallowed setting - and none of the 50 are created. Fix the row and re-run the whole file.

So: check for duplicate or already-existing names before running. One collision anywhere stops everything.

OK - Users, groups & relays: row by row

50 rows, 1 problem - that one is skipped and the other 49 are created. The output names which rows succeeded and which were skipped, and why.

So: read the output afterwards. A command that finishes cleanly does not mean every row landed.

Adding connections

The word after add-bulk-csv is the connection type: rdp, ssh, telnet, vnc or web.

These must match exactly: MyGatewayName

Column reference by connection type

Every type needs these three: name, showMonitorDialog (TRUE/FALSE), approvalLifetimeMin (minutes).

⚠ --help is wrong for non-RDP types

The built-in help text always prints the RDP column list, whichever type you are importing. Use the table above - it is accurate for every type.

You can leave username blank where a connection does not need one - an empty cell is fine, just do not remove the column. Any setting you omit a column for uses Xona's standard default (RDP connections, for example, default to clipboard access on), so you only need to specify what differs from the default.

Examples

These must match exactly: name,showMonitorDialog,approvalLifetimeMin,domain,hostname,manualLogin,password,port,username

These must match exactly: name,showMonitorDialog,approvalLifetimeMin,hostname,manualLogin,password,port,username

These must match exactly: name,showMonitorDialog,approvalLifetimeMin,appUrl

Adding users, and putting them straight into groups

These must match exactly: email,fullName,initialPassword,organization,username,groups and "Engineers,OnCall"

The groups column is optional per row - leave it blank, like Tom Clark, to create the user without any group. For more than one group, separate names with commas and quote the whole cell, like Bob Wong.

⚠ A group name that does not match is skipped silently - but the user is still created

The name must match an existing group exactly. A typo leaves you with a real user who is in none of the groups you intended, which is easy to miss. Verify your group names before a large import.

Adding groups

These must match exactly: name,adName,ssoName

adName and ssoName are optional - leave them blank for a group not tied to AD or SSO, like Contractors. name is required on every row.

Adding relays

These must match exactly: name,host,srcPort,dstPort,maxDurationMinutes,protocol,allowListIPs and "10.0.0.5,10.0.0.6"

Multiple allowed IPs go in the same allowListIPs cell, comma-separated, with quotes around the whole cell.

Adding X-Connections

This one takes JSON, not CSV, and there is no CSV option today. Ask your Xona representative for a template if you need one.

Formatting rules that apply to every command above