Operators and Remote Console

Operators and Remote Console

An operator is someone who runs console commands on a server from another machine. Operators have no passwords: each has a key file, and the server's ACL says which commands each key may run. Every request is signed with the operator's key, sealed to the server's identity key and answered once; a replayed request is refused.

The remote console is off until a group of the ACL holds an operator key.

1. Make an operator key

On the operator's own machine:

avalanche-server keygen --operator operator.key

made operator.key
operator key 91d0e59047b116679d90b16b4a8ded3f2946d8859db1d100fad3c8d42e6fec5e
give it rights on a server: acl add <group> operator.91d0e59047b116679d90b16b4a8ded3f2946d8859db1d100fad3c8d42e6fec5e
its id in the server's log and in bans.toml: operator 0cf066030546ce7d

The file is readable by its owner only. Keep it secret: whoever has it has its rights. keygen never replaces an existing file. The long hex string is the public key: send that (not the file) to the server's owner.

2. Give it rights on the server

In the server's console:

acl create admins
acl add admins operator.91d0e59047b116679d90b16b4a8ded3f2946d8859db1d100fad3c8d42e6fec5e
acl allow admins command
acl deny admins command.stop

command allows every console command; command.stop is then denied. The right for a command is command.<its first word>: command.kick, command.ban, command.acl and so on. A read-only helper gets acl allow helpers command.status and acl allow helpers command.instances. Check a decision with acl check <object> <right>:

operator.91d0…6fec5e command.kick: allowed (by group admins at command)
operator.91d0…6fec5e command.stop: denied (by group admins at command.stop)

3. Run commands

avalanche-server rcon <server address> --key operator.key <command…>

The server's identity key is pinned the first time, the way SSH pins a host key. The first command without --accept-new stops and shows the key:

127.0.0.1:27650 is not pinned; its /info offers the key 858ed6cbb1261fef0e36fc0900bfa4806bef7cb85dd26c1e4b28cb609e2ded29. Compare it with the server's log line "identity key …" and run again with --accept-new (or --server-key <hex>)

Compare it with the line listening on …; identity key … in the server's log, then:

avalanche-server rcon 127.0.0.1:27650 --key operator.key --accept-new say "hello from afar"
pinned 127.0.0.1:27650 = 858ed6cbb1261fef0e36fc0900bfa4806bef7cb85dd26c1e4b28cb609e2ded29 in rcon-servers.toml
said: hello from afar

The pins are kept in rcon-servers.toml beside the key file. A server whose key changed is always refused: either someone is in between, or the server made new keys. Remove its line only after checking with the server's owner. --server-key <hex> gives the key on the command line instead of the pin file.

A denied command:

avalanche-server rcon 127.0.0.1:27650 --key operator.key stop
refused, Denied: your groups do not hold command.stop

The address is host[:port]; the port defaults to the game port, 27450. Commands with spaces in an argument are quoted for your shell as usual.

avalanche-server rcon --help:

Run a console command on a server with an operator key (the remote console) and print its answer

Usage: avalanche-server rcon [OPTIONS] --key <FILE> <ADDRESS> <COMMAND>...

Arguments:
  <ADDRESS>     The server: host[:port] or an address (the game port by default)
  <COMMAND>...  The command and its arguments

Options:
      --key <FILE>        The operator key (made by `keygen --operator`)
      --server-key <HEX>  The server's identity key (hex), instead of the pin file beside the operator key
      --accept-new        Pin the key the server offers when its address is not pinned yet
      --config <CONFIG>   The configuration file (missing: the defaults) [default: server.toml]
      --data <DATA>       The data folder: the server's keys, logs and the rules subset of your disc [default: data]
  -h, --help              Print help

avalanche-server keygen --help:

Make the data folder's keys (refused if a key file exists: keys are never replaced)

Usage: avalanche-server keygen [OPTIONS]

Options:
      --operator <FILE>  Make an operator key at this file instead (for the remote console; its public key goes into acl.toml)
      --config <CONFIG>  The configuration file (missing: the defaults) [default: server.toml]
      --data <DATA>      The data folder: the server's keys, logs and the rules subset of your disc [default: data]
  -h, --help             Print help

rcon exit code	Meaning
0	the command ran
1	it ran and failed
3	refused (no right, unknown key)
2	no answer: the address, the pin, the key file, a limit

Limits

• Per address and per key: 2 requests a second, with a burst of 8.
• After 5 failures (a wrong key, a bad signature, a replay) only one try a minute, per address and per key.
• The server waits at most 5 seconds for a command's answer.
• Every remote command is logged with the operator's id: rcon 0cf066030546ce7d: "say hello from afar": done (1 lines).

keygen without --operator makes the server's own keys in the data folder; the first start does that by itself.