From ce5df164e1b8b848fe3d0561b55a477421e38963 Mon Sep 17 00:00:00 2001 From: Brian Picciano Date: Sun, 7 Jul 2024 13:37:26 +0200 Subject: [PATCH] Update documentation --- README.md | 7 +- docs/admin/adding-a-host-to-the-network.md | 43 +----- docs/admin/creating-a-new-network.md | 22 ++- docs/dev/design-principles.md | 2 +- docs/dev/releases.md | 2 +- docs/glossary.md | 6 +- docs/operator/contributing-a-lighthouse.md | 13 +- docs/operator/contributing-storage.md | 9 +- docs/operator/firewalls.md | 4 +- docs/roadmap.md | 54 +++---- docs/user/creating-a-daemonyml-file.md | 32 ---- docs/user/getting-started.md | 172 +++++++++++---------- docs/user/using-dns.md | 3 +- 13 files changed, 146 insertions(+), 223 deletions(-) delete mode 100644 docs/user/creating-a-daemonyml-file.md diff --git a/README.md b/README.md index da75642..760a42f 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/docs/admin/adding-a-host-to-the-network.md b/docs/admin/adding-a-host-to-the-network.md index 552ff7c..1d9dc41 100644 --- a/docs/admin/adding-a-host-to-the-network.md +++ b/docs/admin/adding-a-host-to-the-network.md @@ -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 | 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 -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. diff --git a/docs/admin/creating-a-new-network.md b/docs/admin/creating-a-new-network.md index 32f380d..f35e0e0 100644 --- a/docs/admin/creating-a-new-network.md +++ b/docs/admin/creating-a-new-network.md @@ -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 \ --ip-net \ --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/ diff --git a/docs/dev/design-principles.md b/docs/dev/design-principles.md index a7628a3..52e9001 100644 --- a/docs/dev/design-principles.md +++ b/docs/dev/design-principles.md @@ -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. diff --git a/docs/dev/releases.md b/docs/dev/releases.md index 48c1ddf..65df939 100644 --- a/docs/dev/releases.md +++ b/docs/dev/releases.md @@ -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. diff --git a/docs/glossary.md b/docs/glossary.md index ac0f2ba..a740d9b 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -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. - diff --git a/docs/operator/contributing-a-lighthouse.md b/docs/operator/contributing-a-lighthouse.md index f1d8d24..48270ee 100644 --- a/docs/operator/contributing-a-lighthouse.md +++ b/docs/operator/contributing-a-lighthouse.md @@ -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 diff --git a/docs/operator/contributing-storage.md b/docs/operator/contributing-storage.md index c5e2c0b..d0190dc 100644 --- a/docs/operator/contributing-storage.md +++ b/docs/operator/contributing-storage.md @@ -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 diff --git a/docs/operator/firewalls.md b/docs/operator/firewalls.md index b4f3ecc..a9d3dae 100644 --- a/docs/operator/firewalls.md +++ b/docs/operator/firewalls.md @@ -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. diff --git a/docs/roadmap.md b/docs/roadmap.md index 71971a5..5524d42 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -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 diff --git a/docs/user/creating-a-daemonyml-file.md b/docs/user/creating-a-daemonyml-file.md deleted file mode 100644 index b55903f..0000000 --- a/docs/user/creating-a-daemonyml-file.md +++ /dev/null @@ -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. - diff --git a/docs/user/getting-started.md b/docs/user/getting-started.md index 26184fc..52aad6b 100644 --- a/docs/user/getting-started.md +++ b/docs/user/getting-started.md @@ -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 diff --git a/docs/user/using-dns.md b/docs/user/using-dns.md index fcbb155..0a7e40d 100644 --- a/docs/user/using-dns.md +++ b/docs/user/using-dns.md @@ -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.