@@ -0,0 +1,3 @@ | |||||
Clean up references to sample configuration and redirect users to the configuration manual instead. | |||||
@@ -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 | |||||
[Sample Configuration File](../usage/configuration/homeserver_sample_config.html) | |||||
section `sso` and `oidc_providers`. | |||||
provider for SSO (Single sign-on). Details in the configuration manual under the | |||||
sections [sso](../usage/configuration/config_documentation.md#sso) and [oidc_providers](../usage/configuration/config_documentation.md#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. | ||||
@@ -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 | |||||
easy to understand as possible, which includes following a consistent | |||||
format. | |||||
administration in general, so it is important that when you add | |||||
a configuration option the documentation be as easy to understand as possible, which | |||||
includes following a consistent format. | |||||
Some guidelines follow: | Some guidelines follow: | ||||
- Sections should be separated with a heading consisting of a single | |||||
line prefixed and suffixed with `##`. There should be **two** blank | |||||
lines before the section header, and **one** after. | |||||
- 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. | |||||
- Each option should be listed in the config manual with the following format: | |||||
- The name of the option, prefixed by `###`. | |||||
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. | ||||
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 `#`. | |||||
- An example setting, using backticks to define the code block | |||||
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 | |||||
with "Uncomment the following to enable [or disable] | |||||
<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. | |||||
- Where several settings are grouped into a single dict, *avoid* the | |||||
convention where the whole block is commented out, resulting in | |||||
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. | |||||
should be the *opposite* to the default. For other options, the example should give | |||||
some non-default value which is likely to be useful to the reader. | |||||
- There should be a horizontal rule between each option, which can be achieved by adding `---` before and | |||||
after the option. | |||||
- `true` and `false` are spelt thus (as opposed to `True`, etc.) | |||||
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 ## | |||||
# The frobnicator will ensure that all requests are fully frobnicated. | |||||
# To enable it, uncomment the following. | |||||
# | |||||
#frobnicator_enabled: true | |||||
# 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 | |||||
modules: | |||||
- module: my_super_module.MySuperClass | |||||
config: | |||||
do_thing: true | |||||
- module: my_other_super_module.SomeClass | |||||
config: {} | |||||
``` | ``` | ||||
--- | |||||
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! | ||||
@@ -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 your configuration file (or uncomment the `enabled: true` line in the | |||||
existing section). See [sample_config.yaml](./sample_config.yaml) for some | |||||
To enable the JSON web token integration, you should then add a `jwt_config` option | |||||
to your configuration file. See the [configuration manual](usage/configuration/config_documentation.md#jwt_config) for some | |||||
sample settings. | sample settings. | ||||
## How to test JWT as a developer | ## How to test JWT as a developer | ||||
@@ -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 | |||||
`homeserver.yaml`. The configuration is slightly different if you're using docker. | |||||
To enable it, first add the `manhole` listener configuration in your | |||||
`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 | ||||
@@ -49,9 +49,9 @@ clients. | |||||
## Server configuration | ## Server configuration | ||||
Support for this feature can be enabled and configured in the | |||||
`retention` section of the Synapse configuration file (see the | |||||
[sample file](https://github.com/matrix-org/synapse/blob/v1.36.0/docs/sample_config.yaml#L451-L518)). | |||||
Support for this feature can be enabled and configured by adding a the | |||||
`retention` in the Synapse configuration file (see | |||||
[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 | |||||
the configuration file: | |||||
A default policy can be defined as such, by adding the `retention` option in | |||||
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 | |||||
[sample configuration file](https://github.com/matrix-org/synapse/blob/v1.36.0/docs/sample_config.yaml#L451-L518). | |||||
Synapse will use a default configuration, which is described here in the | |||||
[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 | |||||
`retention` section of the configuration file: | |||||
purging old events in a room. These limits can be defined under the | |||||
`retention` option in the configuration file: | |||||
```yaml | ```yaml | ||||
allowed_lifetime_min: 1d | allowed_lifetime_min: 1d | ||||
@@ -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). | |||||
See [sample_config.yaml](./sample_config.yaml) for some sample settings, as well as | |||||
setting in your configuration file. | |||||
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 | ||||
@@ -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 | |||||
[homserver.yaml](../usage/configuration/homeserver_sample_config.md). | |||||
To deactivate the certificate validation, the following setting must be added to | |||||
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 | ||||
@@ -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 | |||||
TLS-enabled listener. (Remove the hash sign (`#`) at the start of | |||||
each line). The relevant lines are like this: | |||||
- First, under the `listeners` option, add the configuration for the | |||||
TLS-enabled listener like so: | |||||
```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 | |||||
`tls_private_key_path` lines under the `TLS` section. You will need to manage | |||||
provisioning of these certificates yourself. | |||||
- You will also need to add the options `tls_certificate_path` and | |||||
`tls_private_key_path`. to your configuration file. You will need to manage provisioning of | |||||
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 | ||||
@@ -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: | ||||
@@ -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 | |||||
file](../../../configuration/homeserver_sample_config.md) for more details. | |||||
Please see the [cas_config](../../../configuration/config_documentation.md#cas_config) and [sso](../../../configuration/config_documentation.md#sso) | |||||
sections of the configuration manual for more details. |
@@ -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." | ||||
) | ) | ||||