@@ -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. | |||
belonging to a user. | |||
- `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` | |||
in the homeserver configuration. Note that no error is raised if the provided | |||
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 | |||
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. | |||
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: | |||
- 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 | |||
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 | |||
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: | |||
--- | |||
### `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 | |||
## 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 | |||
and is maintained by a script, `scripts-dev/generate_sample_config.sh`. | |||
Making sure that the output from this script matches the desired format | |||
is left as an exercise for the reader! | |||
@@ -49,9 +49,8 @@ as follows: | |||
* For other installation mechanisms, see the documentation provided by the | |||
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. | |||
## How to test JWT as a developer | |||
@@ -13,8 +13,10 @@ environments where untrusted users have shell access. | |||
## 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 | |||
@@ -49,9 +49,9 @@ clients. | |||
## 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 | |||
`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 | |||
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 | |||
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 | |||
message retention policies is enabled in the server's configuration. If | |||
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 | |||
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 | |||
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 | |||
allowed_lifetime_min: 1d | |||
@@ -45,8 +45,8 @@ as follows: | |||
maintainer. | |||
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. | |||
## Sample configs | |||
@@ -66,8 +66,8 @@ in Synapse can be deactivated. | |||
**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 | |||
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 | |||
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 | |||
listeners: | |||
- port: 8448 | |||
type: http | |||
tls: true | |||
@@ -419,9 +419,11 @@ so, you will need to edit `homeserver.yaml`, as follows: | |||
- 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 | |||
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 | |||
database. This is ignored if `enabled` is false, and is only useful | |||
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! | |||
* `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: | |||
@@ -4,5 +4,5 @@ Synapse supports authenticating users via the [Central Authentication | |||
Service protocol](https://en.wikipedia.org/wiki/Central_Authentication_Service) | |||
(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( | |||
'The config option "trust_identity_server_for_password_resets" ' | |||
'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." | |||
) | |||