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

92 lines
3.0 KiB
Markdown
Raw Normal View History

# 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.
2022-10-30 00:22:03 +00:00
## Step 2: Choose IP
The admin should choose an IP for the host. The IP you choose for the new host
2022-10-30 00:22:03 +00:00
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
2022-11-02 13:02:21 +00:00
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 \
2022-11-05 11:34:49 +00:00
--hostname <name> \
2022-10-30 00:22:03 +00:00
--ip <ip> \
2022-11-02 13:02:21 +00:00
--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`.
2022-11-02 13:02:21 +00:00
### Encrypted `admin.yml`
2022-11-02 13:02:21 +00:00
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
2022-11-02 13:02:21 +00:00
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 \
2022-11-05 11:34:49 +00:00
--hostname <name> \
2022-10-30 00:22:03 +00:00
--ip <ip> \
--admin-path - \
> bootstrap.yml
```
2022-11-02 13:02:21 +00:00
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.
2022-10-30 00:22:03 +00:00
This binary should be treated like a `bootstrap.yml` in terms of its uniqueness
2022-10-30 00:22:03 +00:00
and sensitivity.