Describe config.ini in DOCS/configuration.md

2023-01-26 16:22:03 +01:00 · 2023-01-26 16:22:03 +01:00 · 3b97b3cc2f
parent 23b2afe03e
commit 3b97b3cc2f
4 changed files with 226 additions and 16 deletions
--- a/DOCS/configuration.md
+++ b/DOCS/configuration.md
@ -0,0 +1,220 @@
+# Configuration reference
+
+This document describes the `config.ini` directives. It's an INI file, parsed by [PHP's `parse_ini_file`](https://www.php.net/manual/function.parse-ini-file.php). Every setting is expected to be present.
+
+## `[common]`
+
+### `root-path`
+
+Filesystem path to the directory where the root of the program is installed.
+
+### `public_domains[]`
+
+Allowed server names. Used to make the authentication tokens specific to the service.
+
+You can specify multiple domains:
+```
+public_domains[] = "niver.example"
+public_domains[] = "4example4example4example4example4example4example4example.onion"
+```
+
+### `prefix`
+
+Path that is prepended to the HTTP root where the service can be reached. Used for redirections and emitting cookies.
+
+If the service answers at `https://niver.example/niver/`, you need to set `prefix = "/niver"`.
+
+### `service_name`
+
+String defining the displayed identity of the service.
+
+### `service_emoji`
+
+Pretty string sometimes prefixed to the service name. Can be empty.
+
+## `[dns]`
+
+This configuration section is used by both the registry (`reg`) and the public name server (`ns`).
+
+### `knotc_path`
+
+Filesystem path to the `knotc` binary.
+
+### `kdig_path`
+
+Filesystem path to the `kdig` binary. Used to authenticate resources possession using the DNS.
+
+## `[reg]`
+
+### `enabled`
+
+Defines whether the web interface for this service is accessible.
+
+### `suffixes[]`
+
+Lists the suffixes that the registry manages.
+
+The key is the suffix (ending with a dot) and the value is its registration availability, which can be one of the following:
+
+* `all`: every account can register
+* `approved`: only approved accounts can register
+* `none`: nobody can register
+
+This impacts only new registrations, existing domains can always be managed by users if their suffix appears in the list.
+
+### `suffixes_path`
+
+Filesystem path to the registries directory. The full path to the registry zonefile is `suffixes_path` + `/` + suffixes (as defined in suffixes[]) + `zone`.
+
+### `ttl`
+
+The TTL of every DNS record created by users (i.e. NS, DS and glue records).
+
+### `address`
+
+Host where the Knot DNS server answers the registry values. Should be a secure (local) address, as answers are not authenticated.
+
+(Used to check the transfer authentication records.)
+
+## `[ns]`
+
+### `enabled`
+
+Defines whether the web interface for this service is accessible.
+
+### `knot_zones_path`
+
+Filesystem path to the zones directory. The full path to created zonefiles will be `knot_zones_path/<zone-apex-domain>.zone`.
+
+### `servers[]`
+
+The first element is set as the primary server in the SOA.
+
+All elements are listed in the interface so users can know what NS records to set in their zone.
+
+### `kzonecheck_path`
+
+Filesystem path to the `kzonecheck` binary. Used to check sent plaintext zonefiles.
+
+### `public_soa_email`
+
+Administrator email address published in every SOA record. Ends with a `.`, `@` is replaced by a `.`, an hypothetical `.` in the first part of the address is escaped using a `\` before, thus `contact.admin@niver.example` becomes `contact\.admin.niver.example.`
+
+## `[ht]`
+
+### `enabled`
+
+Defines whether the web interface for this service is accessible. (Users can still use SFTP.)
+
+### `ht_path`
+
+Filesystem path to the users files base directory. Files of a user are located inside `ht_path/<their-internal-user-id>/`
+
+### `subpath_domain` and `subpath_path`
+
+For the feature of sites in subpathes of a single domain:
+
+`subpath_domain` is the said shared domain, displayed in the interface
+
+`subpath_path` is the filesystem path to the directory whose address is the HTTP root of `subpath_domain`
+
+`https://<subpath_domain>/example/` maps to `<subpath_path>/example/`
+
+### `subdomain_domain` and `subdomain_path`
+
+For the feature of sites in subdomains of a root domain:
+
+(The root domain must have a wildcard TLS certificate and wildcard AAAA and A records.)
+
+`subdomain_domain` is the root domain, displayed in the interface
+
+`subdomain_path` is the filesystem path to the directory whose direct subdirectories are mapped to direct subdomains of `subdomain_domain`
+
+`https://example.<subdomain_domain>/` maps to `<subdomain_path>/example/`
+
+### `nginx_config_path`
+
+Filesystem path to the directory that contains configuration files for dedicated sites.
+
+The `http` block of nginx must contain something like `include <nginx_config_path>/*.conf;`
+
+### `nginx_reload_cmd`
+
+Command to execute through sudo to reload the nginx daemon.
+
+### `tor_config_path`
+
+Filesystem path to the directory containing Tor configuration for onion accesses. The full Tor configuration file path is `tor_config_path/<internal-user-id>/<site-dir-name>`
+
+### `tor_keys_path`
+
+Tor sets up keys inside the directory `tor_keys_path/<internal-user-id>/<site-dir-name>/`
+
+### `tor_user`
+
+Linux user as who runs the Tor daemon. Some commands are executed as this user through sudo.
+
+### `tor_reload_cmd`
+
+Command to execute through sudo to reload the Tor daemon.
+
+### `sudo_path`
+
+Filesystem path to the sudo binary.
+
+### `certbot_path`
+
+Filesystem path to the certbot binary. It is used through sudo to get a Let's Encrypt certificate.
+
+### `chgrp_path`, `cat_path`, `rm_path`, `mkdir_path`
+
+Filesystem paths to the corresponding GNU coreutils binary (other implementations are not tested). (Their PHP counterpart can't be used as they need to act as another user through sudo.)
+
+### `sftpgo_group`
+
+Linux group as who runs SFTPGo. (Gets full permissions on users directories.)
+
+### `sftpgo_user`
+
+Linux user as who runs SFTPGo. (Used to delete files that users created.)
+
+
+### `ipv6_address`, `ipv4_address`
+
+Public IPv6 and IPv4 addresses that users must set in their AAAA and A records for a site with dedicated domain.
+
+### `sftp_pub`
+
+Filesystem path to where the public key of the SFTP service is available.
+
+### `sftp_fp`
+
+Filesystem path to where the public key fingerprint of the SFTP service is available.
+
+### `sftp_asciiart`
+
+Filesystem path to where the ASCII art of the public key of the SFTP service is available.
+
+### `sftp_domain`
+
+Domain name that users need to direct their SFTP clients to. May be the same key as in `public_domains[]`.
+
+### `public_sftp_port`
+
+Network port that users need to direct their SFTP clients to. The common default port is `22`.
+
+### `https_port`
+
+Network port where nginx listens. The common default port is `443`.
+
+### `ipv6_listen_address`, `ipv4_listen_address`
+
+IP address where nginx listens. May be the same as `ipv6_address` and `ipv4_address`, or `[::]` and `0.0.0.0` to listen on every address available.
+
+### `internal_onion_http_port`
+
+The port of `[::1]` set in Tor and nginx configuration files when creating an Onion service.
+
+### `user_quota_testing`, `user_quota_approved`
+
+Maximum bytes a user can use on its SFTP space, depending on its account type.
--- a/config.ini
+++ b/config.ini
@ -1,9 +1,9 @@
+; Directives here are described in DOCS/configuration.md
+
 [common]
 root_path = "/srv/niver/core"
-docs_prefix = "/docs/"
-; Prefix in URL, if any
-prefix = ""
 public_domains[] = "niver.test"
+prefix = ""
 service_name = "Niver"
 service_emoji = "🪐"

@ -13,12 +13,11 @@ kdig_path = "/usr/bin/kdig"

 [reg]
 enabled = true
-suffixes_path = "/srv/niver/reg"
 suffixes[niver.test.] = "approved"
 suffixes[test.niver.test.] = "all"
 suffixes[old.niver.test.] = "none"
+suffixes_path = "/srv/niver/reg"
 ttl = 86400
-; A local address to query the registry nameserver
 address = "[::1]:42053"

 [ns]
@ -27,13 +26,11 @@ knot_zones_path = "/srv/niver/ns"
 servers[] = "ns1.niver.test."
 servers[] = "ns2.niver.test."
 kzonecheck_path = "/usr/bin/kzonecheck"
-; @ must be replaced by a dot
 public_soa_email = "hostmaster.niver.invalid."

 [ht]
 enabled = true

-; Path were user's sites will be stored
 ht_path = "/srv/niver/ht"

 subpath_domain = "ht.niver.test"
@ -42,13 +39,10 @@ subpath_path = "/srv/niver/subpath"
 subdomain_domain = "ht.niver.test"
 subdomain_path = "/srv/niver/subdomain"

-; Nginx configuration directory
 nginx_config_path = "/srv/niver/nginx"
 nginx_reload_cmd = "/usr/bin/systemctl reload nginx"

-; Tor configuration directory
 tor_config_path = "/srv/niver/tor-config"
-; Tor keys directory
 tor_keys_path = "/srv/niver/tor-keys"
 tor_user = "tor"
 tor_reload_cmd = "/usr/bin/systemctl reload tor"
@ -60,8 +54,8 @@ cat_path = "/usr/bin/cat"
 rm_path = "/usr/bin/rm"
 mkdir_path = "/usr/bin/mkdir"

-sftpgo_user = "sftpgo"
 sftpgo_group = "sftpgo"
+sftpgo_user = "sftpgo"

 ; Will be shown to users
 ipv6_address = "::1"
--- a/fn/auth.php
+++ b/fn/auth.php
@ -78,7 +78,7 @@ function setupDisplayUsername($display_username) {
 		base64_encode($key),
 		[
 			'expires' => time() + 432000,
-			'path' => '/' . CONF['common']['prefix'],
+			'path' => CONF['common']['prefix'] . '/',
 			'secure' => true,
 			'httponly' => true,
 			'samesite' => 'Strict'
--- a/fn/common.php
+++ b/fn/common.php
@ -105,10 +105,6 @@ function equalArrays($a, $b) {
 	return array_diff($a, $b) === [] AND array_diff($b, $a) === [];
 }

-function linkToDocs($ref, $title) {
-	return '<a rel="help" href="' . CONF['common']['docs_prefix'] . $ref . '.html">' . $title . '</a>';
-}
-
 /*
 	This token authenticates the user to the server through a public communication (the DNS).
 	It is therefore also designed to keep private: