More documentation updates, notably filling out firewall configuration

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/
 

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

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

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

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

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)

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

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

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
+```

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 <subcmd> <args>
+```bash
+isle garage cli <subcmd> <args>
 ```
 
 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
 ```

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

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