From a0597889c3f8ef543a53a9e574685b95710ab659 Mon Sep 17 00:00:00 2001 From: rasmus-kirk Date: Wed, 13 Mar 2024 15:43:13 +0100 Subject: [PATCH] Updated docs --- README.md | 159 ++------------------------ docs/wiki/examples/example-1/index.md | 54 +++++++++ docs/wiki/examples/example-2/index.md | 91 +++++++++++++++ docs/wiki/expose/index.md | 54 +++++++++ docs/wiki/index.md | 4 + 5 files changed, 215 insertions(+), 147 deletions(-) create mode 100644 docs/wiki/examples/example-1/index.md create mode 100644 docs/wiki/examples/example-2/index.md create mode 100644 docs/wiki/expose/index.md diff --git a/README.md b/README.md index 7bac7f5..4a09173 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,8 @@ ![Logo](./docs/img/logo-2.png) -This is a Nixos module that aims to make the installation and management -of running the ["*Arrs"](https://wiki.servarr.com/) as easy, and pain free, -as possible. +This is a Nixos module that aims to make the installation and management of +a home media server as easy, and pain free, as possible. If you have problems or feedback, feel free to join [the discord](https://discord.gg/n9ga99KwWC). @@ -16,7 +15,7 @@ Note that this is still in a somewhat alpha state, beware! - Some options are mostly untested The general format won't change however. If you do still use it, any feedback -is greatly appreciated. +would be greatly appreciated. ## Features @@ -30,7 +29,7 @@ is greatly appreciated. - **Optional Dynamic DNS support:** If you use [Njalla](https://njal.la/) and don't have a static IP, you can use the `nixarr.ddns.njalla.enable` option to dynamically update a DNS record that points to the dynamic public - IP of your server. + IP of your server or your public VPN IP. - **Optional Automatic Port Forwarding:** This module has a UPNP support that lets services request ports from your router automatically, if you enable it. @@ -40,7 +39,7 @@ that is provided by most VPN providers: ```nix {.numberLines} nixarr.vpn = { enable = true; - # IMPORTANT: This file must _not_ be in the config git directory + # WARNING: This file must _not_ be in the config git directory # You can usually get this wireguard file from your VPN provider wgConf = "/data/.secret/wg.conf"; } @@ -52,12 +51,16 @@ because it can cause rate limiting issues. ## Options The documentation for the options can be found -[here](https://nixarr.rasmuskirk.com/options) +[here](https://nixarr.rasmuskirk.com/options.html) ## The Wiki -If you want to know how to setup DDNS with Njalla, or how to manage secrets -in nix, check out the [wiki](https://nixarr.rasmuskirk.com/wiki/) +If you want to know how to setup DDNS with Njalla, how to manage secrets in +nix or examples, check out the [wiki](https://nixarr.rasmuskirk.com/wiki/) + +## Examples + +See the [wiki](https://nixarr.rasmuskirk.com/wiki). ## Importing this module @@ -94,144 +97,6 @@ like shown in this example flake: } ``` -## Examples - -This example does the following: - -- Runs a jellyfin server and exposes it to the internet with HTTPS support. -- Runs the transmission torrent client through a vpn -- Runs all "*Arrs" supported by this module - -```nix {.numberLines} - nixarr = { - enable = true; - # These two values are also the default, but you can set them to whatever - # else you want - # WARNING: Do _not_ set them to `/home/user/whatever`, it will not work! - mediaDir = "/data/media"; - stateDir = "/data/media/.state/nixarr"; - - vpn = { - enable = true; - # WARNING: This file must _not_ be in the config git directory - # You can usually get this wireguard file from your VPN provider - wgConf = "/data/.secret/wg.conf"; - }; - - jellyfin = { - enable = true; - # These options set up a nginx HTTPS reverse proxy, so you can access - # Jellyfin on your domain with HTTPS - expose.https = { - enable = true; - domainName = "your.domain.com"; - acmeMail = "your@email.com"; # Required for ACME-bot - }; - }; - - transmission = { - enable = true; - vpn.enable = true; - peerPort = 50000; # Set this to the port forwarded by your VPN - }; - - # It is possible for this module to run the *Arrs through a VPN, but it - # is generally not recommended, as it can cause rate-limiting issues. - bazarr.enable = true; - sonarr.enable = true; - radarr.enable = true; - prowlarr.enable = true; - readarr.enable = true; - lidarr.enable = true; - }; -``` - -Another example where port forwarding is not an option. This is useful if, -for example, you're living in a dorm that does not allow port forwarding. This -example does the following: - -- Runs Jellyfin and exposes it to the internet on a set port -- Starts openssh and runs it through the VPN so that it can be accessed - outside your home network -- Runs all the supported "*Arrs" - -**Warning:** This is largely untested ATM! - -```nix {.numberLines} - nixarr = { - enable = true; - - vpn = { - enable = true; - wgConf = "/data/.secret/wg.conf"; - }; - - jellyfin = { - enable = true; - vpn.enable = true; - - # Access the Jellyfin web-ui from the internet. - # Get this port from your VPN provider - expose.vpn = { - enable = true; - port = 12345; - }; - }; - - # Setup SSH service that runs through VPN. - # Lets you connect through ssh from the internet without having access to - # port forwarding - openssh.expose.vpn.enable = true; - - transmission = { - enable = true; - vpn.enable = true; - peerPort = 50000; # Set this to the port forwarded by your VPN - }; - - sonarr.enable = true; - radarr.enable = true; - prowlarr.enable = true; - readarr.enable = true; - lidarr.enable = true; - }; - - # The `openssh.vpn.enable` option does not enable openssh, so we do that here: - # We disable password authentication as it's generally insecure. - services.openssh = { - enable = true; - settings.PasswordAuthentication = false; - # Get this port from your VPN provider - ports = [ 54321 ] - }; - # Adds your public keys as trusted devices - users.extraUsers.username.openssh.authorizedKeys.keyFiles = [ - ./path/to/public/key/machine.pub} - ]; -``` - -In both examples, you don't have access to the "*Arrs" or torrent client -without being on your home network or accessing them through localhost. If -you have SSH setup you can use SSH tunneling. Simply run: - -```sh - ssh -N user@ip \ - -L 6001:localhost:9091 \ - -L 6002:localhost:9696 \ - -L 6003:localhost:8989 \ - -L 6004:localhost:7878 \ - -L 6005:localhost:8686 \ - -L 6006:localhost:8787 -``` - -Replace `user` with your user and `ip` with the public ip, or domain if set -up, of your server. This lets you access the services on `localhost:6000` -through `localhost:6006`. - -Another solution is to use [tailscale](https://tailscale.com/) or to setup -your own VPN [manually with wireguard](https://nixos.wiki/wiki/WireGuard). - - ## VPN Providers Your VPN-provider should at the very least support wg-quick configurations, diff --git a/docs/wiki/examples/example-1/index.md b/docs/wiki/examples/example-1/index.md new file mode 100644 index 0000000..97f9ac5 --- /dev/null +++ b/docs/wiki/examples/example-1/index.md @@ -0,0 +1,54 @@ +--- +title: Basic Example +--- + +This example does the following: + +- Runs a jellyfin server and exposes it to the internet with HTTPS support. +- Runs the transmission torrent client through a vpn +- Runs all "*Arrs" supported by this module + +```nix {.numberLines} + nixarr = { + enable = true; + # These two values are also the default, but you can set them to whatever + # else you want + # WARNING: Do _not_ set them to `/home/user/whatever`, it will not work! + mediaDir = "/data/media"; + stateDir = "/data/media/.state/nixarr"; + + vpn = { + enable = true; + # WARNING: This file must _not_ be in the config git directory + # You can usually get this wireguard file from your VPN provider + wgConf = "/data/.secret/wg.conf"; + }; + + jellyfin = { + enable = true; + # These options set up a nginx HTTPS reverse proxy, so you can access + # Jellyfin on your domain with HTTPS + expose.https = { + enable = true; + domainName = "your.domain.com"; + acmeMail = "your@email.com"; # Required for ACME-bot + }; + }; + + transmission = { + enable = true; + vpn.enable = true; + peerPort = 50000; # Set this to the port forwarded by your VPN + }; + + # It is possible for this module to run the *Arrs through a VPN, but it + # is generally not recommended, as it can cause rate-limiting issues. + bazarr.enable = true; + lidarr.enable = true; + prowlarr.enable = true; + radarr.enable = true; + readarr.enable = true; + sonarr.enable = true; + }; +``` + diff --git a/docs/wiki/examples/example-2/index.md b/docs/wiki/examples/example-2/index.md new file mode 100644 index 0000000..95fd464 --- /dev/null +++ b/docs/wiki/examples/example-2/index.md @@ -0,0 +1,91 @@ +--- +title: Example Configuration where Port Forwarding is not an Option +--- + +An example where port forwarding is not an option. This is useful if, +for example, you're living in a dorm that does not allow it. This +example does the following: + +- Runs Jellyfin and exposes it to the internet on a set port +- Starts openssh and runs it through the VPN so that it can be accessed + outside your home network +- Runs all the supported "*Arrs" + +**Warning:** This is largely untested ATM! + +```nix {.numberLines} + nixarr = { + enable = true; + + vpn = { + enable = true; + wgConf = "/data/.secret/wg.conf"; + }; + + jellyfin = { + enable = true; + vpn.enable = true; + + # Access the Jellyfin web-ui from the internet. + # Get this port from your VPN provider + expose.vpn = { + enable = true; + port = 12345; + }; + }; + + # Setup SSH service that runs through VPN. + # Lets you connect through ssh from the internet without having access to + # port forwarding + openssh.expose.vpn.enable = true; + + transmission = { + enable = true; + vpn.enable = true; + peerPort = 50000; # Set this to the port forwarded by your VPN + }; + + bazarr.enable = true; + sonarr.enable = true; + radarr.enable = true; + prowlarr.enable = true; + readarr.enable = true; + lidarr.enable = true; + }; + + # The `openssh.vpn.enable` option does not enable openssh, so we do that here: + # We disable password authentication as it's generally insecure. + services.openssh = { + enable = true; + settings.PasswordAuthentication = false; + # Get this port from your VPN provider + ports = [ 54321 ] + }; + # Adds your public keys as trusted devices + users.extraUsers.username.openssh.authorizedKeys.keyFiles = [ + ./path/to/public/key/machine.pub} + ]; +``` + +This example uses SSH tunneling to expose most of your services. See the +[expose](/wiki/expose) wiki page for more info on how to safely access +your services. + +In this example, you don't have access to any services without being on your +home network or accessing them through localhost. If you have SSH setup you +can use SSH tunneling. Simply run: + +```sh + ssh -N user@ip \ + -L 6001:localhost:9091 \ + -L 6002:localhost:9696 \ + -L 6003:localhost:8989 \ + -L 6004:localhost:7878 \ + -L 6005:localhost:8686 \ + -L 6006:localhost:8787 \ + -L 6007:localhost:6767 +``` + +Replace `user` with your user and `ip` with the public ip, or domain if set +up, of your server. This lets you access the services on `localhost:6001` +through `localhost:6007`. diff --git a/docs/wiki/expose/index.md b/docs/wiki/expose/index.md new file mode 100644 index 0000000..33aae06 --- /dev/null +++ b/docs/wiki/expose/index.md @@ -0,0 +1,54 @@ +--- +title: Exposing Services Safely +--- + +The concept of "exposing" will in this context mean to access your services +outside your home network. The simplest and safest way to access your services +is from inside your home network, please consider if this covers your +needs. If not, keep reading. + +## VPN + +The safest way to expose your services is through +a VPN. I suggest you use [tailscale](https://tailscale.com/) or to setup +your own VPN [manually with wireguard](https://nixos.wiki/wiki/WireGuard). + +## SSH Tunneling + +A practically equally safe way to expose your services is with SSH tunneling. +You will either need to port forward on your router, or [run the openssh +service through a VPN](/options.html#nixarr.openssh.expose.vpn.enable), +and port forward through your VPN-provider. Then you can access your services +from a remote machine using the following command: + +```sh + ssh -N user@ip \ + -L 6001:localhost:9091 \ + -L 6002:localhost:9696 \ + -L 6003:localhost:8989 \ + -L 6004:localhost:7878 \ + -L 6005:localhost:8686 \ + -L 6006:localhost:8787 \ + -L 6007:localhost:6767 +``` + +Replace `user` with your user and `ip` with the public ip, or domain if set +up, of your server. This lets you access the services on `localhost:6001` +through `localhost:6007`. [Example 2](/wiki/examples/example-2) has an +example configuration for this. + +**Warning:** Disable password authentication if you use SSH, it's insecure! + +## Without Authentication + +The most unsafe way, is to expose your services to the internet without SSH +tunneling or VPN. This lets anyone on the internet connect to your services, +and you rely solely on the security of said services, not the much more +robust public key cryptogaphy of the solutions above! While it is not +recommended, it may be necessary depending on your setup. + +The Jellyfin module, helpfully, has options for this, the +[`nixarr.jellyfin.expose.https.enable`](/options.html#nixarr.jellyfin.expose.https.enable) +and the +[`nixarr.jellyfin.expose.vpn.enable`](/options.html#nixarr.jellyfin.expose.vpn.enable) +options. Read the related documentation for more information. diff --git a/docs/wiki/index.md b/docs/wiki/index.md index 8da61f0..059a695 100644 --- a/docs/wiki/index.md +++ b/docs/wiki/index.md @@ -7,6 +7,10 @@ This is an index of existing articles: - **[Recommended Secrets Management](/wiki/secrets)** - **DDNS** - **[Njalla](/wiki/ddns/njalla)** +- **Examples** + - **[Basic Example](/wiki/examples/example-1)** + - **[Example Configuration where Port Forwading is not an Option](/wiki/examples/example-2)** +- **[Exposing Services Safely](/wiki/expose)** For learning how to setup the "*Arrs", once running, refer to the [servarr wiki](https://wiki.servarr.com/)