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

Update documentation

Browse Source
This commit is contained in:
Brian Picciano 2024-07-07 13:37:26 +02:00
parent 7d8b274445
commit ce5df164e1
13 changed files with 146 additions and 223 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
README.md
View File

@ -45,13 +45,12 @@ decide which documents they need to care about.
### User Docs
Users are participants who use network resources, but do not provide any network
or storage resources themselves. Users may be accessing the network from a
laptop, and so are not expected to be online at any particular moment.
resources themselves. Users may be accessing the network from a mobile device,
and so are not expected to be online at any particular moment.
Documentation for users:
* [Getting Started](docs/user/getting-started.md)
* [Creating a daemon.yml File](docs/user/creating-a-daemonyml-file.md)
* [Using DNS](docs/user/using-dns.md) (advanced)
* Restic example (TODO)
@ -63,7 +62,7 @@ Operator hosts will need at least one of the following to be useful:
* A static public IP, or a dynamic public IP with [dDNS][ddns] set up.
* At least 100GB of unused storage which can be reserved for the network.
* At least 100GB of unused storage which can be reserved for the network. (TODO review storage requirements)
Operators are expected to be familiar with server administration, and to not be
afraid of a terminal.

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

@ -4,20 +4,6 @@ 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.json` 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.json` 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
@ -32,8 +18,8 @@ conform to the following rules:
## 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 which is in subnet
which was configured when creating the network.
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
@ -50,13 +36,14 @@ isle admin create-bootstrap \
> bootstrap.json
```
The resulting `bootstrap.json` file should be treated as a secret file that is
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 either.
not be re-used between hosts.
If the user already has access to a `isle` binary then the new
`bootstrap.json` file can be given to them as-is, and they can proceed with
running their host's `isle daemon`.
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`
@ -75,17 +62,3 @@ gpg -d <path to admin.json.gpg> | isle admin create-bootstrap \
Note that the value of `--admin-path` is `-`, indicating that `admin.json`
should be read from stdin.
## Step 4: Optionally, Build Binary
If you wish to embed the `bootstrap.json` 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.json> -A appImage
```
The resulting binary can be found in the `result` directory which is created.
This binary should be treated like a `bootstrap.json` in terms of its uniqueness
and sensitivity.

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

@ -27,7 +27,7 @@ The requirements for this host are:
behind a NAT, and/or allowing traffic on that UDP port in your hosts
firewall.
* At least 300 GB of disk storage space.
* At least 300 GB of disk storage space. (TODO double check the storage space requirements)
* At least 3 directories should be chosen, each of which will be committing at
least 100GB. Ideally these directories should be on different physical
@ -36,16 +36,9 @@ 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: Create a `daemon.yml` File
## Step 1: Edit the `daemon.yml` File
A `daemon.yml` will need to be created for use during network creation. You can
create a new `daemon.yml` with default values filled in by doing:
```
isle admin create-network --dump-config > /path/to/daemon.yml
```
Open this file in a text editor and perform the following changes:
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
@ -104,7 +97,7 @@ you can run:
```
sudo isle admin create-network \
--config-path /path/to/daemon.yml \
--config-path /etc/isle/daemon.yml \
--name <name> \
--ip-net <ip/subnet-prefix> \
--domain <domain> \
@ -117,7 +110,8 @@ A couple of notes here:
* The `--ip-net` parameter is formed from both the subnet and the IP you chose
within it. So if your subnet is `10.10.0.0/16`, and your chosen IP in that
subnet is `10.10.4.20`, then your `--ip-net` parameter will be `10.10.4.20/16`.
subnet is `10.10.4.20`, then your `--ip-net` parameter will be
`10.10.4.20/16`. (TODO expand a bit on what IP is being chosen).
* 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,
@ -143,6 +137,8 @@ network for the daemon itself.
At this point your host, and your network, are ready to go! You can reference
the [Getting Started](../user/getting-started.md) document to set up your
host's daemon process in a more permanent way.
host's daemon process in a more permanent way. (TODO once creating a network is
done via RPC then this will be out-of-date. Better to direct them to the
operator docs, or maybe adding a new host).
[ddns]: https://www.cloudflare.com/learning/dns/glossary/dynamic-dns/

2
docs/dev/design-principles.md
View File

@ -10,7 +10,7 @@ Isle project.
* All resources within an isle network are expected to be hosted on hardware
owned by community members, for example home media servers or gaming rigs.
Thus, an isle is fully autonomous.
Thus, an isle network is fully autonomous.
* Hardware resources are expected to be heterogenous and geographically
dispersed.

2
docs/dev/releases.md
View File

@ -19,7 +19,7 @@ From here an `isle` binary will be cross-compiled for all supported
platforms. This will take a long time the first time you perform it on your
machine.
Once compilation is completely, the release will be signed using the default GPG
Once compilation is completed, the release will be signed using the default GPG
key on your machine, and you will be prompted for its password in order to
create the signature.

6
docs/glossary.md
View File

@ -15,6 +15,10 @@ documentation and source code.
- "isle network", "network" - A collection of hosts which communicate and share
resources with each other via the Isle project.
- "garage cluster" - Garage is one of the sub-processes which isle is able to
run. These garage process connect together to form a cluster. We use the
term "cluster" in the context of garage to stay consistent with garage's
documentation and command-line.
- "user" - A person who takes part in the usage, operation, or administration of
an isle network.

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

@ -26,18 +26,11 @@ traffic on that port to your host.
Configure your host's firewall to allow all UDP traffic on that port.
## Create daemon.yml
First, if you haven't already, [create a `daemon.yml`
file](../user/creating-a-daemonyml-file.md). This will be used to
configure your `isle daemon` process with the public address that other
hosts can find your daemon on.
## Edit daemon.yml
Open your `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.
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

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

@ -4,16 +4,9 @@ If your host machine can be reasonably sure of being online most, if not all, of
the time, and has 100GB or more of unused drive space you'd like to contribute
to the network, then this document is for you.
## Create `daemon.yml`
First, if you haven't already, [create a `daemon.yml`
file](../user/creating-a-daemonyml-file.md). This will be used to
configure your `isle daemon` process with the storage locations and
capacities you want to contribute.
## Edit `daemon.yml`
Open your `daemon.yml` file in a text editor, and find the
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

4
docs/operator/firewalls.md
View File

@ -14,8 +14,8 @@ 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 isle's
[`daemon.yml`](../user/creating-a-daemonyml-file.md) file.
This firewall can be manually configured as part of the `/etc/isle/daemon.yml`
file.
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.

54
docs/roadmap.md
View File

@ -8,14 +8,6 @@ order they will be implemented.
These items are listed more or less in the order they need to be completed, as
they generally depend on the items previous to them.
### Window Support + GUI
Support for Windows is a must. This requirement also includes a simple GUI,
which would essentially act as a thin layer on top of `daemon.yml` to start
with.
Depending on difficulty level, OSX support might be added at this stage as well.
### NATS
Garage is currently used to handle eventually-consistent persistent storage, but
@ -23,16 +15,15 @@ there is no mechanism for inter-host realtime communication as of yet. NATS
would be a good candidate for this, as it uses a gossip protocol which does not
require a central coordinator (I don't think), and is well supported.
### Integration of [domani](https://code.betamike.com/micropelago/domani)
### Integration of [Caddy](https://caddyserver.com/docs/)
Integration of domani will require some changes on domani's end. We want domani
Integration of Caddy's will require some plugins to be developed. We want Caddy
to be able to store cert information in S3 (garage), so that all isle lighthouse
nodes can potentially become gateways as well. Once done, it would be possible
for lighthouses to forward public traffic to inner nodes.
It should also be possible for users within the network to take advantage of
domani's hosting ability even without an always-on host of their own, without
requiring a passphrase.
It should also be possible for users within the network to take use lighthouse
Caddy's to host their websites (and eventually gemini capsules) for them.
Most likely this integration will require NATS as well, to coordinate cache
invalidation and cert refreshing.
@ -45,6 +36,14 @@ files. The bootstrap file would be stored, encrypted, in garage, with the invite
code being able to both identify and decrypt it. To instantiate a host, the user
only needs to input the network domain name and the invite code.
### Windows Support + GUI
Support for Windows is a must. This requirement also includes a simple GUI,
which would essentially act as a thin layer on top of `daemon.yml` to start
with.
Depending on difficulty level, OSX support might be added at this stage as well.
### FUSE Mount
KBFS style. Every user should be able to mount virtual directories to their host
@ -96,11 +95,16 @@ it works.
### Proper Linux Packages
Rather than distributing raw binaries for Linux we should instead be
distributing actual packages, e.g. deb files for debian/ubuntu, PKGBUILD for
arch, rpm for fedora (if we care), etc... This will allow for properly setting
capabilities for the binary at install time, so that it can be run as non-root,
and installing any necessary `.desktop` files so that it can be run as a GUI
application.
distributing actual packages.
* deb files for debian/ubuntu
* PKGBUILD for arch (done)
* rpm for fedora?
* flatpak?
This will allow for properly setting capabilities for the binary at install
time, so that it can be run as non-root, and installing any necessary `.desktop`
files so that it can be run as a GUI application.
### Mobile app
@ -109,20 +113,6 @@ would be great. We are not able to use the existing nebula mobile app because it
is not actually open-source, but we can at least use it as a reference to see
how this can be accomplished.
### Don't run as root
It's currently a pretty hard requirement for `isle daemon` to run as
root. This is due to:
- nebula's network interface root to be started.
- dnsmasq listening on port 53, generally a protected port.
On linux it should be fairly straightforward to grant the entrypoint the
necessary ambient capabilities up-front, and then drop down to a specified user.
This is how the tests work. Doing this with other OS's will depend on how they
work.
### DNS/Firewall Configuration
Ideally Isle could detect the DNS/firewall subsystems being used on a per-OS

32
docs/user/creating-a-daemonyml-file.md
View File

@ -1,32 +0,0 @@
# Creating a daemon.yml File
The `isle daemon` process has generally sane defaults and does not need
to be configured for most users. This document describes how to use the
`daemon.yml` file to handle those cases where configuration is necessary.
## Create daemon.yml
First, create a `daemon.yml` file. You can create a new `daemon.yml` with
default values filled in by doing:
```
isle daemon --dump-config > /path/to/daemon.yml
```
If you open that file in a text editor you can view all default values that
`isle daemon` ships with, as well as documentation for all configurable
parameters. Feel free to edit this file as needed.
## Using daemon.yml
With the `daemon.yml` created and configured, you can configure your daemon
process to use it by passing it as the `--config-path` argument:
```
sudo isle daemon --config-path /path/to/daemon.yml
```
If you are an operator then your host should be running its `isle daemon`
process in systemd (see [Getting Started](getting-started.md) if
not), and you will need to modify the service file accordingly.

172
docs/user/getting-started.md
View File

@ -6,118 +6,126 @@ binary and joining a network.
NOTE currently only linux machines with the following architectures are
supported:
- `x86_64` / `amd64`
- `aarch64` / `arm64`
- `x86_64` (aka `amd64`)
- `aarch64` (aka `arm64`)
- `i686`
(Only `x86_64` has been tested.)
(`i686` has not been tested.)
More OSs and architectures coming soon!
## Obtaining an isle Binary
## Install isle
### The Easy Way
How isle gets installed depends on which Linux distribution you are using.
Download the latest binary for your platform from
[this link](https://code.betamike.com/micropelago/isle/releases/latest).
### Archlinux (also Manjaro)
### The Hard Way
Download the latest `.pkg.tar.zst` package file for your platform from
[this link][latest].
Alternatively, you can build your own binary by running the following from the
project's root:
Install the package using pacman:
```
nix-build -A appImage
sudo pacman -U /path/to/isle-*.pkg.tar.zst
```
(*NOTE* Dependencies of `isle` seemingly compile all of musl and rust
from scratch (it's not clear why, blame garage!). If you have not otherwise
configured it, nix might be using a tmpfs as its build directory, and the
capacity of this tmpfs will probably be exceeded by this build. You can change
your build directory to somewhere on-disk by setting the TMPDIR environment
variable for `nix-daemon` (see [this github issue][tmpdir-gh].))
### Other Distributions
The resulting binary can be found in the `result` directory which is created.
If a package file is not available for your distribution you can still install
an AppImage directly. It is assumed that all commands below are run as root.
Download the latest `.AppImage` binary for your platform from
[this link][latest], and place it in your `/usr/bin` directory.
Create a `daemon.yml` file using default values by doing:
```
mkdir -p /etc/isle/
isle daemon --dump-config > /etc/isle/daemon.yml
```
Create a system user for the isle daemon to run as:
```
useradd -r -s /bin/false -C "isle Daemon" isle
```
If your distro uses systemd, download [the latest systemd service
file][serviceFile] and place it in `/etc/systemd/system`. Run `systemctl
daemon-reload` to ensure systemd has seen the new service file.
If your distro uses an init system other than systemd then you will need to
configure that yourself. You can use the systemd service file linked above as a
reference.
[serviceFile]: https://code.betamike.com/micropelago/isle/src/branch/main/dist/linux/isle.service
### From Source
(TODO probably move these instructions into the Dev docs section).
Building from source requires [nix][nix].
You can build your own AppImage by running the following from the project's
root:
```
nix-build -A appImageBin
```
(*NOTE* The first time you run this a lot of things will be built from scratch.
If you have not otherwise configured it, nix might be using a tmpfs as its build
directory, and the capacity of this tmpfs will probably be exceeded by this
build. You can change your build directory to somewhere on-disk by setting the
TMPDIR environment variable for `nix-daemon` (see
[this github issue][tmpdir-gh].))
The resulting binary can be found under `result/bin`. From here you can continue
with the instructions under the "AppImage" section above.
[nix]: https://nixos.wiki/wiki/Nix_package_manager
[tmpdir-gh]: https://github.com/NixOS/nix/issues/2098#issuecomment-383243838
## Obtaining Your Bootstrap File
## Add Users to the `isle` Group (Optional)
The `bootstrap.json` file contains all information required for your particular
host to join the network, and must be generated and provided to you by an admin
for the network.
## Running the Daemon
Once you have a binary and bootstrap file, you will need to run the `daemon`
sub-command as the root user. This can most easily be done using the `sudo`
command, in a terminal:
If you wish to run isle commands as a user other than root, you can add that
user to the `isle` group:
```
sudo /path/to/isle daemon --bootstrap-path /path/to/bootstrap.json
sudo usermod -aG isle username
```
This will start the daemon process, which will keep running until you kill it
with `ctrl-c`. The `--bootstrap-path /path/to/bootstrap.json` argument is only
required the first time the daemon is run, it will be ignored on subsequent
runs.
## Start the isle Service
You can double check that the daemon is running properly by pinging a private IP
from the network in a separate terminal:
Once installed and bootstrapped you can enable and start the isle service by
doing:
```
ping 10.10.0.1
```
If the pings are successful then your daemon is working!
## Installing the Daemon as a Systemd Service
NOTE in the future we will introduce an `install` sub-command which will
automate most of this section.
Rather than running the daemon manually, you can install it as a systemd
service. This way your daemon will automatically start in the background on
startup, and will be restarted if it has any issues.
To do so, create a file at `/etc/systemd/system/isle.service` with the
following contents:
```
[Unit]
Description=isle
Requires=network.target
After=network.target
[Service]
Restart=always
RestartSec=1s
User=root
ExecStart=/path/to/isle daemon
[Install]
WantedBy=multi-user.target
```
Remember to change the `/path/to/isle` part to the actual absolute path
to your binary!
Once created, perform the following commands in a terminal to enable the
service:
```
sudo systemctl daemon-reload
sudo systemctl enable --now isle
```
You can check the service's status by doing:
(NOTE If your distro uses an init system other than systemd then you will need
to instead start isle according to that system's requirements.)
## Join a Network
This section will guide you through the process of joining an existing network
of isle hosts. If instead you wish to create a new network for others to join
then see the [Creating a New Network][creating-a-new-network] page.
To join an existing network you will need to first obtain a `bootstrap.json`
file. The `bootstrap.json` file contains all information required for your
particular host to join the network, and must be generated and provided to you
by an admin for the network.
Once obtained, you can join the network by doing:
```
sudo systemctl status isle
isle network join --bootstrap-path /path/to/bootstrap.json
```
and you can view its full logs by doing:
After a few moments you will have successfully joined the network!
```
sudo journalctl -lu isle
```
TODO block the `network join` call until joining has succeeded, or display a failure reason.
[creating-a-new-network]: ../admin/creating-a-new-network.md
[latest]: https://code.betamike.com/micropelago/isle/releases/latest

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

@ -10,8 +10,7 @@ network's domain name.
If a request for a hostname not within the network's domain is received then the
server will forward the request to a pre-configured public resolver. The set of
public resolvers used can be configured using the
[daemon.yml](creating-a-daemonyml-file.md) file.
public resolvers used can be configured in the `/etc/isle/daemon.yml` file.
This DNS server is an optional feature of Isle, and not required in general for
making use of the network.