The jaia command line tool aims to be the single entry point for all advanced configuration and administration of JaiaBots and Hubs.
The jaia tool has numerous actions (some of which have subactions of their own). To see the full list of actions available, type:
To see the options of an action, you can type (for example, the version action):
This works recursively for any child action, e.g.,
Many of the actions (jaia ip, jaia ping, jaia ssh) act on another (remote) host (Bot or Hub). The remote host is specified using a shorthand that encodes the host type (bot or hub), ID, network, and fleet ID.
At its simplest the shorthand is bNfM for Bot N on fleet M or hIfJ for Hub I on Fleet J. This uses the local network for fleet operations.
Bots or Hubs may be connected via the Cloud (see the Cloud Computing page for more details) or via the service VPN for remote support. In these cases a character before the fleet 'f' is used to indicate the network in use:
Thus, Bot 5 on VirtualFleet 3 would be b5vf3, or (real) Hub 1 Fleet 10 via the Cloud would be h1cf10. For servicing hosts remotely, Bot 2 on Fleet 4 would be b2sf4.
This section written by Claude
Additionally, if you are on a bot or hub, you can omit fN and the current fleet will be used. The fleet is taken from the jaia_fleet_id environmental variable, which login shells pick up from /etc/profile.d/jaia.sh (which reads /etc/jaiabot/jaia.env, written from the debconf database when jaiabot-embedded is configured). Where no profile has been sourced — for example under cron or ssh <host> <command> — the fleet is read from the hostname instead (hub0-fleet3).
This section written by Copilot
The host shorthand format is b<bot_id>[svc]f<fleet_id>, h<hub_id>[svc]f<fleet_id> or chf<fleet_id> (for CloudHub); the f<fleet_id> portion may be omitted as described above. Parsing is implemented in jaiabot::parse_host_code (src/lib/utils/ip.h).
Several special cases exist for the host string:
These related commands provide remote functionality using host codes given above.
jaia ip <host> simply gives the IP address for a given host code, e.g.,
This section written by Claude
jaia ip is a thin wrapper around the standalone jaia_ip binary, which can also be run directly (jaia_ip b1sf2). jaia_ip does not load the jaia tool (or goby/protobuf) and so starts up considerably faster; prefer it in scripts and other non-interactive callers that query many addresses. jaia_ip additionally supports an explicit query mode (jaia_ip --query_type net --fleet_id 3 --ip_net fleet_vpn); see jaia_ip --help. Both modes give the address in whichever IP version the fleet uses on the network asked for; --ip_version ipv4 or --ip_version ipv6 asks for one in particular, and works with a host code too (jaia ip b5sf3 --ip_version ipv6). The rest of the explicit mode flags cannot be combined with a host code, which already names the node, its fleet and its network.
jaia ssh uses the same codes but runs ssh to remotely log into the given system. Any parameters passed after the host code is passed unmodified to SSH:
jaia ping is just like jaia ssh but runs ping to check connectivity to a host. Similarly, all parameters after the host code are appended to the ping command line unmodified.
On a given system the version action provides the software version of the jaiabot code and its primary dependencies (Goby, MOOS, IvP, etc.).
As usual, jaia help version gives the full set of options.
Keep in mind that you can pair jaia ssh with any command to execute it remotely. For example, to see the versions of jaiabot and friends running on CloudHub for Fleet 1:
jaia status provides a summary of the systemd status of the JaiaBot services (this is the same output you receive on the SSH login MOTD).
This is a thin wrapper around systemctl for jaiabot services.
As always, you can use jaia ssh to execute remotely, e.g. to restart all services on Bot1 for Fleet10:
This section written by Copilot
jaia doc provides command line access to this documentation (Markdown). Run with no arguments to list all the available pages, or provide a page name to display it in the terminal.
This section written by Copilot
These subactions are used to administer a fleet of JaiaBots:
This section written by Claude
The bot, hub and fleet id ranges are defined once, in src/lib/utils/ip.h, and this subaction is how a caller outside that header asks what they are rather than hardcoding them:
ipv4 fleet id is the part of the fleet id range that is addressed with IPv4 on the fleet WLAN and fleet VPN; the rest is addressed with IPv6 on every network (see Cloud Computing).
Pass one or more ids to narrow the output (--bot_id, --hub_id, --fleet_id, --ipv4_fleet_id, --desktop_id, --gateway_id, --rpicam_id), and --min or --max to select one end. A single id that comes out as a single number is written bare, so a script can use it directly:
cloudhub id is the odd one out: the CloudHub is always hub 30, on every fleet, so it is one id rather than a range and --cloudhub_id on its own already gives a bare 30.
--format json gives the same information as an object, as elsewhere in the tool:
As with jaia ip, this is a thin wrapper around a standalone binary (jaia_bounds) that does not load goby/protobuf; prefer calling that directly from scripts. jaia-update-dns.sh uses it to enumerate the fleet's names.
This section written by Claude
The jaiabot-embedded debconf database is the single source of truth for a bot or hub's configuration, and the generated systemd units are derived from it. This subaction reads and writes it without having to go through the interactive dpkg-reconfigure menus. Questions are named without the jaiabot-embedded/ prefix.
Reading and writing the debconf database requires root, so get and set re-run themselves under sudo when they are not already root - there is no need to remember to prepend it. (list does not, since it does not read the database.)
get with no question reports what everything is currently set to, which is the counterpart to list's "what can I set?":
Questions that have never been answered show as (unset), which is distinct from one deliberately set to the empty string. Unlike jaia-debconf.sh selections - which emits debconf-set-selections format for another machine to re-import - this is meant for reading.
--format json gives the same information in a form a machine can read, which is how the Ansible playbooks (config/ansible/tasks/read-debconf.yml) learn what a bot or hub is configured as. Unanswered questions are null:
A single question in JSON gives an object with just that entry (jaia admin debconf get fleet_id --format json).
list shows every question the package defines, along with its type, default and permitted choices - that is, what you can pass to get and set:
list reads the package's templates rather than the debconf database, so it describes what can be set. Both list and a bare get take --all, which also shows the internal debconf_state_* questions - those record where the interactive menu is rather than any configuration.
set validates the value against that question's permitted Choices, so a typo fails immediately rather than silently generating the wrong services. The bot_id, hub_id and fleet_id questions have too many valid answers to list as choices, so they are strings whose ranges are checked against jaia admin bounds instead. By default it then runs dpkg-reconfigure jaiabot-embedded, which regenerates and re-enables the systemd units so the change takes effect.
When changing several values, skip the reconfigure on all but the last so the units are only regenerated once:
As with any action, these can be run remotely: