diff --git a/docs/admin/adding-a-host-to-the-network.md b/docs/admin/adding-a-host-to-the-network.md index c27650a..43eb727 100644 --- a/docs/admin/adding-a-host-to-the-network.md +++ b/docs/admin/adding-a-host-to-the-network.md @@ -20,7 +20,7 @@ conform to the following rules: To create a `bootstrap.json` file for the new host, the admin should perform the following command from their own host: -``` +```bash isle hosts create --hostname >bootstrap.json ``` diff --git a/docs/admin/creating-a-new-network.md b/docs/admin/creating-a-new-network.md index beba061..15161a2 100644 --- a/docs/admin/creating-a-new-network.md +++ b/docs/admin/creating-a-new-network.md @@ -35,25 +35,7 @@ The requirements for this host are: * 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 +## Step 1: 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 @@ -78,19 +60,22 @@ be chosen with care. the Network](./adding-a-host-to-the-network.md) 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: Create the Network +## Step 2: Create the Network To create the network, run: -``` -sudo isle network create \ +```bash +# Creating a host with 3 initial storage allocations of capacities 10GB, 15GB, +# and 20GB: +isle network create \ --name \ --ip-net \ --domain \ - --hostname + --hostname \ + --vpn-public-address \ + --storage-allocation 10@/mnt/driveA/isle \ + --storage-allocation 15@/mnt/driveB/isle \ + --storage-allocation 20@/mnt/driveC/isle ``` At this point your host, and your network, are ready to go! To add other hosts diff --git a/docs/admin/removing-a-host-from-the-network.md b/docs/admin/removing-a-host-from-the-network.md index 7c54092..6b6af62 100644 --- a/docs/admin/removing-a-host-from-the-network.md +++ b/docs/admin/removing-a-host-from-the-network.md @@ -2,7 +2,7 @@ Removing a host from the network is as simple as -``` +```bash isle host remove --hostname ``` diff --git a/docs/command-line.md b/docs/command-line.md index 3f74c2f..233aed8 100644 --- a/docs/command-line.md +++ b/docs/command-line.md @@ -17,6 +17,7 @@ and so are not expected to be online at any particular moment. Documentation for users: * [Joining a Network](./user/join-a-network.md) +* [Working With Multiple Networks](./user/multiple-networks.md) * [Using DNS](./user/using-dns.md) (advanced) ### Operator Docs @@ -34,8 +35,9 @@ afraid of a terminal. Documentation for operators: +* [Configuring Networks](./operator/configuring-networks.md) * [Contributing Storage](./operator/contributing-storage.md) -* [Contributing a Lighthouse](./operator/contributing-a-lighthouse.md) +* [Contributing a Public Address](./operator/contributing-a-public-address.md) * [Managing garage](./operator/managing-garage.md) * [Firewalls](./operator/firewall.md) diff --git a/docs/operator/configuring-networks.md b/docs/operator/configuring-networks.md new file mode 100644 index 0000000..a50c554 --- /dev/null +++ b/docs/operator/configuring-networks.md @@ -0,0 +1,69 @@ +# Configuring Networks + +Only users who intend on providing some resource to a network, such as +[storage][storage] or [a public address][publicaddr], will need to perform any +network-related configuration on their host. + +There are two different ways to manage the configuration of a host related to a +particular network: command-line, or configuration file. Command-line is +generally more convenient, but the configuration file exposes even more +fine-grained controls for super power users and might be preferred by them. + +When a host is joined to multiple networks the user is able to configure some +of them using one mode and the rest using the other. + +[storage]: contributing-storage.md +[publicaddr]: contributing-a-public-address.md + +## Command-line Interface (CLI) + +Configuring using the CLI is as easy as using the `isle` command-line tool, and +is covered by other documentation such as those linked above. + +Keep in mind that if a network's configuration is managed by a configuration +file then the related CLI commands will return an error indicating that the +configuration file must be modified instead. + +```bash +# isle vpn public-address unset +[4] Network configuration is managed by the daemon.yml +``` + +## Configuration File (daemon.yml) + +A `daemon.yml` file can be provided to the daemon process when it is run using +the `--config-path` parameter. If Isle is [installed from a package][install] +then this file will be automatically referenced by the daemon service, and can +be found at `/etc/isle/daemon.yml`. If not the steps to create it are described +in that same document. + +Within the `daemon.yml` is the `networks` field, which accepts a mapping of +network identifier to network configuration. The comments in the file itself +describe the available configuration parameters. + +There are three different ways to identify the network in this file: + +* Network identifier (a big long random string, unique to each network) +* Network name +* Network domain + +If you're not sure of how to identify a network, you can see all three for each +network using the `isle network list` command: + +[install]: ../install.md + +## Switching From CLI to Configuration File (or Vice-Versa) + +If you want to switch from using CLI-based configuration to using the +configuration file, you only need to add the desired configuration to the +`daemon.yml` file and restart the `isle` process. + +You can use `isle network get-config` to get the currently active configuration +for a network in the same format as would be used in `daemon.yml`. This can be +copy-pasted into the `daemon.yml` for a clean transition. + +If you want to switch from using the configuration file to using CLI-based +configuration you only need to remove the section of the configuration file +related to the network and restart the `isle` service. Isle will remember the +most recently used configuration for the network and use that upon restart if +none is provided in the configuration file. diff --git a/docs/operator/contributing-a-lighthouse.md b/docs/operator/contributing-a-lighthouse.md deleted file mode 100644 index 48270ee..0000000 --- a/docs/operator/contributing-a-lighthouse.md +++ /dev/null @@ -1,39 +0,0 @@ -# Contributing a Lighthouse - -The [nebula][nebula] project provides the VPN component which is used by -Isle. Every nebula network requires at least one (but preferably more) -publicly accessible hosts. These hosts are called lighthouses. - -Lighthouses do _not_ route traffic between hosts on the VPN. Rather, they -coordinate VPN hosts to talk directly to each other, and handle the details of -NAT punching through any NATs that hosts might be behind. As such, they are very -lightweight to run, and require no storage resources at all. - -If your host machine has a public static IP, or a dynamic public IP with -[dDNS][ddns] set up, then it can contribute a lighthouse. - -[nebula]: https://github.com/slackhq/nebula -[ddns]: https://www.cloudflare.com/learning/dns/glossary/dynamic-dns/ - -## Setup network - -The first step is to pick a UDP port you will expose the lighthouse on. It -doesn't really matter which port you pick, but a number over 1024 is -recommended. - -If your host is behind a NAT, ensure that the gateway is setup to forward UDP -traffic on that port to your host. - -Configure your host's firewall to allow all UDP traffic on that port. - -## Edit daemon.yml - -Open your `/etc/isle/daemon.yml` file in a text editor, and find the -`vpn.public_addr` field. Update that field to reflect your host's IP/DNS name -and your chosen UDP port. - -## Restart the Daemon - -With the `daemon.yml` configured, you should restart your `isle daemon` -process. On startup the daemon will add its public address to the global -configuration, which other hosts will pick up on and begin using. diff --git a/docs/operator/contributing-a-public-address.md b/docs/operator/contributing-a-public-address.md new file mode 100644 index 0000000..7afcb19 --- /dev/null +++ b/docs/operator/contributing-a-public-address.md @@ -0,0 +1,49 @@ +# Contributing a Public Address + +Isle provides a VPN component which allows hosts in the network to connect to +each other directly and securely. This VPN forms the base layer on which all +other Isle functionality is based. + +Every Isle network requires at least one host which provides a publicly +accessible address. These publicly accessible hosts do _not_ route traffic +between hosts on the Isle network. Rather, they coordinate hosts to talk +directly to each other, and handle the details of punching through any NATs that +hosts might be behind. As such providing a public address is very lightweight +and requires no storage. + +If your host machine has a public static IP, or a dynamic public IP with +[dDNS][ddns] set up, then it can contribute a public address. + +[nebula]: https://github.com/slackhq/nebula +[ddns]: https://www.cloudflare.com/learning/dns/glossary/dynamic-dns/ + +## Setup networking + +The first step is to pick a UDP port you will expose. It doesn't really matter +which port you pick, but a number over 1024 is recommended. + +If your host is behind a NAT, ensure that the gateway is setup to forward UDP +traffic on that port to your host. + +Configure your host's firewall to allow all UDP traffic on that port. + +## Configure Isle + +See the [Configuring Networks](./configuring-networks.md) document for notes on +how to configure Isle networks. This guide assumes configuration using the CLI. + +The `isle vpn public-address` sub-commands can be used to inspect and manage +the public address provided by the host. + +```bash +# isle vpn public-address get +No public address configured + +# isle vpn public-address set --to some-host.mydomain.com:5678 + +# isle vpn public-address get +some-host.mydomain.com:5678 +``` + +Once set the public address will be automatically used by other hosts on the +network. diff --git a/docs/operator/contributing-storage.md b/docs/operator/contributing-storage.md index b7ff290..434f79e 100644 --- a/docs/operator/contributing-storage.md +++ b/docs/operator/contributing-storage.md @@ -4,54 +4,71 @@ This document is for you if your host machine can be reliably be online at all times and has 1GB or more of unused drive space you'd like to contribute to the network. -## Edit `daemon.yml` - -Open your `/etc/isle/daemon.yml` file in a text editor, and find the -`storage.allocations` section. - -Each allocation in the allocations list describes the space being contributed -from a single physical drive. If you only have one drive then you will only need -one allocation listed. - -The comments in the file should be self-explanatory, but ask your admin if you -need any clarification. - -Here is an example set of allocations for a host which is contributing space -from two separate drives: - -``` -storage: - allocations: - - # 1.2 TB are being shared from drive1 - - data_path: /mnt/drive1/isle/data - meta_path: /mnt/drive1/isle/meta - capacity: 1200 - - # 100 GB are being shared from drive2 - - data_path: /mnt/drive2/isle/data - meta_path: /mnt/drive2/isle/meta - capacity: 100 -``` - ## Set Up Your Firewall -See the doc on [Firewalls](./firewalls.md), to be sure that your host's firewall -is properly set up for providing storage. +The Isle daemon will automatically allow the ports used for your storage +allocations in Isle's builtin firewall. See the doc on +[Firewalls](./firewalls.md), to be sure that your host's firewall is properly +set up for providing storage. -## Restart the Daemon +## Configure Isle -With the `daemon.yml` configured, you should restart your `isle daemon` -process. +See the [Configuring Networks](./configuring-networks.md) document for notes on +how to configure Isle networks. This guide assumes configuration using the CLI. -The `isle daemon` will automatically allow the ports used for your -storage allocations in the vpn firewall. +The `isle storage allocation` sub-commands can be used to inspect and manage the +storage allocations provided by the host. + +```bash +# isle storage allocations list +[] + +# isle storage allocation add \ + --data-path /mnt/drive/isle/data \ + --meta-path /mnt/drive/isle/meta \ + --capacity 100 + +# isle storage allocations list +- index: 0 + data_path: /mnt/drive/isle/data + meta_path: /mnt/drive/isle/meta + capacity: 100 + s3_api_port: 3901 + rpc_port: 3900 + admin_port: 3902 +``` + +The above example shows 100GB of storage being added to the network at +`/mnt/drive/isle/data`. It's important to remember that the same data or meta +directory cannot be shared between different allocations or different networks. + +The meta directory doesn't store very much data. If possible it's better to +place the meta directory on a fast drive like an SSD, while the data directory +for the same allocation remains on a large spinning-disk drive. This is not a +requirement though, and the network will function fine either way. ## Removing Allocations -If you later decide to no longer provide storage simply remove the -`storage.allocations` item from your `/etc/isle/daemon.yml` file and restart the -`isle daemon` process. +If you later decide to no longer provide storage the +`isle storage allocations remove` command can be used to remove it. Each +allocation is identified by its index, as returned by +`isle storage allocations list`. + +```bash +# isle storage allocations list +- index: 0 + data_path: /mnt/drive/isle/data + meta_path: /mnt/drive/isle/meta + capacity: 100 + s3_api_port: 3901 + rpc_port: 3900 + admin_port: 3902 + +# isle storage allocation remove --index=0 + +# isle storage allocations list +[] +``` Once removed, it is advisable to wait some time before removing storage allocations from other hosts. This ensures that all data which was previously diff --git a/docs/operator/firewalls.md b/docs/operator/firewalls.md index a9d3dae..5cd7efa 100644 --- a/docs/operator/firewalls.md +++ b/docs/operator/firewalls.md @@ -1,9 +1,9 @@ # Firewalls -When providing services on your host, whether -[network](./contributing-a-lighthouse.md) or -[storage](./contributing-storage.md), you will need to ensure that your host's -firewall is configured correctly to do so. +When providing resources on your host, whether +[network](./contributing-a-public-address.md) or +[storage](./contributing-storage.md), you will need to ensure that your +host's firewall is configured correctly to do so. To make matters even more confusing, there are actually two firewalls at play: the host's firewall, and the VPN firewall. @@ -14,24 +14,24 @@ Isle uses the [nebula](https://github.com/slackhq/nebula) project to provide its VPN layer. Nebula ships with its own [builtin firewall](https://nebula.defined.net/docs/config/firewall), which only applies to connections coming in over the virtual network interface which it creates. -This firewall can be manually configured as part of the `/etc/isle/daemon.yml` -file. +This firewall can be manually configured using the `isle vpn firewall` set of +sub-commands, or using the [configuration file][configfile]. -Any storage instances which are defined as part of the `daemon.yml` file will -have their network ports automatically added to the VPN firewall by isle. -This means that you only need to configure the VPN firewall if you are hosting -services for your isle network besides storage. +Any storage allocations which are defined will have their network ports +automatically added to the VPN firewall by Isle. This means that you only need +to configure the VPN firewall if you are hosting services for your isle network +besides storage. ## Host Firewall The host you are running isle on will almost definitely have a firewall running, separate from the VPN firewall. If you wish to provide services for -your isle network from your host, you will need to allow their ports in your +your Isle network from your host, you will need to allow their ports in your host's firewall. **isle does _not_ automatically configure your host's firewall to any extent!** -One option is to open your host to all traffic from your isle network, and +One option is to open your host to all traffic from your Isle network, and allow the VPN firewall to be fully responsible for filtering traffic. To do this on Linux using iptables, for example, you would add something like this to your iptables configuration: @@ -40,9 +40,11 @@ iptables configuration: -A INPUT --source --jump ACCEPT ``` -being sure to replace the network CIDR with the one for you network. +being sure to replace the network CIDR with the one for your network. If you don't feel comfortable allowing nebula to deal with all packet filtering, you will need to manually determine and add the ports for each nebula service to -your host's firewall. It is recommended that you manually specify any storage -allocation ports defined in your `daemon.yml` if this is the approach you take. +your host's firewall. You will need to manually specify any configured storage +allocation ports if this is the approach you take. + +[configfile]: ./configuring-networks.md diff --git a/docs/user/multiple-networks.md b/docs/user/multiple-networks.md new file mode 100644 index 0000000..65c4bfb --- /dev/null +++ b/docs/user/multiple-networks.md @@ -0,0 +1,23 @@ +# Working With Multiple Networks + +When joined to only a single network all CLI commands will assume that network +is the subject of the command. However if multiple networks are joined then the +desired must be specified. This is done using the `--network` flag on all +commands which require it. + +The `--network` flag accepts as its argument either the network ID, the +network's name, or the network's domain. + +```bash +# Using network ID +isle hosts list --network b56b7d9ec420878fe3f + +# Using network name +isle storage allocations list --network "Martin And Friends" + +# Using network domain +isle vpn firewall list --network martin-and-friends.com +``` + +The values of these for each joined network can be obtained using +`isle networks list`. diff --git a/docs/user/using-dns.md b/docs/user/using-dns.md index 0a7e40d..dbe4b65 100644 --- a/docs/user/using-dns.md +++ b/docs/user/using-dns.md @@ -1,8 +1,7 @@ # Using DNS -Every `isle daemon` process ships with a DNS server which runs -automatically. This server will listen on port 53 on the VPN IP of that -particular host. +Every `isle daemon` process ships with a DNS server which runs automatically. +This server will listen on port 53 on the VPN IP of that particular host. The server will serve requests for `.hosts.` hostnames, where `` is the name of any host in the network, and ` is the diff --git a/go/daemon/daecommon/daemon.yml b/go/daemon/daecommon/daemon.yml index 590df08..b2a5606 100644 --- a/go/daemon/daecommon/daemon.yml +++ b/go/daemon/daecommon/daemon.yml @@ -1,12 +1,12 @@ # -# This file defines all configuration directives which can be modified for -# the isle daemon at runtime. All values specified here are the -# default values. +# This file defines all configuration directives which can be modified for the +# isle daemon at runtime. All values specified here are the default values. # ################################################################################ # Configuration broken down by network. Each network can be identified by its -# ID, its name, or its domain. +# ID, its name, or its domain. These can be discovered using +# `isle networks list`. #networks: #id-or-name-or-domain: @@ -14,8 +14,8 @@ # A DNS service runs as part of every isle process. #dns: - # list of IPs that the DNS service will use to resolve requests outside the - # network's domain. + # list of IPs that the DNS service will use to resolve requests outside + # the network's domain. #resolvers: # - 1.1.1.1 # - 8.8.8.8 @@ -23,47 +23,46 @@ # A VPN service runs as part of every isle process. #vpn: - # Enable this field if the vpn will be made to be publicly accessible at a - # particular IP or hostname. At least one host must have a publicly accessible - # VPN process at any given moment. + # Enable this field for this host to be used for the coordination of VPN + # connections between other hosts. #public_addr: "host:port" - # Firewall directives, as described here: - # https://github.com/slackhq/nebula/blob/v1.6.1/examples/config.yml#L260 + # By default the VPN firewall rejects all traffic. All entries here + # indicate traffic which should be allowed. + # + # Ports used for storage allocations (defined lower down) will be + # automatically allowed and don't need to be included here. #firewall: - # Allow all outbound traffic from this node. + # Allow all outbound traffic from this host. #outbound: # - port: any # proto: any # host: any - # Allow ICMP between hosts. + # Allow ICMP (ping) between hosts. #inbound: # - port: any # proto: icmp # host: any - # - # # If any storage allocations are declared below, the ports used will be - # # allowed here automatically. #storage: - # Allocations defined here are used to store data in the distributed storage - # network. If no allocations are defined then no data is replicated to this - # node. + # Allocations defined here are used to store data in the distributed + # storage network. If no allocations are defined then no data is + # replicated to this host. # - # Each allocation should have its own data/meta directories, separate from the - # other allocations. + # Each allocation should have its own data/meta directories, separate from + # the other allocations. # - # The data directory of each allocation should be on a different drive, while - # the meta directories can be anywhere (ideally on an SSD). + # The data directory of each allocation should be on a different drive, + # while the meta directories can be anywhere (ideally on an SSD). # - # Capacity declares how many gigabytes can be stored in each allocation, and - # is required. + # Capacity declares how many gigabytes can be stored in each allocation, + # and is required. # - # The ports are all _optional_, and will be automatically assigned if they are - # not specified. If ports any ports are specified then all should be + # The ports are all _optional_, and will be automatically assigned if they + # are not specified. If ports any ports are specified then all should be # specified, and each should be unique across all allocations. # #allocations: diff --git a/nix/nebula.nix b/nix/nebula.nix index aad26ca..b4774c5 100644 --- a/nix/nebula.nix +++ b/nix/nebula.nix @@ -8,7 +8,6 @@ pname = "nebula"; # If this changes, remember to change: - # - the go/daemon/daecommon/daemon.yml vpn.firewall docs # - the version imported in go-workspace version = "1.6.1"; diff --git a/tasks/v0.0.3/update-documentation.md b/tasks/v0.0.3/update-documentation.md deleted file mode 100644 index 9b1f3d7..0000000 --- a/tasks/v0.0.3/update-documentation.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -type: task ---- - -# Update Documentation - -All documentation related to management of network configuration needs to be -updated. - -Check through all development documentation, especially that surrounding -testing. - -Doc changes to included are: - -- New page on network configuration, how it can be done via the `daemon.yml` - file or via the command-line (but not both!) - -- Rework "Contributing a Lighthouse" so that it doesn't directly mention nebula - or lighthouses at all. - -- Remove nebula reference from `daemon.yml` comments.