Cleanup references to sample config in the docs and redirect users to configuration manual (#13077)

This commit is contained in:
Shay 2022-06-30 09:21:39 -07:00 committed by GitHub
parent 0ceb3af10b
commit 8330fc9953
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
12 changed files with 72 additions and 88 deletions

3
changelog.d/13077.doc Normal file
View file

@ -0,0 +1,3 @@
Clean up references to sample configuration and redirect users to the configuration manual instead.

View file

@ -124,9 +124,8 @@ Body parameters:
- `address` - string. Value of third-party ID. - `address` - string. Value of third-party ID.
belonging to a user. belonging to a user.
- `external_ids` - array, optional. Allow setting the identifier of the external identity - `external_ids` - array, optional. Allow setting the identifier of the external identity
provider for SSO (Single sign-on). Details in provider for SSO (Single sign-on). Details in the configuration manual under the
[Sample Configuration File](../usage/configuration/homeserver_sample_config.html) sections [sso](../usage/configuration/config_documentation.md#sso) and [oidc_providers](../usage/configuration/config_documentation.md#oidc_providers).
section `sso` and `oidc_providers`.
- `auth_provider` - string. ID of the external identity provider. Value of `idp_id` - `auth_provider` - string. ID of the external identity provider. Value of `idp_id`
in the homeserver configuration. Note that no error is raised if the provided in the homeserver configuration. Note that no error is raised if the provided
value is not in the homeserver configuration. value is not in the homeserver configuration.

View file

@ -70,82 +70,61 @@ on save as they take a while and can be very resource intensive.
- Avoid wildcard imports (`from synapse.types import *`) and - Avoid wildcard imports (`from synapse.types import *`) and
relative imports (`from .types import UserID`). relative imports (`from .types import UserID`).
## Configuration file format ## Configuration code and documentation format
The [sample configuration file](./sample_config.yaml) acts as a When adding a configuration option to the code, if several settings are grouped into a single dict, ensure that your code
correctly handles the top-level option being set to `None` (as it will be if no sub-options are enabled).
The [configuration manual](usage/configuration/config_documentation.md) acts as a
reference to Synapse's configuration options for server administrators. reference to Synapse's configuration options for server administrators.
Remember that many readers will be unfamiliar with YAML and server Remember that many readers will be unfamiliar with YAML and server
administration in general, so that it is important that the file be as administration in general, so it is important that when you add
easy to understand as possible, which includes following a consistent a configuration option the documentation be as easy to understand as possible, which
format. includes following a consistent format.
Some guidelines follow: Some guidelines follow:
- Sections should be separated with a heading consisting of a single - Each option should be listed in the config manual with the following format:
line prefixed and suffixed with `##`. There should be **two** blank
lines before the section header, and **one** after. - The name of the option, prefixed by `###`.
- Each option should be listed in the file with the following format:
- A comment describing the setting. Each line of this comment
should be prefixed with a hash (`#`) and a space.
The comment should describe the default behaviour (ie, what - A comment which describes the default behaviour (i.e. what
happens if the setting is omitted), as well as what the effect happens if the setting is omitted), as well as what the effect
will be if the setting is changed. will be if the setting is changed.
- An example setting, using backticks to define the code block
Often, the comment end with something like "uncomment the
following to <do action>".
- A line consisting of only `#`.
- A commented-out example setting, prefixed with only `#`.
For boolean (on/off) options, convention is that this example For boolean (on/off) options, convention is that this example
should be the *opposite* to the default (so the comment will end should be the *opposite* to the default. For other options, the example should give
with "Uncomment the following to enable [or disable] some non-default value which is likely to be useful to the reader.
<feature>." For other options, the example should give some
non-default value which is likely to be useful to the reader.
- There should be a blank line between each option. - There should be a horizontal rule between each option, which can be achieved by adding `---` before and
- Where several settings are grouped into a single dict, *avoid* the after the option.
convention where the whole block is commented out, resulting in - `true` and `false` are spelt thus (as opposed to `True`, etc.)
comment lines starting `# #`, as this is hard to read and confusing
to edit. Instead, leave the top-level config option uncommented, and
follow the conventions above for sub-options. Ensure that your code
correctly handles the top-level option being set to `None` (as it
will be if no sub-options are enabled).
- Lines should be wrapped at 80 characters.
- Use two-space indents.
- `true` and `false` are spelt thus (as opposed to `True`, etc.)
- Use single quotes (`'`) rather than double-quotes (`"`) or backticks
(`` ` ``) to refer to configuration options.
Example: Example:
---
### `modules`
Use the `module` sub-option to add a module under `modules` to extend functionality.
The `module` setting then has a sub-option, `config`, which can be used to define some configuration
for the `module`.
Defaults to none.
Example configuration:
```yaml ```yaml
## Frobnication ## modules:
- module: my_super_module.MySuperClass
# The frobnicator will ensure that all requests are fully frobnicated. config:
# To enable it, uncomment the following. do_thing: true
# - module: my_other_super_module.SomeClass
#frobnicator_enabled: true config: {}
# By default, the frobnicator will frobnicate with the default frobber.
# The following will make it use an alternative frobber.
#
#frobincator_frobber: special_frobber
# Settings for the frobber
#
frobber:
# frobbing speed. Defaults to 1.
#
#speed: 10
# frobbing distance. Defaults to 1000.
#
#distance: 100
``` ```
---
Note that the sample configuration is generated from the synapse code Note that the sample configuration is generated from the synapse code
and is maintained by a script, `scripts-dev/generate_sample_config.sh`. and is maintained by a script, `scripts-dev/generate_sample_config.sh`.
Making sure that the output from this script matches the desired format Making sure that the output from this script matches the desired format
is left as an exercise for the reader! is left as an exercise for the reader!

View file

@ -49,9 +49,8 @@ as follows:
* For other installation mechanisms, see the documentation provided by the * For other installation mechanisms, see the documentation provided by the
maintainer. maintainer.
To enable the JSON web token integration, you should then add a `jwt_config` section To enable the JSON web token integration, you should then add a `jwt_config` option
to your configuration file (or uncomment the `enabled: true` line in the to your configuration file. See the [configuration manual](usage/configuration/config_documentation.md#jwt_config) for some
existing section). See [sample_config.yaml](./sample_config.yaml) for some
sample settings. sample settings.
## How to test JWT as a developer ## How to test JWT as a developer

View file

@ -13,8 +13,10 @@ environments where untrusted users have shell access.
## Configuring the manhole ## Configuring the manhole
To enable it, first uncomment the `manhole` listener configuration in To enable it, first add the `manhole` listener configuration in your
`homeserver.yaml`. The configuration is slightly different if you're using docker. `homeserver.yaml`. You can find information on how to do that
in the [configuration manual](usage/configuration/config_documentation.md#manhole_settings).
The configuration is slightly different if you're using docker.
#### Docker config #### Docker config

View file

@ -49,9 +49,9 @@ clients.
## Server configuration ## Server configuration
Support for this feature can be enabled and configured in the Support for this feature can be enabled and configured by adding a the
`retention` section of the Synapse configuration file (see the `retention` in the Synapse configuration file (see
[sample file](https://github.com/matrix-org/synapse/blob/v1.36.0/docs/sample_config.yaml#L451-L518)). [configuration manual](usage/configuration/config_documentation.md#retention)).
To enable support for message retention policies, set the setting To enable support for message retention policies, set the setting
`enabled` in this section to `true`. `enabled` in this section to `true`.
@ -65,8 +65,8 @@ message retention policy configured in its state. This allows server
admins to ensure that messages are never kept indefinitely in a server's admins to ensure that messages are never kept indefinitely in a server's
database. database.
A default policy can be defined as such, in the `retention` section of A default policy can be defined as such, by adding the `retention` option in
the configuration file: the configuration file and adding these sub-options:
```yaml ```yaml
default_policy: default_policy:
@ -86,8 +86,8 @@ Purge jobs are the jobs that Synapse runs in the background to purge
expired events from the database. They are only run if support for expired events from the database. They are only run if support for
message retention policies is enabled in the server's configuration. If message retention policies is enabled in the server's configuration. If
no configuration for purge jobs is configured by the server admin, no configuration for purge jobs is configured by the server admin,
Synapse will use a default configuration, which is described in the Synapse will use a default configuration, which is described here in the
[sample configuration file](https://github.com/matrix-org/synapse/blob/v1.36.0/docs/sample_config.yaml#L451-L518). [configuration manual](usage/configuration/config_documentation.md#retention).
Some server admins might want a finer control on when events are removed Some server admins might want a finer control on when events are removed
depending on an event's room's policy. This can be done by setting the depending on an event's room's policy. This can be done by setting the
@ -137,8 +137,8 @@ the server's database.
### Lifetime limits ### Lifetime limits
Server admins can set limits on the values of `max_lifetime` to use when Server admins can set limits on the values of `max_lifetime` to use when
purging old events in a room. These limits can be defined as such in the purging old events in a room. These limits can be defined under the
`retention` section of the configuration file: `retention` option in the configuration file:
```yaml ```yaml
allowed_lifetime_min: 1d allowed_lifetime_min: 1d

View file

@ -45,8 +45,8 @@ as follows:
maintainer. maintainer.
To enable the OpenID integration, you should then add a section to the `oidc_providers` To enable the OpenID integration, you should then add a section to the `oidc_providers`
setting in your configuration file (or uncomment one of the existing examples). setting in your configuration file.
See [sample_config.yaml](./sample_config.yaml) for some sample settings, as well as See the [configuration manual](usage/configuration/config_documentation.md#oidc_providers) for some sample settings, as well as
the text below for example configurations for specific providers. the text below for example configurations for specific providers.
## Sample configs ## Sample configs

View file

@ -66,8 +66,8 @@ in Synapse can be deactivated.
**NOTE**: This has an impact on security and is for testing purposes only! **NOTE**: This has an impact on security and is for testing purposes only!
To deactivate the certificate validation, the following setting must be made in To deactivate the certificate validation, the following setting must be added to
[homserver.yaml](../usage/configuration/homeserver_sample_config.md). your [homserver.yaml](../usage/configuration/homeserver_sample_config.md).
```yaml ```yaml
use_insecure_ssl_client_just_for_testing_do_not_use: true use_insecure_ssl_client_just_for_testing_do_not_use: true

View file

@ -407,11 +407,11 @@ The recommended way to do so is to set up a reverse proxy on port
Alternatively, you can configure Synapse to expose an HTTPS port. To do Alternatively, you can configure Synapse to expose an HTTPS port. To do
so, you will need to edit `homeserver.yaml`, as follows: so, you will need to edit `homeserver.yaml`, as follows:
- First, under the `listeners` section, uncomment the configuration for the - First, under the `listeners` option, add the configuration for the
TLS-enabled listener. (Remove the hash sign (`#`) at the start of TLS-enabled listener like so:
each line). The relevant lines are like this:
```yaml ```yaml
listeners:
- port: 8448 - port: 8448
type: http type: http
tls: true tls: true
@ -419,9 +419,11 @@ so, you will need to edit `homeserver.yaml`, as follows:
- names: [client, federation] - names: [client, federation]
``` ```
- You will also need to uncomment the `tls_certificate_path` and - You will also need to add the options `tls_certificate_path` and
`tls_private_key_path` lines under the `TLS` section. You will need to manage `tls_private_key_path`. to your configuration file. You will need to manage provisioning of
provisioning of these certificates yourself. these certificates yourself.
- You can find more information about these options as well as how to configure synapse in the
[configuration manual](../usage/configuration/config_documentation.md).
If you are using your own certificate, be sure to use a `.pem` file that If you are using your own certificate, be sure to use a `.pem` file that
includes the full certificate chain including any intermediate certificates includes the full certificate chain including any intermediate certificates

View file

@ -2999,7 +2999,7 @@ This setting has the following sub-options:
* `localdb_enabled`: Set to false to disable authentication against the local password * `localdb_enabled`: Set to false to disable authentication against the local password
database. This is ignored if `enabled` is false, and is only useful database. This is ignored if `enabled` is false, and is only useful
if you have other `password_providers`. Defaults to true. if you have other `password_providers`. Defaults to true.
* `pepper`: Set the value here to a secret random string for extra security. # Uncomment and change to a secret random string for extra security. * `pepper`: Set the value here to a secret random string for extra security.
DO NOT CHANGE THIS AFTER INITIAL SETUP! DO NOT CHANGE THIS AFTER INITIAL SETUP!
* `policy`: Define and enforce a password policy, such as minimum lengths for passwords, etc. * `policy`: Define and enforce a password policy, such as minimum lengths for passwords, etc.
Each parameter is optional. This is an implementation of MSC2000. Parameters are as follows: Each parameter is optional. This is an implementation of MSC2000. Parameters are as follows:

View file

@ -4,5 +4,5 @@ Synapse supports authenticating users via the [Central Authentication
Service protocol](https://en.wikipedia.org/wiki/Central_Authentication_Service) Service protocol](https://en.wikipedia.org/wiki/Central_Authentication_Service)
(CAS) natively. (CAS) natively.
Please see the `cas_config` and `sso` sections of the [Synapse configuration Please see the [cas_config](../../../configuration/config_documentation.md#cas_config) and [sso](../../../configuration/config_documentation.md#sso)
file](../../../configuration/homeserver_sample_config.md) for more details. sections of the configuration manual for more details.

View file

@ -145,7 +145,7 @@ class EmailConfig(Config):
raise ConfigError( raise ConfigError(
'The config option "trust_identity_server_for_password_resets" ' 'The config option "trust_identity_server_for_password_resets" '
'has been replaced by "account_threepid_delegate". ' 'has been replaced by "account_threepid_delegate". '
"Please consult the sample config at docs/sample_config.yaml for " "Please consult the configuration manual at docs/usage/configuration/config_documentation.md for "
"details and update your config file." "details and update your config file."
) )