From 98da8d802fb248b1bb9ff7ea37e1b0aeef549fd0 Mon Sep 17 00:00:00 2001 From: Brian Picciano Date: Wed, 18 Dec 2024 21:54:15 +0100 Subject: [PATCH] More documentation updates, notably filling out firewall configuration --- docs/command-line.md | 2 +- docs/dev/building.md | 4 +- docs/dev/rebuilding-documentation.md | 2 +- docs/dev/testing.md | 4 +- docs/install.md | 12 +- docs/operator/configuring-networks.md | 4 +- .../operator/contributing-a-public-address.md | 10 +- docs/operator/contributing-storage.md | 44 +++---- docs/operator/firewalls.md | 116 +++++++++++++++--- docs/operator/managing-garage.md | 16 +-- docs/user/join-a-network.md | 2 +- docs/user/using-dns.md | 2 +- 12 files changed, 150 insertions(+), 68 deletions(-) diff --git a/docs/command-line.md b/docs/command-line.md index 233aed8..29de7a2 100644 --- a/docs/command-line.md +++ b/docs/command-line.md @@ -38,8 +38,8 @@ Documentation for operators: * [Configuring Networks](./operator/configuring-networks.md) * [Contributing Storage](./operator/contributing-storage.md) * [Contributing a Public Address](./operator/contributing-a-public-address.md) +* [Configuring Firewalls](./operator/firewalls.md) * [Managing garage](./operator/managing-garage.md) -* [Firewalls](./operator/firewall.md) [ddns]: https://www.cloudflare.com/learning/dns/glossary/dynamic-dns/ diff --git a/docs/dev/building.md b/docs/dev/building.md index 895745e..08f4b2f 100644 --- a/docs/dev/building.md +++ b/docs/dev/building.md @@ -17,7 +17,7 @@ issue][tmpdir-gh].)) You can build an AppImage for your current system by running the following from the project's root: -``` +```bash nix-build -A build.appImage ``` @@ -27,7 +27,7 @@ The resulting binary can be found under `result/bin`. An AppImage can be cross-compiled by passing the `hostSystem` argument: -``` +```bash nix-build --argstr hostSystem "x86_64-linux" -A build.appImage ``` diff --git a/docs/dev/rebuilding-documentation.md b/docs/dev/rebuilding-documentation.md index 89f1159..c19576f 100644 --- a/docs/dev/rebuilding-documentation.md +++ b/docs/dev/rebuilding-documentation.md @@ -5,7 +5,7 @@ which do not require any build step. There are a few other kinds of files, such as `.plantuml` files, which do require a build step. If these are changed then their artifacts should be rebuilt by doing: -``` +```bash cd docs nix-shell ``` diff --git a/docs/dev/testing.md b/docs/dev/testing.md index 32cf168..2911a31 100644 --- a/docs/dev/testing.md +++ b/docs/dev/testing.md @@ -3,7 +3,7 @@ All tests are currently written as go tests, and as such can be run from the `go` directory using the normal go testing tool. -``` +```bash cd go go test -run Foo ./daemon go test ./... # Test everything @@ -30,7 +30,7 @@ By running tests using the `go/integration_test.sh` script the tests will be automatically run in the integration test environment. All arguments will be passed directly to the go testing tool. -``` +```bash cd go ./integration_test.sh -run Foo ./daemon ``` diff --git a/docs/install.md b/docs/install.md index 7133a87..fba12ed 100644 --- a/docs/install.md +++ b/docs/install.md @@ -25,7 +25,7 @@ Download the latest `.pkg.tar.zst` package file for your platform from Install the package using pacman: -``` +```bash sudo pacman -U /path/to/isle-*.pkg.tar.zst ``` @@ -38,13 +38,15 @@ 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: -``` + +```bash mkdir -p /etc/isle/ isle daemon --dump-config > /etc/isle/daemon.yml ``` Create a system user for the isle daemon to run as: -``` + +```bash useradd -r -s /bin/false -C "isle Daemon" isle ``` @@ -69,7 +71,7 @@ Isle](./dev/building.md) document. If you wish to run isle commands as a user other than root, you can add that user to the `isle` group: -``` +```bash sudo usermod -aG isle username ``` @@ -78,7 +80,7 @@ sudo usermod -aG isle username Once installed and bootstrapped you can enable and start the isle service by doing: -``` +```bash sudo systemctl enable --now isle ``` diff --git a/docs/operator/configuring-networks.md b/docs/operator/configuring-networks.md index a50c554..28d2699 100644 --- a/docs/operator/configuring-networks.md +++ b/docs/operator/configuring-networks.md @@ -25,8 +25,8 @@ 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 +isle vpn public-address unset +# [4] Network configuration is managed by the daemon.yml ``` ## Configuration File (daemon.yml) diff --git a/docs/operator/contributing-a-public-address.md b/docs/operator/contributing-a-public-address.md index 7afcb19..5924f2f 100644 --- a/docs/operator/contributing-a-public-address.md +++ b/docs/operator/contributing-a-public-address.md @@ -36,13 +36,13 @@ 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 get +# No public address configured -# isle vpn public-address set --to some-host.mydomain.com:5678 +isle vpn public-address set --to some-host.mydomain.com:5678 -# isle vpn public-address get -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 diff --git a/docs/operator/contributing-storage.md b/docs/operator/contributing-storage.md index 434f79e..a31dd2e 100644 --- a/docs/operator/contributing-storage.md +++ b/docs/operator/contributing-storage.md @@ -20,22 +20,22 @@ 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 allocations list +# [] -# isle storage allocation add \ +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 +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 @@ -55,19 +55,19 @@ 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 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 allocation remove --index=0 -# isle storage allocations list -[] +isle storage allocations list +# [] ``` Once removed, it is advisable to wait some time before removing storage diff --git a/docs/operator/firewalls.md b/docs/operator/firewalls.md index 5cd7efa..99a00d3 100644 --- a/docs/operator/firewalls.md +++ b/docs/operator/firewalls.md @@ -1,4 +1,4 @@ -# Firewalls +# Configuring Firewalls When providing resources on your host, whether [network](./contributing-a-public-address.md) or @@ -8,20 +8,6 @@ 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. -## VPN Firewall - -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 using the `isle vpn firewall` set of -sub-commands, or using the [configuration file][configfile]. - -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 @@ -42,9 +28,103 @@ iptables configuration: 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. You will need to manually specify any configured storage +If you don't feel comfortable allowing Isle to deal with all packet filtering, +you will need to manually determine and add the ports for each service to your +host's firewall. You will need to manually specify any configured storage allocation ports if this is the approach you take. +## VPN Firewall + +Isle uses the [nebula][nebula] project to provide its VPN layer. Nebula ships +with its own [builtin firewall][nebulafirewall], which only applies to +connections coming in over the virtual network interface which it creates. This +firewall can be manually configured using the `isle vpn firewall` set of +sub-commands, or using the [configuration file][configfile]. + +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. + +[nebula]: https://github.com/slackhq/nebula +[nebulafirewall]: https://nebula.defined.net/docs/config/firewall [configfile]: ./configuring-networks.md + +### Configuring the VPN Firewall + +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 firewall` sub-commands are used to configure the VPN's firewall. +Without any flags the `isle vpn firewall show` command will display the +currently active firewall. + +```bash +isle vpn firewall show +# outbound: +# - index: 0 +# port: any +# proto: any +# host: any +# inbound: +# - index: 0 +# port: any +# proto: icmp +# host: any +# - index: 1 +# port: "22" +# proto: tcp +# host: my-laptop +``` + +When making changes to the firewall, all changes are first applied to a staging +version of the firewall. The staged version can be viewed by adding the +`--staged` flag to the `show` sub-command. + +```bash +isle vpn firewall remove --from inbound --indexes 1 + +isle vpn firewall show --staged +# outbound: +# - index: 0 +# port: any +# proto: any +# host: any +# inbound: +# - index: 0 +# port: any +# proto: icmp +# host: any + +isle vpn firewall add --to inbound --port 53 --proto udp --host any + +isle vpn firewall show --staged +# outbound: +# - index: 0 +# port: any +# proto: any +# host: any +# inbound: +# - index: 0 +# port: any +# proto: icmp +# host: any +# - index: 1 +# port: "53" +# proto: udp +# host: any +``` + +Once the staged firewall is in the desired state, it can be applied using the +`commit` sub-command. + +```bash +isle vpn firewall commit +``` + + If you wish to instead discard all staged changes you can use the `reset` + sub-commmand. + +```bash +isle vpn firewall reset +``` diff --git a/docs/operator/managing-garage.md b/docs/operator/managing-garage.md index 3c82616..f99c992 100644 --- a/docs/operator/managing-garage.md +++ b/docs/operator/managing-garage.md @@ -29,8 +29,8 @@ do so if necessary. Every `isle` binary contains a full `garage` binary embedded into it. This binary can be accessed directly like so: -``` -sudo isle garage cli +```bash +isle garage cli ``` Before handing off execution to the `garage` binary, the `isle` process @@ -46,20 +46,20 @@ connected to. To display the current layout of the garage cluster: -``` -sudo isle garage cli layout show +```bash +isle garage cli layout show ``` **(DO NOT CHANGE THE CLUSTER LAYOUT UNLESS YOU KNOW WHAT YOU'RE DOING!)** To create a new bucket: -``` -sudo isle garage cli bucket create new-bucket +```bash +isle garage cli bucket create new-bucket ``` To list existing buckets: -``` -sudo isle garage cli bucket list +```bash +isle garage cli bucket list ``` diff --git a/docs/user/join-a-network.md b/docs/user/join-a-network.md index c6eddbb..150c126 100644 --- a/docs/user/join-a-network.md +++ b/docs/user/join-a-network.md @@ -11,7 +11,7 @@ by an admin for the network. Once obtained, you can join the network by doing: -``` +```bash isle network join --bootstrap-path /path/to/bootstrap.json ``` diff --git a/docs/user/using-dns.md b/docs/user/using-dns.md index dbe4b65..7adc9c4 100644 --- a/docs/user/using-dns.md +++ b/docs/user/using-dns.md @@ -21,7 +21,7 @@ the network is `10.10.1.1`, and my network's domain is `cool.internal`. In order to configure the host to use the isle DNS server for all DNS requests, I could do something like this: -``` +```bash sudo su echo "nameserver 10.10.1.1" > /etc/resolv.conf ```