From 3b97b3cc2f249b4f71b2fa4580fb4df25f47ed9e Mon Sep 17 00:00:00 2001 From: Miraty Date: Thu, 26 Jan 2023 16:22:03 +0100 Subject: [PATCH] Describe config.ini in DOCS/configuration.md --- DOCS/configuration.md | 220 ++++++++++++++++++++++++++++++++++++++++++ config.ini | 16 +-- fn/auth.php | 2 +- fn/common.php | 4 - 4 files changed, 226 insertions(+), 16 deletions(-) create mode 100644 DOCS/configuration.md diff --git a/DOCS/configuration.md b/DOCS/configuration.md new file mode 100644 index 0000000..ecf1738 --- /dev/null +++ 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`. + +### `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//` + +### `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:///example/` maps to `/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./` maps to `/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 /*.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//` + +### `tor_keys_path` + +Tor sets up keys inside the directory `tor_keys_path///` + +### `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. diff --git a/config.ini b/config.ini index 1aa21c4..552ad8c 100644 --- 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" diff --git a/fn/auth.php b/fn/auth.php index 10782a9..c95588c 100644 --- 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' diff --git a/fn/common.php b/fn/common.php index be2cee9..f154b9e 100644 --- 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 '' . $title . ''; -} - /* This token authenticates the user to the server through a public communication (the DNS). It is therefore also designed to keep private: