From 4eec05762c665b2c2a38b3c37e637b7f067a30ef Mon Sep 17 00:00:00 2001 From: core Date: Sun, 8 Oct 2023 00:54:52 -0400 Subject: [PATCH] config reference --- docs/docs/disclaimer.md | 3 + docs/docs/intro.md | 44 +------------ docs/docs/tfcli/_category_.json | 8 +++ docs/docs/tfcli/intro.md | 5 ++ docs/docs/tfclient/_category_.json | 8 +++ docs/docs/tfclient/intro.md | 5 ++ docs/docs/tfweb/_category_.json | 8 +++ docs/docs/tfweb/intro.md | 5 ++ docs/docs/trifid-api/_category_.json | 8 +++ .../config_reference/_category_.json | 8 +++ .../config_reference/cryptography.md | 33 ++++++++++ .../trifid-api/config_reference/database.md | 61 +++++++++++++++++++ .../trifid-api/config_reference/server.md | 19 ++++++ .../trifid-api/config_reference/tokens.md | 42 +++++++++++++ docs/docs/trifid-api/intro.md | 12 ++++ docs/docs/tutorial-basics/_category_.json | 2 +- docs/docs/tutorial-extras/_category_.json | 2 +- docs/docusaurus.config.js | 25 +++++++- docs/src/components/HomepageFeatures/index.js | 19 +++--- .../img/undraw_fast_loading_re_8oi3.svg | 1 + .../img/undraw_secure_server_re_8wsq.svg | 1 + .../img/undraw_setup_wizard_re_nday.svg | 1 + docs/static/img/undraw_speed_test_re_pe1f.svg | 1 + 23 files changed, 264 insertions(+), 57 deletions(-) create mode 100644 docs/docs/disclaimer.md create mode 100644 docs/docs/tfcli/_category_.json create mode 100644 docs/docs/tfcli/intro.md create mode 100644 docs/docs/tfclient/_category_.json create mode 100644 docs/docs/tfclient/intro.md create mode 100644 docs/docs/tfweb/_category_.json create mode 100644 docs/docs/tfweb/intro.md create mode 100644 docs/docs/trifid-api/_category_.json create mode 100644 docs/docs/trifid-api/config_reference/_category_.json create mode 100644 docs/docs/trifid-api/config_reference/cryptography.md create mode 100644 docs/docs/trifid-api/config_reference/database.md create mode 100644 docs/docs/trifid-api/config_reference/server.md create mode 100644 docs/docs/trifid-api/config_reference/tokens.md create mode 100644 docs/docs/trifid-api/intro.md create mode 100644 docs/static/img/undraw_fast_loading_re_8oi3.svg create mode 100644 docs/static/img/undraw_secure_server_re_8wsq.svg create mode 100644 docs/static/img/undraw_setup_wizard_re_nday.svg create mode 100644 docs/static/img/undraw_speed_test_re_pe1f.svg diff --git a/docs/docs/disclaimer.md b/docs/docs/disclaimer.md new file mode 100644 index 0000000..ce610ad --- /dev/null +++ b/docs/docs/disclaimer.md @@ -0,0 +1,3 @@ +# Disclaimer + +trifid-api and the Trifid project are in no way intended to disrupt Defined Networking's buisness. Please, if you are a commercial customer, use their service instead. Trifid was developed and released with the full knowledge and permission of the Defined Networking team. \ No newline at end of file diff --git a/docs/docs/intro.md b/docs/docs/intro.md index 8a2e69d..964e5a4 100644 --- a/docs/docs/intro.md +++ b/docs/docs/intro.md @@ -2,46 +2,6 @@ sidebar_position: 1 --- -# Tutorial Intro +# Trifid Introduction -Let's discover **Docusaurus in less than 5 minutes**. - -## Getting Started - -Get started by **creating a new site**. - -Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**. - -### What you'll need - -- [Node.js](https://nodejs.org/en/download/) version 16.14 or above: - - When installing Node.js, you are recommended to check all checkboxes related to dependencies. - -## Generate a new site - -Generate a new Docusaurus site using the **classic template**. - -The classic template will automatically be added to your project after you run the command: - -```bash -npm init docusaurus@latest my-website classic -``` - -You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor. - -The command also installs all necessary dependencies you need to run Docusaurus. - -## Start your site - -Run the development server: - -```bash -cd my-website -npm run start -``` - -The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there. - -The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/. - -Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes. +Welcome to the Trifid project documentation! Trifid is a free and open-source reimplementation of the [Defined Networking](https://defined.net) protocol for managing [Nebula](https://github.com/slackhq/nebula) networks. \ No newline at end of file diff --git a/docs/docs/tfcli/_category_.json b/docs/docs/tfcli/_category_.json new file mode 100644 index 0000000..824d871 --- /dev/null +++ b/docs/docs/tfcli/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "tfcli", + "position": 5, + "link": { + "type": "generated-index", + "description": "Documentation for tfcli, the CLI for the management API." + } +} diff --git a/docs/docs/tfcli/intro.md b/docs/docs/tfcli/intro.md new file mode 100644 index 0000000..4fd6418 --- /dev/null +++ b/docs/docs/tfcli/intro.md @@ -0,0 +1,5 @@ +--- +sidebar_position: 1 +--- + +# Introduction \ No newline at end of file diff --git a/docs/docs/tfclient/_category_.json b/docs/docs/tfclient/_category_.json new file mode 100644 index 0000000..e942e56 --- /dev/null +++ b/docs/docs/tfclient/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "tfclient", + "position": 4, + "link": { + "type": "generated-index", + "description": "Documentation for tfclient, trifid's VPN client reimplementation." + } +} diff --git a/docs/docs/tfclient/intro.md b/docs/docs/tfclient/intro.md new file mode 100644 index 0000000..4fd6418 --- /dev/null +++ b/docs/docs/tfclient/intro.md @@ -0,0 +1,5 @@ +--- +sidebar_position: 1 +--- + +# Introduction \ No newline at end of file diff --git a/docs/docs/tfweb/_category_.json b/docs/docs/tfweb/_category_.json new file mode 100644 index 0000000..3d84144 --- /dev/null +++ b/docs/docs/tfweb/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "tfweb", + "position": 3, + "link": { + "type": "generated-index", + "description": "Documentation for tfweb, trifid's web UI." + } +} diff --git a/docs/docs/tfweb/intro.md b/docs/docs/tfweb/intro.md new file mode 100644 index 0000000..4fd6418 --- /dev/null +++ b/docs/docs/tfweb/intro.md @@ -0,0 +1,5 @@ +--- +sidebar_position: 1 +--- + +# Introduction \ No newline at end of file diff --git a/docs/docs/trifid-api/_category_.json b/docs/docs/trifid-api/_category_.json new file mode 100644 index 0000000..f712cb9 --- /dev/null +++ b/docs/docs/trifid-api/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "trifid-api", + "position": 2, + "link": { + "type": "generated-index", + "description": "Documentation for trifid-api, the API server reimplementation." + } +} diff --git a/docs/docs/trifid-api/config_reference/_category_.json b/docs/docs/trifid-api/config_reference/_category_.json new file mode 100644 index 0000000..31958ef --- /dev/null +++ b/docs/docs/trifid-api/config_reference/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Configuration Reference", + "position": 2, + "link": { + "type": "generated-index", + "description": "Configuration options for trifid-api." + } +} diff --git a/docs/docs/trifid-api/config_reference/cryptography.md b/docs/docs/trifid-api/config_reference/cryptography.md new file mode 100644 index 0000000..7dee45d --- /dev/null +++ b/docs/docs/trifid-api/config_reference/cryptography.md @@ -0,0 +1,33 @@ +# cryptography + +Essential, extremely important cryptography settings. Relate directly to key handling and certificate generation. + +```toml title="/etc/trifid/config.toml" +[cryptography] +data_encryption_key = "010aecf4b545bb9bc918e154181eb6fd59f08430a78a23ec7eac69e6d06c6fed" +local_keystore_directory = "/var/lib/trifid" +certs_expiry_time = 32140800 # 1 year +``` + +### cryptography.data_encryption_key (required) + +:::caution +**You must change this value!** It controls how CA keys are encrypted. Generate a new value for this with `openssl rand -hex 32`, and never share it with anyone. +::: + +:::danger +**DO NOT CHANGE THIS VALUE ON AN EXISTING INSTANCE!** Doing so will render all existing CAs and networks permanently unusable, and will require manual database manipulation and re-enrollment of all devices on your instance to fix. +::: + +The 32-byte hex-encoded AES-256 key to encrypt CA keys with before storing them to the database. + +### cryptography.local_keystore_directory (required) + +The path to the legacy keystore. This is currently unused and will be removed entirely in a future release. +The value of this does not matter. + +### cryptography.certs_expiry_time + +Default: 32140800 (1 year) + +The amount of time to make certs valid for, in seconds. \ No newline at end of file diff --git a/docs/docs/trifid-api/config_reference/database.md b/docs/docs/trifid-api/config_reference/database.md new file mode 100644 index 0000000..11a0b4c --- /dev/null +++ b/docs/docs/trifid-api/config_reference/database.md @@ -0,0 +1,61 @@ +# database + +Defines the connection details and options for managing the database connection pool. + +```toml title="/etc/trifid/config.toml" +[database] +url = "postgres://username:password@host/database" +max_connections = 100 +min_connections = 5 +connect_timeout = 8 +acquire_timeout = 8 +idle_timeout = 8 +max_lifetime = 8 +sqlx_logging = true +``` + +### database.url (required) + +The postgres connection URL to access the database. Takes the form `postgres://username:password@host/database`. + +### database.max_connections + +Default: 100 + +The maximum number of connections that will be opened to the database at any one time. + +### database.min_connections + +Default: 5 + +The minimum number of connections that will be maintained to the database at any one time. + +### database.connect_timeout + +Default: 8 + +The timeout, in seconds, to use when creating new connections to the database. + +### database.acquire_timeout + +Defualt: 8 + +The timeout, in seconds, to use when acquiring a connection from the connection pool. + +### database.idle_timeout + +Default: 8 + +The amount of time, in seconds, that inactive connections will be kept in the pool before they are dropped. + +### database.max_lifetime + +Default: 8 + +The maximum amount of time, in seconds, that connections will be maintained for. + +### database.sqlx_logging + +Default: true + +If true, verbose sqlx query logs will be enabled. If false, they will be hidden. \ No newline at end of file diff --git a/docs/docs/trifid-api/config_reference/server.md b/docs/docs/trifid-api/config_reference/server.md new file mode 100644 index 0000000..ce9ddcc --- /dev/null +++ b/docs/docs/trifid-api/config_reference/server.md @@ -0,0 +1,19 @@ +# server + +Settings related to the HTTP server itself. + +```toml title="/etc/trifid/config.toml" +[server] +bind = "0.0.0.0:8080" +workers = 32 +``` + +### server.bind (required) + +A SocketAddr that the server will listen to connections on. Takes the form `IP:PORT` + +### server.workers + +Default: 32 + +The number of thread workers that will be created to process incoming requests. \ No newline at end of file diff --git a/docs/docs/trifid-api/config_reference/tokens.md b/docs/docs/trifid-api/config_reference/tokens.md new file mode 100644 index 0000000..0ba12a8 --- /dev/null +++ b/docs/docs/trifid-api/config_reference/tokens.md @@ -0,0 +1,42 @@ +# tokens + +Settings related to the various token types issued by the server. + +```toml title="/etc/trifid/config.toml" +[tokens] +magic_link_expiry_time_seconds = 3600 # 1 hour +session_token_expiry_time_seconds = 15780000 # 6 months +totp_setup_timeout_time_seconds = 600 # 10 minutes +mfa_tokens_expiry_time_seconds = 600 # 10 minutes +enrollment_tokens_expiry_time = 600 # 10 minutes +``` + +### tokens.magic_link_expiry_time_seconds + +Default: 3600 (1 hour) + +How long magic links should be valid for, in seconds. + +### tokens.session_token_expiry_time_seconds + +Default: 15780000 (6 months) + +How long session tokens should remain valid for, in seconds. This controls how often you need to re-authenticate with magic links. + +### tokens.totp_setup_timeout_time_seconds + +Default: 600 (10 minutes) + +How long TOTP setup tokens should be valid for, in seconds, before a new one must be generated. + +### tokens.mfa_tokens_expiry_time_seconds + +Default: 600 (10 minutes) + +How long MFA tokens should remain valid for, in seconds. This controls how often you need to re-authenticate with 2fa. + +### tokens.enrollment_tokens_expiry_time + +Default: 600 (10 minutes) + +How long enrollment tokens should be valid for, in seconds, before a new one must be generated. \ No newline at end of file diff --git a/docs/docs/trifid-api/intro.md b/docs/docs/trifid-api/intro.md new file mode 100644 index 0000000..48a10e7 --- /dev/null +++ b/docs/docs/trifid-api/intro.md @@ -0,0 +1,12 @@ +--- +sidebar_position: 1 +--- + +# Introduction + +Welcome to the trifid-api documentation! +trifid-api is a complete reimplementation of the [Defined Networking](https://defined.net) API server, designed to allow you to self-host your own networks. + +:::caution +Although trifid-api is battle-tested and has been used in production networks for months with no major issues, it should still be considered experimental software. Please, [report any bugs you find](https://git.e3t.cc/core/trifid/issues) to assist with further development of trifid-api. +::: \ No newline at end of file diff --git a/docs/docs/tutorial-basics/_category_.json b/docs/docs/tutorial-basics/_category_.json index 2e6db55..86ff3a6 100644 --- a/docs/docs/tutorial-basics/_category_.json +++ b/docs/docs/tutorial-basics/_category_.json @@ -1,6 +1,6 @@ { "label": "Tutorial - Basics", - "position": 2, + "position": 6, "link": { "type": "generated-index", "description": "5 minutes to learn the most important Docusaurus concepts." diff --git a/docs/docs/tutorial-extras/_category_.json b/docs/docs/tutorial-extras/_category_.json index a8ffcc1..f0379bd 100644 --- a/docs/docs/tutorial-extras/_category_.json +++ b/docs/docs/tutorial-extras/_category_.json @@ -1,6 +1,6 @@ { "label": "Tutorial - Extras", - "position": 3, + "position": 7, "link": { "type": "generated-index" } diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index a166b1d..9cbb918 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -66,7 +66,7 @@ const config = { type: 'docSidebar', sidebarId: 'tutorialSidebar', position: 'left', - label: 'Tutorial', + label: 'Docs', }, {to: '/blog', label: 'Blog', position: 'left'}, ], @@ -78,9 +78,25 @@ const config = { title: 'Docs', items: [ { - label: 'Tutorial', + label: 'Overview', to: '/docs/intro', }, + { + label: 'trifid-api', + to: '/docs/trifid-api/intro', + }, + { + label: 'tfweb', + to: '/docs/tfweb/intro', + }, + { + label: 'tfclient', + to: '/docs/tfclient/intro', + }, + { + label: 'tfcli', + to: '/docs/tfcli/intro', + }, ], }, { @@ -90,6 +106,10 @@ const config = { label: 'Blog', to: '/blog', }, + { + label: 'Git', + href: 'https://git.e3t.cc/core/trifid', + }, ], }, ], @@ -98,6 +118,7 @@ const config = { prism: { theme: lightCodeTheme, darkTheme: darkCodeTheme, + additionalLanguages: ["toml"] }, }), }; diff --git a/docs/src/components/HomepageFeatures/index.js b/docs/src/components/HomepageFeatures/index.js index 78f410b..b131103 100644 --- a/docs/src/components/HomepageFeatures/index.js +++ b/docs/src/components/HomepageFeatures/index.js @@ -5,31 +5,28 @@ import styles from './styles.module.css'; const FeatureList = [ { title: 'Easy to Use', - Svg: require('@site/static/img/undraw_docusaurus_mountain.svg').default, + Svg: require('@site/static/img/undraw_setup_wizard_re_nday.svg').default, description: ( <> - Docusaurus was designed from the ground up to be easily installed and - used to get your website up and running quickly. + Trifid is easy to install, simple to configure and is designed to get out of your way so you can focus on what matters most. ), }, { - title: 'Focus on What Matters', - Svg: require('@site/static/img/undraw_docusaurus_tree.svg').default, + title: 'Incredibly Fast', + Svg: require('@site/static/img/undraw_fast_loading_re_8oi3.svg').default, description: ( <> - Docusaurus lets you focus on your docs, and we'll do the chores. Go - ahead and move your docs into the docs directory. + Trifid was built from the ground-up with speed in mind. Written entirely in Go and Rust, Trifid is fast and safe. ), }, { - title: 'Powered by React', - Svg: require('@site/static/img/undraw_docusaurus_react.svg').default, + title: 'Simple Security', + Svg: require('@site/static/img/undraw_secure_server_re_8wsq.svg').default, description: ( <> - Extend or customize your website layout by reusing React. Docusaurus can - be extended while reusing the same header and footer. + Built around the Defined Networking protocol, the server never handles any sensitive client keys. ), }, diff --git a/docs/static/img/undraw_fast_loading_re_8oi3.svg b/docs/static/img/undraw_fast_loading_re_8oi3.svg new file mode 100644 index 0000000..21eb197 --- /dev/null +++ b/docs/static/img/undraw_fast_loading_re_8oi3.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/static/img/undraw_secure_server_re_8wsq.svg b/docs/static/img/undraw_secure_server_re_8wsq.svg new file mode 100644 index 0000000..c0d5590 --- /dev/null +++ b/docs/static/img/undraw_secure_server_re_8wsq.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/static/img/undraw_setup_wizard_re_nday.svg b/docs/static/img/undraw_setup_wizard_re_nday.svg new file mode 100644 index 0000000..c20bc6a --- /dev/null +++ b/docs/static/img/undraw_setup_wizard_re_nday.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/static/img/undraw_speed_test_re_pe1f.svg b/docs/static/img/undraw_speed_test_re_pe1f.svg new file mode 100644 index 0000000..dc927a9 --- /dev/null +++ b/docs/static/img/undraw_speed_test_re_pe1f.svg @@ -0,0 +1 @@ + \ No newline at end of file