diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index afa66a0df..12c9d1397 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -11,6 +11,18 @@ defaults: shell: bash jobs: + lint-docs: + runs-on: macos-11 + steps: + - uses: actions/checkout@v2 + - uses: actions/setup-node@v2 + with: + node-version: '14.18.2' + - name: Lint Docs + run: | + npm install -g markdownlint-cli + markdownlint docs/ + static-analysis: runs-on: ubuntu-18.04 env: diff --git a/docs/.markdownlint.json b/docs/.markdownlint.json new file mode 100644 index 000000000..07e07965f --- /dev/null +++ b/docs/.markdownlint.json @@ -0,0 +1,5 @@ +{ + "MD002": { + "level": 2 + } +} diff --git a/docs/.markdownlintignore b/docs/.markdownlintignore new file mode 100644 index 000000000..57510a2be --- /dev/null +++ b/docs/.markdownlintignore @@ -0,0 +1 @@ +_site/ diff --git a/docs/README.md b/docs/README.md index 7d7c3b016..66a6d4129 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,13 +1,20 @@ + # Firezone Docs + ## Overview -This repository is for our documentation website found at https://docs.firez.one/. +This repository is for our documentation website found at +[https://docs.firez.one/](https://docs.firez.one). ## Contributing -We uses pages to organize our documentation. Please see the [Jekyll site](https://jekyllrb.com/docs/pages/) for more information. +We uses pages to organize our documentation. Please see the +[Jekyll site](https://jekyllrb.com/docs/pages/) for more information. ### Setup -We are using [Jekyll](https://jekyllrb.com/docs/) to generate the site and [Github Pages](https://pages.github.com/) to host it. When developing locally, you can use the [`jekyll serve`](https://jekyllrb.com/docs/serving-jekyll/) command to start a server from the `/docs` directory. \ No newline at end of file +We are using [Jekyll](https://jekyllrb.com/docs/) to generate the site and +[Github Pages](https://pages.github.com/) to host it. When developing locally, +you can use the [`jekyll serve`](https://jekyllrb.com/docs/serving-jekyll/) +command to start a server from the `/docs` directory. diff --git a/docs/_includes/footer_custom.html b/docs/_includes/footer_custom.html index 2457dedb1..8eecb82e3 100644 --- a/docs/_includes/footer_custom.html +++ b/docs/_includes/footer_custom.html @@ -1,6 +1,13 @@ {%- if site.footer_content -%}
-

For support, first visit our Discussion Forums

- Company | Github | Twitter +

+ For support, first visit our + Discussion Forums +

+ Company + | + Github + | + Twitter
{%- endif -%} diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html index b81d5eea5..964baf74c 100644 --- a/docs/_layouts/default.html +++ b/docs/_layouts/default.html @@ -135,12 +135,15 @@ layout: table_wrappers {% endif %} {% endunless %}
+

{{ page.title }}

+ {% if site.heading_anchors != false %} {% include vendor/anchor_headings.html html=content beforeHeading="true" anchorBody="" anchorClass="anchor-heading" anchorAttrs="aria-labelledby=\"%html_id%\"" %} {% else %} {{ content }} {% endif %} + {% if page.has_children == true and page.has_toc != false %}

Table of contents

diff --git a/docs/docs/administer/configure.md b/docs/docs/administer/configure.md new file mode 100644 index 000000000..abf0c91b0 --- /dev/null +++ b/docs/docs/administer/configure.md @@ -0,0 +1,18 @@ +--- +layout: default +title: Configure +nav_order: 1 +parent: Administer +--- +--- + +Firezone leverages [Chef Omnibus](https://github.com/chef/omnibus) to handle +release packaging, process supervision, log management, and more. + +The main configuration file is written in [Ruby](https://ruby-lang.org) and can +be found at `/etc/firezone/firezone.rb`. Changing this file **requires +re-running** `sudo firezone-ctl reconfigure` which triggers Chef to pick up the +changes and apply them to the running system. + +For an exhaustive list of configuration variables and their description, see +the [configuration file reference]({% link docs/reference/configuration-file.md %}). diff --git a/docs/docs/get-started/index.md b/docs/docs/administer/index.md similarity index 62% rename from docs/docs/get-started/index.md rename to docs/docs/administer/index.md index e9f595a61..a6d698730 100644 --- a/docs/docs/get-started/index.md +++ b/docs/docs/administer/index.md @@ -1,8 +1,6 @@ --- -layout: default -title: Get Started nav_order: 3 +layout: default +title: Administer has_children: true --- - -# Get Started diff --git a/docs/docs/usage/manage.md b/docs/docs/administer/manage.md similarity index 91% rename from docs/docs/usage/manage.md rename to docs/docs/administer/manage.md index f3e4287b9..13569174e 100644 --- a/docs/docs/usage/manage.md +++ b/docs/docs/administer/manage.md @@ -2,16 +2,16 @@ layout: default title: Manage Installation nav_order: 2 -parent: Usage +parent: Administer +--- --- -# Manage Installation +Your Firezone installation can be managed via the `firezone-ctl` command, as +shown below. Most subcommands require prefixing with `sudo`. ---- + -Your Firezone installation can be managed via the `firezone-ctl` command, as shown below. Most subcommands require prefixing with `sudo`. - -```console +```text root@demo:~# firezone-ctl I don't know that command. omnibus-ctl: command (subcommand) @@ -64,3 +64,5 @@ Service Management Commands: usr2 Send the services a USR2. ``` + + diff --git a/docs/docs/usage/security-considerations.md b/docs/docs/administer/security-considerations.md similarity index 77% rename from docs/docs/usage/security-considerations.md rename to docs/docs/administer/security-considerations.md index 4a44bf936..4766b7ded 100644 --- a/docs/docs/usage/security-considerations.md +++ b/docs/docs/administer/security-considerations.md @@ -1,18 +1,16 @@ --- layout: default title: Security Considerations -nav_order: 5 -parent: Usage +nav_order: 6 +parent: Administer --- - -# Security Considerations --- Firezone is still young software. For mission-critical applications, we recommend **limiting network access to the Web UI** (by default ports tcp/443 and tcp/80) to prevent exposing it to the public Internet at this time. -The WireGuard listen port (by default port udp/51821) can be safely exposed to +The WireGuard listen port (by default port udp/51820) can be safely exposed to allow user devices to connect. Traffic to this port is handled directly by the WireGuard kernel module. diff --git a/docs/docs/usage/troubleshoot.md b/docs/docs/administer/troubleshoot.md similarity index 80% rename from docs/docs/usage/troubleshoot.md rename to docs/docs/administer/troubleshoot.md index ed650c626..5b6ab290e 100644 --- a/docs/docs/usage/troubleshoot.md +++ b/docs/docs/administer/troubleshoot.md @@ -1,14 +1,11 @@ --- layout: default title: Troubleshoot -nav_order: 6 -parent: Usage +nav_order: 5 +parent: Administer --- -# Troubleshoot - --- - For any problems that arise, a good first bet is to check the Firezone logs. To view Firezone logs, run `sudo firezone-ctl tail`. diff --git a/docs/docs/usage/uninstall.md b/docs/docs/administer/uninstall.md similarity index 92% rename from docs/docs/usage/uninstall.md rename to docs/docs/administer/uninstall.md index c738936cb..27f5f1fe9 100644 --- a/docs/docs/usage/uninstall.md +++ b/docs/docs/administer/uninstall.md @@ -2,11 +2,7 @@ layout: default title: Uninstall nav_order: 4 -parent: Usage ---- - -# Uninstall - +parent: Administer --- To completely remove Firezone and its configuration files, run the [uninstall.sh diff --git a/docs/docs/usage/upgrade.md b/docs/docs/administer/upgrade.md similarity index 83% rename from docs/docs/usage/upgrade.md rename to docs/docs/administer/upgrade.md index 202bb1145..08763e265 100644 --- a/docs/docs/usage/upgrade.md +++ b/docs/docs/administer/upgrade.md @@ -2,18 +2,17 @@ layout: default title: Upgrade nav_order: 3 -parent: Usage ---- - -# Upgrade +parent: Administer --- Upgrading Firezone will disconnect all VPN connections and require shutting down the Web UI. We recommend a maintenance window of about an hour in case anything goes wrong during the upgrade. -To upgrade Firezone, simply download the new OS package, install it over the existing installation with `sudo dpkg -i firezone_X.X.X.deb` or -`sudo rpm -i --force firezone_X.X.X.rpm` and then run `sudo firezone-ctl reconfigure && sudo firezone-ctl restart`. +To upgrade Firezone, simply download the new OS package, install it over the +existing installation with `sudo dpkg -i firezone_X.X.X.deb` or +`sudo rpm -i --force firezone_X.X.X.rpm` and then run +`sudo firezone-ctl reconfigure && sudo firezone-ctl restart`. Occasionally problems arise. If you hit any, please let us know by [filing an issue](https://github.com/firezone/firezone/issues/new/choose). diff --git a/docs/docs/deploy/clients.md b/docs/docs/deploy/clients.md new file mode 100644 index 000000000..8b48a7bf6 --- /dev/null +++ b/docs/docs/deploy/clients.md @@ -0,0 +1,16 @@ +--- +layout: default +title: Install Clients +nav_order: 3 +parent: Deploy +--- +--- + +## Client Instructions + +End devices should download the latest version of the WireGuard client from +[https://www.wireguard.com/install/](https://www.wireguard.com/install/). +Once installed, clients can import the tunnel via the `.conf` file sent by the +administrator. + +![Client Instructions]({{ site.asset_urls.client_instructions }}) diff --git a/docs/docs/deploy/index.md b/docs/docs/deploy/index.md new file mode 100644 index 000000000..cb96b908a --- /dev/null +++ b/docs/docs/deploy/index.md @@ -0,0 +1,6 @@ +--- +layout: default +title: Deploy +nav_order: 2 +has_children: true +--- diff --git a/docs/docs/get-started/prerequisites.md b/docs/docs/deploy/prerequisites.md similarity index 80% rename from docs/docs/get-started/prerequisites.md rename to docs/docs/deploy/prerequisites.md index 9e8b3575f..589142c4a 100644 --- a/docs/docs/get-started/prerequisites.md +++ b/docs/docs/deploy/prerequisites.md @@ -2,15 +2,15 @@ layout: default title: Prerequisites nav_order: 1 -parent: Get Started +parent: Deploy +--- --- -# Prerequisites ---- +Firezone requires the setup of a DNS record and matching SSL certificate for +in production deployments. -Firezone requires the setup of a DNS record and matching SSL certificate to run -in production. Not using Firezone in production? [ -Skip directly to the installation guide]({% link docs/get-started/install.md %}). +Not using Firezone in production? [ +Skip to install the server]({% link docs/deploy/server.md %}). ## Create a DNS record @@ -27,6 +27,7 @@ you'll need a valid SSL certificate to use Firezone in a production capacity. We recommend using [Let's Encrypt](https://letsencrypt.org) to generate a free SSL cert for your domain. Firezone will include the ability to automatically generate valid SSL certificates for you in an upcoming release, -but for now these must be generated manually and specified in the configuration -file. See here for a guide on how to do so: +but for now these must be generated manually and specified in the main +configuration file at `/etc/firezone/firezone.rb`. See here for a guide on how +to do so: [https://eff-certbot.readthedocs.io/en/stable/using.html#manual](https://eff-certbot.readthedocs.io/en/stable/using.html#manual) diff --git a/docs/docs/deploy/server.md b/docs/docs/deploy/server.md new file mode 100644 index 000000000..900c919cc --- /dev/null +++ b/docs/docs/deploy/server.md @@ -0,0 +1,55 @@ +--- +layout: default +title: Install Server +nav_order: 2 +parent: Deploy +--- +--- + +**Important**: Ensure you've satisfied the +[prerequisites]({% link docs/deploy/prerequisites.md %}) before following this +guide. + + +## Installation Instructions + +**NOTE**: Firezone modifies the kernel netfilter and routing tables. Other +programs that modify the Linux routing table or netfilter firewall +will likely interfere with Firezone's operation. + +Assuming you're running a supported Linux kernel on one of the [distros +listed above](#supported-linux-distributions), follow these steps to install and +configure Firezone for first use: + +1. [Install WireGuard](https://www.wireguard.com/install/) for your distro. + If using Linux kernel 5.6 or higher, skip this step. +2. Download the relevant package for your distribution from the + [releases page](https://github.com/firezone/firezone/releases). +3. Install with `sudo rpm -i firezone*.rpm` or `sudo dpkg -i firezone*.deb` + depending on your distro. +4. Bootstrap the application with `sudo firezone-ctl reconfigure`. This will + initialize config files, set up needed services and generate the default + configuration. +5. Edit the default configuration located at `/etc/firezone/firezone.rb`. + At a minimum, you'll need to review the following configuration variables: + + ```ruby + # Auto-generated based on the server's hostname. + # Set this to the FQDN used to access the Web UI. + default['firezone']['fqdn'] = 'firezone.example.com' + + # Specify the path to your SSL cert and private key. + # If set to nil, a self-signed cert will be generated for you. + default['firezone']['ssl']['certificate'] = '/path/to/cert.pem' + default['firezone']['ssl']['certificate_key'] = '/path/to/key.pem' + ``` + +6. Reconfigure the application to pick up the new changes: + `sudo firezone-ctl reconfigure`. +7. Finally, create an admin user with `sudo firezone-ctl create-or-reset-admin`. + The login credentials will be printed to the console output. +8. Now you should be able to log into the web UI at the FQDN you specified in + step 5 above, e.g. `https://firezone.example.com` + +Next, proceed to [install WireGuard clients +]({% link docs/deploy/clients.md %}). diff --git a/docs/docs/deploy/supported-platforms.md b/docs/docs/deploy/supported-platforms.md new file mode 100644 index 000000000..c97527da8 --- /dev/null +++ b/docs/docs/deploy/supported-platforms.md @@ -0,0 +1,75 @@ +--- +layout: default +title: Supported Platforms +nav_order: 0 +parent: Deploy +--- +--- + +Firezone currently supports the following platforms: + + + +| OS | Architectures | Status | Notes | +| --- | --- | --- | --- | +| AmazonLinux 2 | `amd64` | **Fully-supported** | See [AmazonLinux 2 Notes](#amazonlinux-2-notes) | +| CentOS 7 | `amd64` | **Fully-supported** | See [CentOS 7 Notes](#centos-7-notes) | +| CentOS 8 | `amd64` | **Fully-supported** | See [CentOS 8 Notes](#centos-8-notes) | +| CentOS Stream 9 | `amd64` | **Fully-supported** | Works as-is | +| Debian 10 | `amd64` | **Fully-supported** | See [Debian 10 Notes](#debian-10-notes)| +| Debian 11 | `amd64` | **Fully-supported** | Works as-is | +| Fedora 33 | `amd64` | **Fully-supported** | Works as-is | +| Fedora 34 | `amd64` | **Fully-supported** | Works as-is | +| Fedora 35 | `amd64` | **Fully-supported** | Works as-is | +| Ubuntu 18.04 | `amd64` | **Fully-supported** | See [Ubuntu 18.04 Notes](#ubuntu-1804-notes) | +| Ubuntu 20.04 | `amd64` | **Fully-supported** | Works as-is | +| openSUSE Leap 15.3 | `amd64` | **Fully-supported** | See [openSUSE Notes](#opensuse-notes) | + + + +If your distro isn't listed here please +[open an issue](https://github.com/firezone/firezone/issues/new/choose) and let +us know. New distros are being supported on a regular basis and there's a good +chance yours will be added soon. + +### AmazonLinux 2 Notes + +Kernel upgrade required: + +```bash +sudo amazon-linux-extras install -y kernel-5.10 +``` + +### CentOS 7 Notes + +Kernel upgrade to 5.6+ required. See [this guide +](https://medium.com/@nazishalam07/update-centos-kernel-3-10-to-5-13-latest-9462b4f1e62c) +for an example. + +### CentOS 8 Notes + +The WireGuard kernel module needs to be installed: + +```bash +yum install elrepo-release epel-release +yum install kmod-wireguard +``` + +### Ubuntu 18.04 Notes + +Kernel upgrade to 5.4+ required. E.g. `apt install linux-image-generic-hwe-18.04` + +### Debian 10 Notes + +Kernel upgrade to 5.6+ required. See [this guide +](https://jensd.be/968/linux/install-a-newer-kernel-in-debian-10-buster-stable) +for an example. + +### openSUSE Notes + +Firezone requires the `setcap` utility, but some recent openSUSE releases may +not have it installed by default. To fix, ensure `libcap-progs` is installed: + +```shell +sudo zypper install libcap-progs +``` diff --git a/docs/docs/get-started/client-setup.md b/docs/docs/get-started/client-setup.md deleted file mode 100644 index 925185748..000000000 --- a/docs/docs/get-started/client-setup.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -layout: default -title: Client Setup -nav_order: 3 -parent: Get Started ---- - -# Client Setup and Usage - ---- - -## Adding Devices -Add a device through the Web UI by clicking the "Add Device" button under -`/devices` or `/users`. Once the device profile is created, you can send the -WireGuard configuration file to the client. - -## Client Instructions -Clients should download the latest version of the WireGuard client from -https://www.wireguard.com/install/. Once installed, clients can import the -tunnel via the `.conf` file sent by the administrator. - -![Client Instructions]({{ site.asset_urls.client_instructions }}) diff --git a/docs/docs/get-started/install.md b/docs/docs/get-started/install.md deleted file mode 100644 index d743b98af..000000000 --- a/docs/docs/get-started/install.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -layout: default -title: Install -nav_order: 2 -parent: Get Started ---- - -# Install -{: .no_toc } ---- - -**Important**: Ensure you've satisfied the [prerequisites]({% link docs/get-started/prerequisites.md %}) -before following this guide. - -## Table of Contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- - -## Supported Linux Distributions - -Firezone currently supports the following distributions and architectures: - -| Name | Architectures | Status | Notes | -| --- | --- | --- | --- | -| AmazonLinux 2 | `amd64` | **Fully-supported** | See [AmazonLinux 2 Notes](#amazonlinux-2-notes) | -| CentOS 7 | `amd64` | **Fully-supported** | See [CentOS 7 Notes](#centos-7-notes) | -| CentOS 8 | `amd64` | **Fully-supported** | See [CentOS 8 Notes](#centos-8-notes) | -| CentOS 8 | `amd64` | **Fully-supported** | Works as-is | -| Debian 10 | `amd64` | **Fully-supported** | See [Debian 10 Notes](#debian-10-notes)| -| Debian 11 | `amd64` | **Fully-supported** | Works as-is | -| Fedora 33 | `amd64` | **Fully-supported** | Works as-is | -| Fedora 34 | `amd64` | **Fully-supported** | Works as-is | -| Fedora 35 | `amd64` | **Fully-supported** | Works as-is | -| Ubuntu 18.04 | `amd64` | **Fully-supported** | See [Ubuntu 18.04 Notes](#ubuntu-1804-notes) | -| Ubuntu 20.04 | `amd64` | **Fully-supported** | Works as-is | -| openSUSE Leap 15.3 | `amd64` | **Fully-supported** | See [openSUSE Notes](#opensuse-notes) | - -If your distro isn't listed here please -[open an issue](https://github.com/firezone/firezone/issues/new/choose) and let -us know. New distros are being supported on a regular basis and there's a good -chance yours will be added soon. - -### AmazonLinux 2 Notes - -Kernel upgrade required: - -```bash -sudo amazon-linux-extras install -y kernel-5.10 -``` - -### CentOS 7 Notes - -Kernel upgrade to 4.19+ required. See [this guide -](https://medium.com/@nazishalam07/update-centos-kernel-3-10-to-5-13-latest-9462b4f1e62c) -for an example. - -### CentOS 8 Notes - -The WireGuard kernel module needs to be installed: - -```bash -yum install elrepo-release epel-release -yum install kmod-wireguard -``` - -### Ubuntu 18.04 Notes - -Kernel upgrade to 4.19+ required. E.g. `apt install linux-image-generic-hwe-18.04` - -### Debian 10 Notes - -Kernel upgrade to 5.6+ required. See [this guide -](https://jensd.be/968/linux/install-a-newer-kernel-in-debian-10-buster-stable) -for an example. - -### openSUSE Notes - -Firezone requires the `setcap` utility, but some recent openSUSE releases may -not have it installed by default. To fix, ensure `libcap-progs` is installed: - -```shell -sudo zypper install libcap-progs -``` - -## Installation Instructions - -**NOTE**: Firezone modifies the kernel netfilter and routing tables. Other -programs that modify the Linux routing table or netfilter firewall -will likely interfere with Firezone's operation. - -Assuming you're running Linux kernel 4.19+ on one of the supported distros -listed above, follow these steps to install and configure Firezone for first -use: - -1. [Install WireGuard](https://www.wireguard.com/install/) for your distro. If using Linux kernel 5.6 or higher, skip - this step. -2. Download the relevant package for your distribution from the - [releases page](https://github.com/firezone/firezone/releases). -3. Install with `sudo rpm -i firezone*.rpm` or `sudo dpkg -i firezone*.deb` - depending on your distro. -4. Bootstrap the application with `sudo firezone-ctl reconfigure`. This will initialize config files, set up needed services and generate the default configuration. -5. Edit the default configuration located at `/etc/firezone/firezone.rb`. - At a minimum, you'll need to review the following configuration variables: - - ```ruby - # Auto-generated based on the server's hostname. - # Set this to the FQDN used to access the Web UI. - default['firezone']['fqdn'] = 'firezone.example.com' - - # Specify the path to your SSL cert and private key. - # If set to nil, a self-signed cert will be generated for you. - default['firezone']['ssl']['certificate'] = '/path/to/cert.pem' - default['firezone']['ssl']['certificate_key'] = '/path/to/key.pem' - ``` -6. Reconfigure the application to pick up the new changes: `sudo firezone-ctl reconfigure`. -7. Finally, create an admin user with `sudo firezone-ctl create-or-reset-admin`. - The login credentials will be printed to the console output. -8. Now you should be able to log into the web UI at the FQDN you specified in - step 5 above, e.g. `https://firezone.example.com` - -Next, proceed to [read about using Firezone]({% link docs/usage/index.md %}). diff --git a/docs/docs/reference/_architecture.md b/docs/docs/reference/_architecture.md new file mode 100644 index 000000000..cdf5279f3 --- /dev/null +++ b/docs/docs/reference/_architecture.md @@ -0,0 +1,6 @@ +--- +layout: default +nav_order: 1 +title: Architecture +parent: Reference +--- diff --git a/docs/docs/reference/configuration-file.md b/docs/docs/reference/configuration-file.md new file mode 100644 index 000000000..997b04f23 --- /dev/null +++ b/docs/docs/reference/configuration-file.md @@ -0,0 +1,155 @@ +--- +layout: default +nav_order: 2 +title: Configuration File +parent: Reference +--- + +Shown below is a complete listing of the configuration options available in +`/etc/firezone/firezone.rb`. + +| option | description | default value | +| ----------------------------------------- | --------------------- | -------- | +| `default['firezone']['nginx']['enabled']` | Whether to enable the bundled nginx server | `true` | +| default['firezone']['fqdn'] = (node['fqdn'] || node['hostname']).downcase | +| default['firezone']['config_directory'] = '/etc/firezone' | +| default['firezone']['install_directory'] = '/opt/firezone' | +| default['firezone']['app_directory'] = "#{node['firezone']['install_directory']}/embedded/service/firezone" | +| default['firezone']['log_directory'] = '/var/log/firezone' | +| default['firezone']['var_directory'] = '/var/opt/firezone' | +| default['firezone']['user'] = 'firezone' | +| default['firezone']['group'] = 'firezone' | +| default['firezone']['admin_email'] = "firezone@localhost" | +| default['firezone']['egress_interface'] = nil | +| default['firezone']['fips_enabled'] = nil | +| default['enterprise']['name'] = 'firezone' | +| default['firezone']['install_path'] = node['firezone']['install_directory'] | +| default['firezone']['sysvinit_id'] = 'SUP' | +| default['firezone']['nginx']['enabled'] = true | +| default['firezone']['nginx']['force_ssl'] = true | +| default['firezone']['nginx']['non_ssl_port'] = 80 | +| default['firezone']['nginx']['ssl_port'] = 443 | +| default['firezone']['nginx']['directory'] = "#{node['firezone']['var_directory']}/nginx/etc" | +| default['firezone']['nginx']['log_directory'] = "#{node['firezone']['log_directory']}/nginx" | +| default['firezone']['nginx']['log_rotation']['file_maxbytes'] = 104857600 | +| default['firezone']['nginx']['log_rotation']['num_to_keep'] = 10 | +| default['firezone']['nginx']['log_x_forwarded_for'] = false | +| default['firezone']['nginx']['redirect_to_canonical'] = false | +| default['firezone']['nginx']['cache']['enabled'] = false | +| default['firezone']['nginx']['cache']['directory'] = "#{node['firezone']['var_directory']}/nginx/cache" | +| default['firezone']['nginx']['user'] = node['firezone']['user'] | +| default['firezone']['nginx']['group'] = node['firezone']['group'] | +| default['firezone']['nginx']['dir'] = node['firezone']['nginx']['directory'] | +| default['firezone']['nginx']['log_dir'] = node['firezone']['nginx']['log_directory'] | +| default['firezone']['nginx']['pid'] = "#{node['firezone']['nginx']['directory']}/nginx.pid" | +| default['firezone']['nginx']['daemon_disable'] = true | +| default['firezone']['nginx']['gzip'] = 'on' | +| default['firezone']['nginx']['gzip_static'] = 'off' | +| default['firezone']['nginx']['gzip_http_version'] = '1.0' | +| default['firezone']['nginx']['gzip_comp_level'] = '2' | +| default['firezone']['nginx']['gzip_proxied'] = 'any' | +| default['firezone']['nginx']['gzip_vary'] = 'off' | +| default['firezone']['nginx']['gzip_buffers'] = nil | +| default['firezone']['nginx']['gzip_types'] = %w( | +| text/plain | +| text/css | +| application/x-javascript | +| text/xml | +| application/xml | +| application/rss+xml | +| application/atom+xml | +| text/javascript | +| application/javascript | +| application/json | +| ) | +| default['firezone']['nginx']['gzip_min_length'] = 1000 | +| default['firezone']['nginx']['gzip_disable'] = 'MSIE [1-6]\.' | +| default['firezone']['nginx']['keepalive'] = 'on' | +| default['firezone']['nginx']['keepalive_timeout'] = 65 | +| default['firezone']['nginx']['worker_processes'] = node['cpu'] && node['cpu']['total'] ? node['cpu']['total'] : 1 | +| default['firezone']['nginx']['worker_connections'] = 1024 | +| default['firezone']['nginx']['worker_rlimit_nofile'] = nil | +| default['firezone']['nginx']['multi_accept'] = false | +| default['firezone']['nginx']['event'] = nil | +| default['firezone']['nginx']['server_tokens'] = nil | +| default['firezone']['nginx']['server_names_hash_bucket_size'] = 64 | +| default['firezone']['nginx']['sendfile'] = 'on' | +| default['firezone']['nginx']['access_log_options'] = nil | +| default['firezone']['nginx']['error_log_options'] = nil | +| default['firezone']['nginx']['disable_access_log'] = false | +| default['firezone']['nginx']['default_site_enabled'] = false | +| default['firezone']['nginx']['types_hash_max_size'] = 2048 | +| default['firezone']['nginx']['types_hash_bucket_size'] = 64 | +| default['firezone']['nginx']['proxy_read_timeout'] = nil | +| default['firezone']['nginx']['client_body_buffer_size'] = nil | +| default['firezone']['nginx']['client_max_body_size'] = '250m' | +| default['firezone']['nginx']['default']['modules'] = [] | +| default['firezone']['postgresql']['enabled'] = true | +| default['firezone']['postgresql']['username'] = node['firezone']['user'] | +| default['firezone']['postgresql']['data_directory'] = "#{node['firezone']['var_directory']}/postgresql/13.3/data" | +| default['firezone']['postgresql']['log_directory'] = "#{node['firezone']['log_directory']}/postgresql" | +| default['firezone']['postgresql']['log_rotation']['file_maxbytes'] = 104857600 | +| default['firezone']['postgresql']['log_rotation']['num_to_keep'] = 10 | +| default['firezone']['postgresql']['checkpoint_completion_target'] = 0.5 | +| default['firezone']['postgresql']['checkpoint_segments'] = 3 | +| default['firezone']['postgresql']['checkpoint_timeout'] = '5min' | +| default['firezone']['postgresql']['checkpoint_warning'] = '30s' | +| default['firezone']['postgresql']['effective_cache_size'] = '128MB' | +| default['firezone']['postgresql']['listen_address'] = '127.0.0.1' | +| default['firezone']['postgresql']['max_connections'] = 350 | +| default['firezone']['postgresql']['md5_auth_cidr_addresses'] = ['127.0.0.1/32', '::1/128'] | +| default['firezone']['postgresql']['port'] = 15432 | +| default['firezone']['postgresql']['shared_buffers'] = "#{(node['memory']['total'].to_i / 4) / 1024}MB" | +| default['firezone']['postgresql']['shmmax'] = 17179869184 | +| default['firezone']['postgresql']['shmall'] = 4194304 | +| default['firezone']['postgresql']['work_mem'] = '8MB' | +| default['firezone']['database']['user'] = node['firezone']['postgresql']['username'] | +| default['firezone']['database']['name'] = 'firezone' | +| default['firezone']['database']['host'] = node['firezone']['postgresql']['listen_address'] | +| default['firezone']['database']['port'] = node['firezone']['postgresql']['port'] | +| default['firezone']['database']['pool'] = [10, Etc.nprocessors].max | +| default['firezone']['database']['extensions'] = { 'plpgsql' => true, 'pg_trgm' => true } | +| default['firezone']['phoenix']['enabled'] = true | +| default['firezone']['phoenix']['port'] = 13000 | +| default['firezone']['phoenix']['log_directory'] = "#{node['firezone']['log_directory']}/phoenix" | +| default['firezone']['phoenix']['log_rotation']['file_maxbytes'] = 104857600 | +| default['firezone']['phoenix']['log_rotation']['num_to_keep'] = 10 | +| default['firezone']['wireguard']['enabled'] = true | +| default['firezone']['wireguard']['log_directory'] = "#{node['firezone']['log_directory']}/wireguard" | +| default['firezone']['wireguard']['log_rotation']['file_maxbytes'] = 104857600 | +| default['firezone']['wireguard']['log_rotation']['num_to_keep'] = 10 | +| default['firezone']['wireguard']['interface_name'] = 'wg-firezone' | +| default['firezone']['wireguard']['port'] = 51820 | +| default['firezone']['wireguard']['mtu'] = 1420 | +| default['firezone']['wireguard']['ipv4']['enabled'] = true | +| default['firezone']['wireguard']['ipv4']['network'] = '10.3.2.0/24' | +| default['firezone']['wireguard']['ipv4']['address'] = '10.3.2.1' | +| default['firezone']['wireguard']['ipv6']['enabled'] = true | +| default['firezone']['wireguard']['ipv6']['network'] = 'fd00::3:2:0/120' | +| default['firezone']['wireguard']['ipv6']['address'] = 'fd00::3:2:1' | +| default['firezone']['runit']['svlogd_bin'] = "#{node['firezone']['install_directory']}/embedded/bin/svlogd" | +| default['firezone']['ssl']['directory'] = '/var/opt/firezone/ssl' | +| default['firezone']['ssl']['enabled'] = true | +| default['firezone']['ssl']['certificate'] = nil | +| default['firezone']['ssl']['certificate_key'] = nil | +| default['firezone']['ssl']['ssl_dhparam'] = nil | +| default['firezone']['ssl']['country_name'] = 'US' | +| default['firezone']['ssl']['state_name'] = 'CA' | +| default['firezone']['ssl']['locality_name'] = 'San Francisco' | +| default['firezone']['ssl']['company_name'] = 'My Company' | +| default['firezone']['ssl']['organizational_unit_name'] = 'Operations' | +| default['firezone']['ssl']['email_address'] = 'you@example.com' | +| default['firezone']['ssl']['ciphers'] = 'ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA:AES256-SHA:AES:CAMELLIA:DES-CBC3-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH-DSS-DES-CBC3-SHA:!EDH-RSA-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA' | +| default['firezone']['ssl']['fips_ciphers'] = 'FIPS@STRENGTH:!aNULL:!eNULL' | +| default['firezone']['ssl']['protocols'] = 'TLSv1 TLSv1.1 TLSv1.2' | +| default['firezone']['ssl']['session_cache'] = 'shared:SSL:4m' | +| default['firezone']['ssl']['session_timeout'] = '5m' | +| default['firezone']['robots_allow'] = '/' | +| default['firezone']['robots_disallow'] = nil | +| default['firezone']['from_email'] = nil | +| default['firezone']['smtp_address'] = nil | +| default['firezone']['smtp_password'] = nil | +| default['firezone']['smtp_port'] = nil | +| default['firezone']['smtp_user_name'] = nil | +| default['firezone']['connectivity_checks']['enabled'] = true | +| default['firezone']['connectivity_checks']['interval'] = 3_600 | diff --git a/docs/docs/usage/index.md b/docs/docs/reference/index.md similarity index 64% rename from docs/docs/usage/index.md rename to docs/docs/reference/index.md index 48709d58d..5c3be38ec 100644 --- a/docs/docs/usage/index.md +++ b/docs/docs/reference/index.md @@ -1,8 +1,6 @@ --- layout: default -title: Usage +title: Reference nav_order: 4 has_children: true --- - -# Using Firezone diff --git a/docs/docs/usage/configure.md b/docs/docs/usage/configure.md deleted file mode 100644 index 6cada9975..000000000 --- a/docs/docs/usage/configure.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -layout: default -title: Configure -nav_order: 1 -parent: Usage ---- - -# Configure ---- - -User-configurable settings can be found in the main configuration file located -at `/etc/firezone/firezone.rb`. Changing this file **requires re-running** `sudo firezone-ctl reconfigure` to pick up -the changes and apply them to the running system. diff --git a/docs/docs/user-guides/add-devices.md b/docs/docs/user-guides/add-devices.md new file mode 100644 index 000000000..a6649eaeb --- /dev/null +++ b/docs/docs/user-guides/add-devices.md @@ -0,0 +1,10 @@ +--- +layout: default +title: Add Devices +nav_order: 2 +parent: User Guides +--- + +Add a device through the Web UI by clicking the "Add Device" button under +`/devices` or `/users`. Once the device profile is created, you can send the +WireGuard configuration file to the user. diff --git a/docs/docs/user-guides/add-users.md b/docs/docs/user-guides/add-users.md new file mode 100644 index 000000000..646e7bae0 --- /dev/null +++ b/docs/docs/user-guides/add-users.md @@ -0,0 +1,6 @@ +--- +layout: default +title: Add Users +nav_order: 1 +parent: User Guides +--- diff --git a/docs/docs/user-guides/common-configurations.md b/docs/docs/user-guides/common-configurations.md new file mode 100644 index 000000000..8bee21c45 --- /dev/null +++ b/docs/docs/user-guides/common-configurations.md @@ -0,0 +1,6 @@ +--- +layout: default +title: Common Configurations +nav_order: 1 +parent: User Guides +--- diff --git a/docs/docs/user-guides/index.md b/docs/docs/user-guides/index.md new file mode 100644 index 000000000..003dff9c2 --- /dev/null +++ b/docs/docs/user-guides/index.md @@ -0,0 +1,6 @@ +--- +layout: default +title: User Guides +nav_order: 5 +has_children: true +--- diff --git a/docs/index.md b/docs/index.md index 9818787d5..2076f3d23 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,14 +1,12 @@ --- -# Feel free to add content and custom Front Matter to this file. -# To modify the layout, see https://jekyllrb.com/docs/themes/#overriding-theme-defaults - layout: default title: Overview nav_order: 1 -description: "Firezone is a self-managed WireGuard-based VPN server and Linux firewall designed for simplicity and security." +description: > + Firezone is a self-managed WireGuard-based VPN server and Linux firewall + designed for simplicity and security. --- -# Overview --- [Firezone](https://firez.one) is an open source, self-hosted VPN server and @@ -17,14 +15,14 @@ your private network and internal applications from a simple Web UI. ## Quick Start -1. [Prepare for install]({% link docs/get-started/index.md %}) -2. [Install]({% link docs/get-started/install.md %}) -3. [Configure]({% link docs/usage/configure.md %}) +1. [Deploy]({% link docs/deploy/index.md %}) +1. [Administer]({% link docs/administer/index.md %}) +1. [User Guides]({% link docs/user-guides/index.md %}) ## Get Help -If you're looking for help installing and configuring Firezone, we're happy to -help. +If you're looking for help installing, configuring, or using Firezone, we're +happy to help. * [Discussion Forums](https://discourse.firez.one/) * [Public Slack Group](https://join.slack.com/t/firezone-users/shared_invite/zt-111043zus-j1lP_jP5ohv52FhAayzT6w)