IO provides a terminal user interface (TUI) and a rich set of command-line tools over SSH. By default, these run on port 2200.
To connect to the TUI, use ssh HOST -p PORT.
To use the command-line tools, just append the command name. For example, here we use help to get a list of commands:
$ ssh alfa -p 2200 help
Usage:
ssh alfa -p 2200 -- [command]
Available Commands:
acme ACME subcommands
apply Apply structured configuration to entities
build Information about the IO build
completion Generate the autocompletion script for the specified shell
dump Dump IO data
get Get IO elements
help Help about any command
log Get or set log level
put Upload IO configuration from STDIN
resolve Resolve service names
rm Remove IO elements
rotate Rotate logs
shutdown Shutdown IO
status IO status
tail Display the end of a file and changes
test Test commands
version Display IO version
vouchers Operate on vouchers
whoami Display the connected user
Flags:
-h, --help help for ssh alfa -p 2200 --
Use "ssh alfa -p 2200 -- [command] --help" for more information about a command.
Configuration
The ssh_port element
Integer. Specifies the port where IO listens for SSH connections (defaults to 2200). Changes to this value take effect on the next restart of IO.
ssh_port = 2200
The ssh directory
Other aspects of IO's configuration are controlled using files in the ssh subdirectory of the directory where IO stores files. When an IO binary is run locally, that defaults to ~/.local/share/io. When IO is run in its container, that directory is /io in the container (typically an external volume is mounted to this path). In either case, IO looks for the following files:
ssh/authorized_keys
This file has the same meaning and format as the authorized_keys file in your local .ssh directory. It contains the public keys that will authenticate connections to the IO SSH port.
Its contents should look like this:
ssh-ed25519 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX user@example.com
Other key types (such as ssh-rsa) are also supported.
ssh/ssh_host_ed25519_key
This file contains the host key used by the IO server. If this file doesn't exist, IO will create one and store it at this location. It can also be generated directly using the following command:
ssh-keygen -t ed25519 -f ssh_host_ed25519_key -N ""
Its contents should look like this:
-----BEGIN OPENSSH PRIVATE KEY-----
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
-----END OPENSSH PRIVATE KEY-----
The host key must be an Ed25519 key.
Connecting to IO using an SSH Proxy Jump
In some cases, an IO server could be running behind a firewall that is only configured to allow SSH connections through port 22. Typically, IO can't use this port because an SSH server is running on it, but if so, IO can still be reached through port 22 using a mechanism called ProxyJump.
Here's an example. hammer-surfing.exe.xyz is the remote server, localhost is the local name of the remote server, and 2200 is the port on that server where IO is accepting SSH connections.
ssh -J hammer-surfing.exe.xyz localhost -p 2200
To connect using the more concise ssh hammer-surfing-io, put the following in ~/.ssh/config:
Host hammer-surfing-io
HostName hammer-surfing.exe.xyz
ProxyJump hammer-surfing.exe.xyz
Port 2200