servnest/DOCS/configuration.md

# Configuration reference

This document describes the ServNest configuration directives that are part of `config.ini` (distributed as `config.template.ini`). It's an INI file, parsed by [PHP's `parse_ini_file` function](https://www.php.net/manual/function.parse-ini-file.php). Every directive is expected to be present.

## `[common]`

### `public_domains[]`

Allowed server names. Used to make the authentication tokens specific to the service.

You can specify multiple domains:
```
public_domains[] = "servnest.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://servnest.example/servnest/`, you need to set `prefix = "/servnest"`.

### `service_name`

String defining the displayed identity of the service.

### `service_emoji`

Pretty string sometimes prefixed to the service name. Can be empty.

### `about_url`

Address of the service presentation page.

### `services[]`

Keys `auth`, `reg`, `ns` and `ht` are required.

Values can be:
* `enabled`: The service is provided as usual.
* `no-registration` (`auth` only): Same as `enabled`, but no new account can be created.
* `error`: For maintenance/debugging purposes, the service is temporarily unavailable. When used on the `auth` service, users can't submit any form, but this doesn't prevent already logged in SFTP users to act on the filesystem.
* `disabled` (`reg`, `ns` and `ht` only): The service is ignored everywhere, this installation never provides it.

## `[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]`

### `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]`

### `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 when creating a zone.

All elements are used as NS records for newly created zones and listed in the interface so users can know what NS records must be delegated from the registry.

The script `jobs/ns-update.php` may be run after updating this setting to update NS records for already created zones.

### `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@servnest.example` becomes `contact\.admin.servnest.example.`

### `local_only_check`

Check for records on the local registry name server when adding a zone.

Development feature, should not be enabled for a public server.

## `[ht]`

### `ht_path`

Apache can be [chroot](https://httpd.apache.org/docs/current/mod/mod_unixd.html#chrootdir)ed to this directory.

`<ht_path>/fs/<internal-user-id>/` is the users files base directory.

`<ht_path>/uri/<address>/` is automatically reachable by Apache (using [mod_vhost_alias](https://httpd.apache.org/docs/current/mod/mod_vhost_alias.html)) and contains relative symlinks to users managed directories.

### `user_quota_testing`, `user_quota_approved`

Maximum bytes a user can use on its SFTP space, depending on its account type.

### `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/`

### `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.

### `onion_internal_host`

HTTP Onion services listen on port 80 and forward requests to this host.

### `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.)

### `cname`

For a site with dedicated domain, the domain that users must point their domain to.

This domain should have the following records:

AAAA
: `ipv6_address`

A
: `ipv4_address`

CAA
: `caa_account_uris[testing]`

CAA
: `caa_account_uris[approved]`

### `ipv6_address`, `ipv4_address`

For a site with dedicated domain, when manually copying records, public IPv6 and IPv4 addresses that users must set in their AAAA and A records.

Should be the same as the AAAA and A records for `cname`.

### `caa_account_uris[]`

For a site with dedicated domain, when manually copying records, the URIs of the accounts (both stable and staging) that request Let's Encrypt certificates. Keys `testing` and `approved` must be set to outputs of respectively `certbot show_account --test-cert` and `certbot show_account`

Should be the same as the CAA records for `cname`.

### `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`.

## `[check]`

This configuration section is used only when running `check.php`.

### `https_port`

Port where the public nginx reverse proxy can be reached. Usually `443` for production.

### `sftp_path`

Filesystem path to the sftp binary.

### `sshpass_path`

Filesystem path to the sshpass binary.

### `tor_proxy`

Curl's [CURLOPT_PROXY](https://curl.se/libcurl/c/CURLOPT_PROXY.html) argument, used to test onion services.