isle/docs/admin/adding-a-host-to-the-network.md

Adding a Host to the Network

This document guides an admin through adding a single host to the network. Keep in mind that the steps described here must be done for each host the user wishes to add.

There are two ways for a user to add a host to the isle network.

• If the user is savy enough to obtain their own isle binary, they can do so. The admin can then generate a bootstrap.yml file for their host, give that to the user, and the user can run isle daemon using that bootstrap file.

• If the user is not so savy, the admin can generate a custom isle binary with the bootstrap.yml embedded into it. The user can be given this binary and run isle daemon without any configuration on their end.

From the admin's perspective the only difference between these cases is one extra step.

Step 1: Choose Hostname

The user will need to provide you with a name for their host. The name should conform to the following rules:

• It should only contain lowercase letters, numbers, and hyphens.

• It should begin with a letter.

• It should end with a letter or number.

Step 2: Choose IP

The admin should choose an IP for the host. The IP you choose for the new host should be one which is not yet used by any other host, and which is in subnet which was configured when creating the network.

Step 3: Create a bootstrap.yml File

Access to an admin.yml file is required for this step.

To create a bootstrap.yml file for the new host, the admin should perform the following command from their own host:

isle hosts create-bootstrap \
    --hostname <name> \
    --ip <ip> \
    --admin-path <path to admin.yml> \
    > bootstrap.yml

The resulting bootstrap.yml file should be treated as a secret file that is shared only with the user it was generated for. The bootstrap.yml file should not be re-used between hosts either.

If the user already has access to a isle binary then the new bootstrap.yml file can be given to them as-is, and they can proceed with running their host's isle daemon.

Encrypted admin.yml

If admin.yml is kept in an encrypted format on disk (it should be!) then the decrypted form can be piped into create-bootstrap over stdin. For example, if GPG is being used to secure admin.yml then the following could be used to generate a bootstrap.yml:

gpg -d <path to admin.yml.gpg> | isle hosts create-bootstrap \
    --hostname <name> \
    --ip <ip> \
    --admin-path - \
    > bootstrap.yml

Note that the value of --admin-path is -, indicating that admin.yml should be read from stdin.

Step 4: Optionally, Build Binary

If you wish to embed the bootstrap.yml into a custom binary for the user (to make installation extremely easy for them) then you can run the following:

nix-build --arg bootstrap <path to bootstrap.yml> -A appImage

The resulting binary can be found in the result directory which is created.

This binary should be treated like a bootstrap.yml in terms of its uniqueness and sensitivity.