Connect More Servers

Every server you want to manage with Komodo needs the Periphery agent installed. Periphery is a small, stateless binary that provides receives commands from Komodo Core over a bi-directional websocket connection.

Connecting a server has 3 steps:

1. Create an onboarding key via the Komodo Core API / UI.
2. Install the Periphery agent on the server or VM, passing the onboarding key.
3. Confirm the connection status is OK.

Install Periphery

You can install Periphery as a systemd managed process, run it as a docker container, or run the binary directly with another process manager.

Systemd

info

This is the recommended and simplest method to run Periphery. It avoids a number of complications which can come up when running Periphery in a container. See this discussion.

Root install

curl -sSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/setup-periphery.py \
  | python3 - \
  --core-address="https://<core-address>" \
  --connect-as="$(hostname)" \
  --onboarding-key="O-..."

User install

Periphery can also be installed to run as a systemd user service (for the calling user).

curl -sSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/setup-periphery.py \
  | python3 - --user \
  --core-address="https://<core-address>" \
  --connect-as="$(hostname)" \
  --onboarding-key="O-..."

Enable the Periphery service to start automatically after a reboot.

sudo systemctl enable periphery

Important

For systemctl user installs: To ensure periphery stays running when your user logs out, make sure to enable linger:

sudo loginctl enable-linger $USER

Configuration file

The configuration file location will depend on root vs system install:

• Root install: /etc/komodo/periphery.config.toml
• User install: $HOME/.config/komodo/periphery.config.toml

The full example configuration file is here.

You can find more information (and view the script) in the script readme.

info

This script can be run multiple times without issue, and it won't change existing config after the first run. Just run it again after a Komodo version release, and it will update the periphery version.

tip

For deployment to many servers, a tool like Ansible should be used. An example of such a setup can be found here: https://github.com/bpbradley/ansible-role-komodo

Container

You can use a docker compose file:

https://github.com/moghtech/komodo/blob/main/compose/periphery.compose.yaml

Binary

1. Download the periphery binary from the latest release.

2. Create and edit your config files, following the config example.

note

See the periphery config docs for more information on configuring periphery.

3. Ensure that connectivity with Komodo Core is possible via the chosen connection method. So either:

   • Periphery can reach Komodo Core at the configured core_address.
   • Komodo Core can reach Periphery on the specified port (default 8120).

4. Install docker. See the docker install docs.

note

Ensure that the user which periphery is run as has access to the docker group without sudo.

5. Start the periphery binary with your preferred process manager, like systemd.

Example periphery start command

periphery --config-path /path/to/periphery.config.toml

info

You can run periphery --help to see the manual.

When running periphery in docker, use command to pass in additional arguments.

command: periphery --config-path /path/in/container/to/periphery.config.base.toml

Authentication and Key Rotation

Core and Periphery authenticate using automatically generated public/private key pairs. No manual key management is required.

How it works

1. When you create an onboarding key in the UI or API, Komodo Core generates a key pair, and the private key is returned once the the user as the "onboarding key".
2. When Periphery first connects using the onboarding key, it generates its own key pair, and sends just the public key to Core. Core stores this public key for each Server.
3. All subsequent communication is authenticated by performing a cryptographic handshake and validating the transfered public key matches.

The onboarding key is no longer needed after the initial connection, and the Periphery private key never leaves the server.

Default key locations

Component	Install Method	Default path
Core	Container	/config/keys/core.key
Periphery	Container	/config/keys/periphery.key
Periphery	Systemd	${root_directory}/keys/periphery.key

Keys can also be specified inline in config instead of as file paths.

Automatic key rotation

Komodo supports automatic rotation of the Periphery key pairs. When triggered, already connected Periphery agents generate a new key pair and sends the new public key to Komodo Core, which updates its expected public key for that server.

Each Server has an auto_rotate_keys setting (default: true) that controls whether it participates in the bulk RotateAllServerKeys operation. You can also rotate keys for individual servers at any time through the API or UI.

Onboarding key options

Onboarding keys are reusable and support several options:

Option	Description
enabled	Enable or disable the key.
expires	Expiration timestamp (0 = never).
tags	Default tags applied to servers created with this key.
copy_server	Template Server to copy configuration from.
create_builder	Automatically create a Builder resource for the new server.
privileged	Allow the key to update public keys on existing servers.

Configuration

The configuration can also be passed as YAML or JSON. You can use it-tools to convert this TOML file to your preferred format:

• YAML: it-tools.tech/toml-to-yaml
• JSON: it-tools.tech/toml-to-json

Quick download to ./komodo/periphery.config.toml:

wget -P komodo https://raw.githubusercontent.com/moghtech/komodo/main/config/periphery.config.toml

https://github.com/moghtech/komodo/blob/main/config/periphery.config.toml

Passing config files

Either file paths or directory paths can be passed to --config-path (alias: -c). By default, no paths will be used, meaning the configuration is entirely loaded via environment variables.

When using directories, the file entries can be filtered by name with the --config-keyword argument, which can be passed multiple times to add more keywords. These are each wildcard patterns to match file names. Only config files with file names that contain a keyword will be merged, with files matching later defined keywords having higher priority on field conflicts. By default, the only keyword is *config*.*. This matches files like config.toml, periphery.config.yaml, etc.

When passing multiple config files, later --config-path given in the command will always override previous ones. Directory config files are merged in alphabetical order by name, so config_b.toml will override config_a.toml.

There are two ways to merge config files. The default behavior is to completely replace any base fields with whatever fields are present in the override config. So if you pass allowed_ips = [] in your override config, the final allowed_ips will be an empty list as well.

--merge-nested-config true will merge config fields recursively and extend config array fields.

For example, with --merge-nested-config true you can specify an allowed ip in the base config, and another in the override config, they will both be present in the final config.

Similarly, you can specify a base Docker / GitHub account pair, and extend them with additional accounts in the override config.