micropelago/isle
4
1
Fork 0
Code Issues 1 Pull Requests Projects Releases 6 Activity

Update documentation

Browse Source
This commit is contained in:
Brian Picciano 2024-12-17 20:42:47 +01:00
parent 279b70124c
commit 47f0bf910d
14 changed files with 259 additions and 175 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/admin/adding-a-host-to-the-network.md
View File

@ -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 <name> >bootstrap.json
```

37
docs/admin/creating-a-new-network.md
View File

@ -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 <name> \
--ip-net <subnet> \
--domain <domain> \
--hostname <hostname>
--hostname <hostname> \
--vpn-public-address <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

2
docs/admin/removing-a-host-from-the-network.md
View File

@ -2,7 +2,7 @@
Removing a host from the network is as simple as
```
```bash
isle host remove --hostname <name>
```

4
docs/command-line.md
View File

@ -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)

69
docs/operator/configuring-networks.md Normal file
View File

@ -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.

39
docs/operator/contributing-a-lighthouse.md
View File

@ -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.

49
docs/operator/contributing-a-public-address.md Normal file
View File

@ -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.

97
docs/operator/contributing-storage.md
View File

@ -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

32
docs/operator/firewalls.md
View File

@ -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 <network CIDR> --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

23
docs/user/multiple-networks.md Normal file
View File

@ -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`.

5
docs/user/using-dns.md
View File

@ -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 `<hostname>.hosts.<domain>` hostnames,
where `<hostname>` is the name of any host in the network, and `<domain`> is the

53
go/daemon/daecommon/daemon.yml
View File

@ -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:

1
nix/nebula.nix
View File

@ -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";

21
tasks/v0.0.3/update-documentation.md
View File

@ -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.