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.

## 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 is in a subnet which
was configured when creating the network.

## Step 3: Create a `bootstrap.json` File

Access to an `admin.json` file is required for this step.

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

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

The resulting `bootstrap.json` file should be treated as a secret file and
shared only with the user it was generated for. The `bootstrap.json` file should
not be re-used between hosts.

The user can now proceed with calling `isle network join`, as described in the
[Getting Started][getting-started] document.

[getting-started]: ../user/getting-started.md

### Encrypted `admin.json`

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

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

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