isle/docs/admin/creating-a-new-network.md

Creating a New Network

This guide is for those who wish to start a new isle network of their own.

By starting a new isle network, you are becoming the administrator of a network. Be aware that being a network administrator is not necessarily easy, and the users of your network will frequently need your help in order to have a good experience. It can be helpful to have others with which you are administering the network, in order to share responsibilities.

Requirements

Creating a network is done using a single host, which will become the first host in the network.

The configuration used during network creation will be identical to that used during normal operation of the host, so be prepared to commit to that configuration for a non-trivial amount of time.

The requirements for this host are:

• A public static IP, or a dynamic public IP with dDNS set up.

  • There should be UDP port which is accessible publicly over that IP/DNS name. This may involve forwarding the UDP port in your gateway if the host is behind a NAT, and/or allowing traffic on that UDP port in your hosts firewall.

• At least 3 GB of disk storage space.

  • At least 3 directories should be chosen, each of which will be committing at least 1GB. Ideally these directories should be on different physical disks, but if that's not possible it's ok. See the Next Steps section.

• None of the resources being used for this network (the UDP port or storage locations) should be being used by other networks.

Step 1: Configure the isle Daemon

Open /etc/isle/daemon.yml in a text editor and perform the following changes:

• Set the vpn.public_addr field to the host:port your host is accessible on, where host is the static public IP/DNS name of your host, and port is the UDP port which is publicly accessible.

• Configure 3 (at least) allocations in the storage.allocations section.

Save and close the file.

Run the following to restart the daemon with the new configuration:

sudo systemctl restart isle

Step 2: Choose Parameters

There are some key parameters which must be chosen when creating a new network. These will remain constant throughout the lifetime of the network, and so should be chosen with care.

• Name: A human-readable name for the network. This will only be used for display purposes.

• Subnet: The IP subnet (or CIDR) will look something like 10.10.0.0/16, where the /16 indicates that all IPs from 10.10.0.0 to 10.10.255.255 are included. It's recommended to choose from the ranges reserved for private networks, but within that selection the choice is up to you.

• Domain: isle is shipped with a DNS server which will automatically configure itself with all hosts in the network, with each DNS entry taking the form of hostname.hosts.domain, where domain is the domain chosen in this step. The domain may be a valid public domain or not, it's up to you.

• Hostname: The hostname of your host, which will be the first host in the network, must be chosen at this point. You can reference the Adding a Host to the Network document for the constraints on the hostname.

• IP: The IP of your host, which will be the first host in the network. This IP must be within the chosen subnet range.

Step 3: Prepare to Encrypt admin.json

The admin.json file (which will be created in the next step) is the most sensitive part of an isle network. If it falls into the wrong hands it can be used to completely compromise your network, impersonate hosts on the network, and will likely lead to someone stealing or deleting all of your data.

Therefore it is important that the file remains encrypted when it is not being used, and that it is never stored to disk in its decrypted form.

This guide assumes that you have GPG already set up with your own secret key, and that you are familiar with how it works. There is no requirement to use GPG, if you care to use a different method.

Step 4: Create the admin.json File

To create the network, and the admin.json file in the process, run:

sudo isle network create \
    --name <name> \
    --ip-net <subnet> \
    --domain <domain> \
    --hostname <hostname> \
    | gpg -e -r <my gpg email> \
    > admin.json.gpg

A couple of notes here:

• Only one gpg recipient is specified. If you intend on including other users as network administrators you can add them to the recipients list at this step, so they will be able to use the admin.json file as well. You can also manually add them as recipients later.

The isle network create command may take up to a minute to complete. Once completed you should have an admin.json.gpg file in your current directory.

At this point your host, and your network, are ready to go! To add other hosts to the network you can reference the Adding a Host to the Network document.