diff options
Diffstat (limited to 'docs')
31 files changed, 186 insertions, 242 deletions
diff --git a/docs/.sample_config_header.yaml b/docs/.sample_config_header.yaml index 2355337e6d..acbaad8231 100644 --- a/docs/.sample_config_header.yaml +++ b/docs/.sample_config_header.yaml @@ -1,12 +1,12 @@ # This file is maintained as an up-to-date snapshot of the default # homeserver.yaml configuration generated by Synapse. You can find a # complete accounting of possible configuration options at -# https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html +# https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html # # It is *not* intended to be copied and used as the basis for a real # homeserver.yaml. Instead, if you are starting from scratch, please generate # a fresh config using Synapse by following the instructions in -# https://matrix-org.github.io/synapse/latest/setup/installation.html. +# https://element-hq.github.io/synapse/latest/setup/installation.html. # ################################################################################ diff --git a/docs/README.md b/docs/README.md index 5222ee5f03..0b2b910c73 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,13 +1,13 @@ # Synapse Documentation -**The documentation is currently hosted [here](https://matrix-org.github.io/synapse).** +**The documentation is currently hosted [here](https://element-hq.github.io/synapse).** Please update any links to point to the new website instead. ## About This directory currently holds a series of markdown files documenting how to install, use -and develop Synapse. The documentation is readable directly from this repository, but it is -recommended to instead browse through the [website](https://matrix-org.github.io/synapse) for +and develop Synapse. The documentation is readable directly from this repository, but it is +recommended to instead browse through the [website](https://element-hq.github.io/synapse) for easier discoverability. ## Adding to the documentation @@ -50,7 +50,7 @@ build the documentation with: mdbook build ``` -The rendered contents will be outputted to a new `book/` directory at the root of the repository. Please note that +The rendered contents will be outputted to a new `book/` directory at the root of the repository. Please note that index.html is not built by default, it is created by copying over the file `welcome_and_overview.html` to `index.html` during deployment. Thus, when running `mdbook serve` locally the book will initially show a 404 in place of the index due to the above. Do not be alarmed! diff --git a/docs/admin_api/README.rst b/docs/admin_api/README.rst index 8d6e76580a..db141732f9 100644 --- a/docs/admin_api/README.rst +++ b/docs/admin_api/README.rst @@ -1,7 +1,7 @@ Admin APIs ========== -**Note**: The latest documentation can be viewed `here <https://matrix-org.github.io/synapse>`_. +**Note**: The latest documentation can be viewed `here <https://element-hq.github.io/synapse>`_. See `docs/README.md <../README.md>`_ for more information. **Please update links to point to the website instead.** Existing files in this directory @@ -11,4 +11,3 @@ This directory includes documentation for the various synapse specific admin APIs available. Updates to the existing Admin API documentation should still be made to these files, but any new documentation files should instead be placed under `docs/usage/administration/admin_api <../usage/administration/admin_api>`_. - diff --git a/docs/admin_api/user_admin_api.md b/docs/admin_api/user_admin_api.md index e8e492d095..9dc600b875 100644 --- a/docs/admin_api/user_admin_api.md +++ b/docs/admin_api/user_admin_api.md @@ -149,10 +149,11 @@ Body parameters: granting them access to the Admin API, among other things. - `deactivated` - **bool**, optional. If unspecified, deactivation state will be left unchanged. - Note: the `password` field must also be set if both of the following are true: - - `deactivated` is set to `false` and the user was previously deactivated (you are reactivating this user) - - Users are allowed to set their password on this homeserver (both `password_config.enabled` and - `password_config.localdb_enabled` config options are set to `true`). + Note: + - For the password field there is no strict check of the necessity for its presence. + It is possible to have active users without a password, e.g. when authenticating with OIDC is configured. + You must check yourself whether a password is required when reactivating a user or not. + - It is not possible to set a password if the config option `password_config.localdb_enabled` is set `false`. Users' passwords are wiped upon account deactivation, hence the need to set a new one here. Note: a user cannot be erased with this API. For more details on @@ -223,7 +224,7 @@ The following parameters should be set in the URL: **or** displaynames that contain this value. - `guests` - string representing a bool - Is optional and if `false` will **exclude** guest users. Defaults to `true` to include guest users. This parameter is not supported when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582) -- `admins` - Optional flag to filter admins. If `true`, only admins are queried. If `false`, admins are excluded from +- `admins` - Optional flag to filter admins. If `true`, only admins are queried. If `false`, admins are excluded from the query. When the flag is absent (the default), **both** admins and non-admins are included in the search results. - `deactivated` - string representing a bool - Is optional and if `true` will **include** deactivated users. Defaults to `false` to exclude deactivated users. @@ -272,7 +273,7 @@ The following fields are returned in the JSON response body: - `is_guest` - bool - Status if that user is a guest account. - `admin` - bool - Status if that user is a server administrator. - `user_type` - string - Type of the user. Normal users are type `None`. - This allows user type specific behaviour. There are also types `support` and `bot`. + This allows user type specific behaviour. There are also types `support` and `bot`. - `deactivated` - bool - Status if that user has been marked as deactivated. - `erased` - bool - Status if that user has been marked as erased. - `shadow_banned` - bool - Status if that user has been marked as shadow banned. @@ -887,7 +888,7 @@ The following fields are returned in the JSON response body: ### Create a device -Creates a new device for a specific `user_id` and `device_id`. Does nothing if the `device_id` +Creates a new device for a specific `user_id` and `device_id`. Does nothing if the `device_id` exists already. The API is: @@ -1254,11 +1255,11 @@ The following parameters should be set in the URL: ## Check username availability -Checks to see if a username is available, and valid, for the server. See [the client-server +Checks to see if a username is available, and valid, for the server. See [the client-server API](https://matrix.org/docs/spec/client_server/r0.6.0#get-matrix-client-r0-register-available) for more information. -This endpoint will work even if registration is disabled on the server, unlike +This endpoint will work even if registration is disabled on the server, unlike `/_matrix/client/r0/register/available`. The API is: diff --git a/docs/consent_tracking.md b/docs/consent_tracking.md index 26620a0752..b45a057b73 100644 --- a/docs/consent_tracking.md +++ b/docs/consent_tracking.md @@ -24,7 +24,7 @@ To enable this, first create templates for the policy and success pages. These should be stored on the local filesystem. These templates use the [Jinja2](http://jinja.pocoo.org) templating language, -and [docs/privacy_policy_templates](https://github.com/matrix-org/synapse/tree/develop/docs/privacy_policy_templates/) +and [docs/privacy_policy_templates](https://github.com/element-hq/synapse/tree/develop/docs/privacy_policy_templates/) gives examples of the sort of thing that can be done. Note that the templates must be stored under a name giving the language of the diff --git a/docs/development/contributing_guide.md b/docs/development/contributing_guide.md index 57cac7ed16..08de320b1b 100644 --- a/docs/development/contributing_guide.md +++ b/docs/development/contributing_guide.md @@ -4,14 +4,16 @@ This document aims to get you started with contributing to Synapse! # 1. Who can contribute to Synapse? -Everyone is welcome to contribute code to [matrix.org -projects](https://github.com/matrix-org), provided that they are willing to -license their contributions under the same license as the project itself. We -follow a simple 'inbound=outbound' model for contributions: the act of -submitting an 'inbound' contribution means that the contributor agrees to -license the code under the same terms as the project's overall 'outbound' -license - in our case, this is almost always Apache Software License v2 (see -[LICENSE](https://github.com/matrix-org/synapse/blob/develop/LICENSE)). +Everyone is welcome to contribute code to +[Synapse](https://github.com/element-hq/synapse), provided that they are willing +to license their contributions to Element under a [Contributor License +Agreement](https://cla-assistant.io/element-hq/synapse) (CLA). This ensures that +their contribution will be made available under an OSI-approved open-source +license, currently Affero General Public License v3 (AGPLv3). + +Please see the +[Element blog post](https://element.io/blog/synapse-now-lives-at-github-com-element-hq-synapse/) +for the full rationale. # 2. What do I need? @@ -97,8 +99,8 @@ Now edit `homeserver.yaml`, things you might want to change include: - Set a `server_name` - Adjusting paths to be correct for your system like the `log_config` to point to the log config you just copied -- Using a [PostgreSQL database instead of SQLite](https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html#database) -- Adding a [`registration_shared_secret`](https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html#registration_shared_secret) so you can use [`register_new_matrix_user` command](https://matrix-org.github.io/synapse/latest/setup/installation.html#registering-a-user). +- Using a [PostgreSQL database instead of SQLite](https://vector-im.github.io/synapse/latest/usage/configuration/config_documentation.html#database) +- Adding a [`registration_shared_secret`](https://vector-im.github.io/synapse/latest/usage/configuration/config_documentation.html#registration_shared_secret) so you can use [`register_new_matrix_user` command](https://vector-im.github.io/synapse/latest/setup/installation.html#registering-a-user). And then run Synapse with the following command: @@ -122,22 +124,22 @@ Join our developer community on Matrix: [#synapse-dev:matrix.org](https://matrix # 6. Pick an issue. -Fix your favorite problem or perhaps find a [Good First Issue](https://github.com/matrix-org/synapse/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+First+Issue%22) +Fix your favorite problem or perhaps find a [Good First Issue](https://github.com/element-hq/synapse/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+First+Issue%22) to work on. # 7. Turn coffee into code and documentation! There is a growing amount of documentation located in the -[`docs`](https://github.com/matrix-org/synapse/tree/develop/docs) -directory, with a rendered version [available online](https://matrix-org.github.io/synapse). +[`docs`](https://github.com/element-hq/synapse/tree/develop/docs) +directory, with a rendered version [available online](https://vector-im.github.io/synapse). This documentation is intended primarily for sysadmins running their own Synapse instance, as well as developers interacting externally with Synapse. -[`docs/development`](https://github.com/matrix-org/synapse/tree/develop/docs/development) +[`docs/development`](https://github.com/element-hq/synapse/tree/develop/docs/development) exists primarily to house documentation for Synapse developers. -[`docs/admin_api`](https://github.com/matrix-org/synapse/tree/develop/docs/admin_api) houses documentation +[`docs/admin_api`](https://github.com/element-hq/synapse/tree/develop/docs/admin_api) houses documentation regarding Synapse's Admin API, which is used mostly by sysadmins and external service developers. @@ -147,14 +149,10 @@ options and documentation](../code_style.md#configuration-code-and-documentation We welcome improvements and additions to our documentation itself! When writing new pages, please -[build `docs` to a book](https://github.com/matrix-org/synapse/tree/develop/docs#adding-to-the-documentation) +[build `docs` to a book](https://github.com/element-hq/synapse/tree/develop/docs#adding-to-the-documentation) to check that your contributions render correctly. The docs are written in [GitHub-Flavoured Markdown](https://guides.github.com/features/mastering-markdown/). -Some documentation also exists in [Synapse's GitHub -Wiki](https://github.com/matrix-org/synapse/wiki), although this is primarily -contributed to by community authors. - When changes are made to any Rust code then you must call either `poetry install` or `maturin develop` (if installed) to rebuild the Rust code. Using [`maturin`](https://github.com/PyO3/maturin) is quicker than `poetry install`, so is recommended when making frequent @@ -331,7 +329,7 @@ This configuration should generally cover your needs. - To run with Postgres, supply the `-e POSTGRES=1 -e MULTI_POSTGRES=1` environment flags. - To run with Synapse in worker mode, supply the `-e WORKERS=1 -e REDIS=1` environment flags (in addition to the Postgres flags). -For more details about other configurations, see the [Docker-specific documentation in the SyTest repo](https://github.com/matrix-org/sytest/blob/develop/docker/README.md). +For more details about other configurations, see the [Docker-specific documentation in the SyTest repo](https://github.com/vector-im/sytest/blob/develop/docker/README.md). ## Run the integration tests ([Complement](https://github.com/matrix-org/complement)). @@ -365,7 +363,7 @@ The above will run a monolithic (single-process) Synapse with SQLite as the data - If setting `WORKERS=1`, optionally set `WORKER_TYPES=` to declare which worker types you wish to test. A simple comma-delimited string containing the worker types defined from the `WORKERS_CONFIG` template in - [here](https://github.com/matrix-org/synapse/blob/develop/docker/configure_workers_and_start.py#L54). + [here](https://github.com/element-hq/synapse/blob/develop/docker/configure_workers_and_start.py#L54). A safe example would be `WORKER_TYPES="federation_inbound, federation_sender, synchrotron"`. See the [worker documentation](../workers.md) for additional information on workers. - Passing `ASYNCIO_REACTOR=1` as an environment variable to use the Twisted asyncio reactor instead of the default one. @@ -434,7 +432,7 @@ in the format of `PRnumber.type`. The type can be one of the following: * `misc` (for internal-only changes) This file will become part of our [changelog]( -https://github.com/matrix-org/synapse/blob/master/CHANGES.md) at the next +https://github.com/element-hq/synapse/blob/master/CHANGES.md) at the next release, so the content of the file should be a short description of your change in the same style as the rest of the changelog. The file can contain Markdown formatting, and must end with a full stop (.) or an exclamation mark (!) for @@ -466,7 +464,7 @@ There are two options for solving this: add the changelog file to your branch, or: 1. Look at the [list of all - issues/PRs](https://github.com/matrix-org/synapse/issues?q=), add one to the + issues/PRs](https://github.com/element-hq/synapse/issues?q=), add one to the highest number you see, and quickly open the PR before somebody else claims your number. @@ -501,81 +499,19 @@ separate pull requests.) ## Sign off -In order to have a concrete record that your contribution is intentional -and you agree to license it under the same terms as the project's license, we've adopted the -same lightweight approach that the Linux Kernel -[submitting patches process]( -https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin>), -[Docker](https://github.com/docker/docker/blob/master/CONTRIBUTING.md), and many other -projects use: the DCO ([Developer Certificate of Origin](http://developercertificate.org/)). -This is a simple declaration that you wrote -the contribution or otherwise have the right to contribute it to Matrix: - -``` -Developer Certificate of Origin -Version 1.1 - -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - -Developer's Certificate of Origin 1.1 - -By making a contribution to this project, I certify that: - -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -(b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or +After you make a PR a comment from @CLAassistant will appear asking you to sign +the [CLA](https://cla-assistant.io/element-hq/synapse). +This will link a page to allow you to confirm that you have read and agreed to +the CLA by signing in with GitHub. -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -``` - -If you agree to this for your contribution, then all that's needed is to -include the line in your commit or pull request comment: - -``` -Signed-off-by: Your Name <your@email.example.org> -``` +Alternatively, you can sign off before opening a PR by going to +<https://cla-assistant.io/element-hq/synapse>. We accept contributions under a legally identifiable name, such as your name on government documentation or common-law names (names claimed by legitimate usage or repute). Unfortunately, we cannot accept anonymous contributions at this time. -Git allows you to add this signoff automatically when using the `-s` -flag to `git commit`, which uses the name and email set in your -`user.name` and `user.email` git configs. - -### Private Sign off - -If you would like to provide your legal name privately to the Matrix.org -Foundation (instead of in a public commit or comment), you can do so -by emailing your legal name and a link to the pull request to -[dco@matrix.org](mailto:dco@matrix.org?subject=Private%20sign%20off). -It helps to include "sign off" or similar in the subject line. You will then -be instructed further. - -Once private sign off is complete, doing so for future contributions will not -be required. # 10. Turn feedback into better code. diff --git a/docs/development/demo.md b/docs/development/demo.md index 893ed6998e..f78f5f1c0a 100644 --- a/docs/development/demo.md +++ b/docs/development/demo.md @@ -2,7 +2,7 @@ **DO NOT USE THESE DEMO SERVERS IN PRODUCTION** -Requires you to have a [Synapse development environment setup](https://matrix-org.github.io/synapse/develop/development/contributing_guide.html#4-install-the-dependencies). +Requires you to have a [Synapse development environment setup](https://element-hq.github.io/synapse/develop/development/contributing_guide.html#4-install-the-dependencies). The demo setup allows running three federation Synapse servers, with server names `localhost:8480`, `localhost:8481`, and `localhost:8482`. diff --git a/docs/development/dependencies.md b/docs/development/dependencies.md index b5926d96ff..e4378231aa 100644 --- a/docs/development/dependencies.md +++ b/docs/development/dependencies.md @@ -79,9 +79,9 @@ phonenumbers = [ We can see this pinned version inside the docker image for that release: ``` -$ docker pull matrixdotorg/synapse:v1.57.0 +$ docker pull vectorim/synapse:v1.97.0 ... -$ docker run --entrypoint pip matrixdotorg/synapse:v1.57.0 show phonenumbers +$ docker run --entrypoint pip vectorim/synapse:v1.97.0 show phonenumbers Name: phonenumbers Version: 8.12.44 Summary: Python version of Google's common library for parsing, formatting, storing and validating international phone numbers. diff --git a/docs/development/git.md b/docs/development/git.md index 9b1ed54b65..b68c03fec1 100644 --- a/docs/development/git.md +++ b/docs/development/git.md @@ -14,11 +14,11 @@ b2dba0607`: Note how the commit comment explains clearly what is changing and why. Also note the *absence* of merge commits, as well as the absence of commits called things like (to pick a few culprits): -[“pep8”](https://github.com/matrix-org/synapse/commit/84691da6c), [“fix broken -test”](https://github.com/matrix-org/synapse/commit/474810d9d), -[“oops”](https://github.com/matrix-org/synapse/commit/c9d72e457), -[“typo”](https://github.com/matrix-org/synapse/commit/836358823), or [“Who's -the president?”](https://github.com/matrix-org/synapse/commit/707374d5d). +[“pep8”](https://github.com/element-hq/synapse/commit/84691da6c), [“fix broken +test”](https://github.com/element-hq/synapse/commit/474810d9d), +[“oops”](https://github.com/element-hq/synapse/commit/c9d72e457), +[“typo”](https://github.com/element-hq/synapse/commit/836358823), or [“Who's +the president?”](https://github.com/element-hq/synapse/commit/707374d5d). There are a number of reasons why keeping a clean commit history is a good thing: diff --git a/docs/development/synapse_architecture/streams.md b/docs/development/synapse_architecture/streams.md index 67d92acfa1..4981416835 100644 --- a/docs/development/synapse_architecture/streams.md +++ b/docs/development/synapse_architecture/streams.md @@ -1,7 +1,7 @@ ## Streams Synapse has a concept of "streams", which are roughly described in [`id_generators.py`]( - https://github.com/matrix-org/synapse/blob/develop/synapse/storage/util/id_generators.py + https://github.com/element-hq/synapse/blob/develop/synapse/storage/util/id_generators.py ). Generally speaking, streams are a series of notifications that something in Synapse's database has changed that the application might need to respond to. For example: @@ -11,12 +11,12 @@ For example: - The to-device stream reports when a device has a new [to-device message](https://spec.matrix.org/v1.7/client-server-api/#send-to-device-messaging). See [`synapse.replication.tcp.streams`]( - https://github.com/matrix-org/synapse/blob/develop/synapse/replication/tcp/streams/__init__.py + https://github.com/element-hq/synapse/blob/develop/synapse/replication/tcp/streams/__init__.py ) for the full list of streams. It is very helpful to understand the streams mechanism when working on any part of Synapse that needs to respond to changes—especially if those changes are made by different workers. To that end, let's describe streams formally, paraphrasing from the docstring of [`AbstractStreamIdGenerator`]( - https://github.com/matrix-org/synapse/blob/a719b703d9bd0dade2565ddcad0e2f3a7a9d4c37/synapse/storage/util/id_generators.py#L96 + https://github.com/element-hq/synapse/blob/a719b703d9bd0dade2565ddcad0e2f3a7a9d4c37/synapse/storage/util/id_generators.py#L96 ). ### Definition diff --git a/docs/federate.md b/docs/federate.md index df4c87da51..cfbfd16ff8 100644 --- a/docs/federate.md +++ b/docs/federate.md @@ -54,7 +54,7 @@ in the HTTP library used by Synapse, 308 redirects are currently not followed by federating servers, which can cause `M_UNKNOWN` or `401 Unauthorized` errors. This may affect users who are redirecting apex-to-www (e.g. `example.com` -> `www.example.com`), and especially users of the Kubernetes *Nginx Ingress* module, which uses 308 redirect -codes by default. For those Kubernetes users, [this Stackoverflow post](https://stackoverflow.com/a/52617528/5096871) +codes by default. For those Kubernetes users, [this Stackoverflow post](https://stackoverflow.com/a/52617528/5096871) might be helpful. For other users, switching to a `301 Moved Permanently` code may be an option. 308 redirect codes will be supported properly in a future release of Synapse. @@ -64,4 +64,4 @@ release of Synapse. If you want to get up and running quickly with a trio of homeservers in a private federation, there is a script in the `demo` directory. This is mainly useful just for development purposes. See -[demo scripts](https://matrix-org.github.io/synapse/develop/development/demo.html). +[demo scripts](https://element-hq.github.io/synapse/develop/development/demo.html). diff --git a/docs/manhole.md b/docs/manhole.md index 4e5bf833ce..214c32497e 100644 --- a/docs/manhole.md +++ b/docs/manhole.md @@ -38,7 +38,7 @@ docker run -d --name synapse \ --mount type=volume,src=synapse-data,dst=/data \ -p 8008:8008 \ -p 127.0.0.1:9000:9000 \ - matrixdotorg/synapse:latest + vectorim/synapse:latest ``` #### Native config diff --git a/docs/metrics-howto.md b/docs/metrics-howto.md index 16e4368f35..eb6b90cec9 100644 --- a/docs/metrics-howto.md +++ b/docs/metrics-howto.md @@ -87,8 +87,8 @@ 1. Restart Prometheus. -1. Consider using the [grafana dashboard](https://github.com/matrix-org/synapse/tree/master/contrib/grafana/) - and required [recording rules](https://github.com/matrix-org/synapse/tree/master/contrib/prometheus/) +1. Consider using the [grafana dashboard](https://github.com/element-hq/synapse/tree/master/contrib/grafana/) + and required [recording rules](https://github.com/element-hq/synapse/tree/master/contrib/prometheus/) ## Monitoring workers diff --git a/docs/modules/third_party_rules_callbacks.md b/docs/modules/third_party_rules_callbacks.md index 4a27d976fb..d06bff25eb 100644 --- a/docs/modules/third_party_rules_callbacks.md +++ b/docs/modules/third_party_rules_callbacks.md @@ -224,7 +224,7 @@ wishing this callback to be called on every profile change are encouraged to dis per-room profiles globally using the `allow_per_room_profiles` configuration setting in Synapse's configuration file. This callback is not called when registering a user, even when setting it through the -[`get_displayname_for_registration`](https://matrix-org.github.io/synapse/latest/modules/password_auth_provider_callbacks.html#get_displayname_for_registration) +[`get_displayname_for_registration`](https://element-hq.github.io/synapse/latest/modules/password_auth_provider_callbacks.html#get_displayname_for_registration) module callback. If multiple modules implement this callback, Synapse runs them all in order. @@ -343,4 +343,4 @@ class EventCensorer: ) event_dict["content"] = new_event_content return event_dict -``` \ No newline at end of file +``` diff --git a/docs/modules/writing_a_module.md b/docs/modules/writing_a_module.md index b99f64b9d8..93f24d0da1 100644 --- a/docs/modules/writing_a_module.md +++ b/docs/modules/writing_a_module.md @@ -10,7 +10,7 @@ either the output of the module's `parse_config` static method (see below), or t configuration associated with the module in Synapse's configuration file. See the documentation for the `ModuleApi` class -[here](https://github.com/matrix-org/synapse/blob/master/synapse/module_api/__init__.py). +[here](https://github.com/element-hq/synapse/blob/master/synapse/module_api/__init__.py). ## When Synapse runs with several modules configured @@ -82,7 +82,7 @@ the callback name as the argument name and the function as its value. A `register_[...]_callbacks` method exists for each category. Callbacks for each category can be found on their respective page of the -[Synapse documentation website](https://matrix-org.github.io/synapse). +[Synapse documentation website](https://element-hq.github.io/synapse). ## Caching @@ -109,7 +109,7 @@ from synapse.module_api import cached, ModuleApi class MyModule: def __init__(self, config: Any, api: ModuleApi): self.api = api - + # Register the cached function so Synapse knows how to correctly invalidate # entries for it. self.api.register_cached_function(self.get_user_from_id) @@ -124,15 +124,15 @@ class MyModule: async def do_something_with_users(self) -> None: """Calls the cached function and then invalidates an entry in its cache.""" - + user_id = "@alice:example.com" - + # Get the user. Since get_department_for_user is wrapped with a cache, # the return value for this user_id will be cached. department = await self.get_department_for_user(user_id) - + # Do something with `department`... - + # Let's say something has changed with our user, and the entry we have for # them in the cache is out of date, so we want to invalidate it. await self.api.invalidate_cache(self.get_department_for_user, (user_id,)) diff --git a/docs/sample_config.yaml b/docs/sample_config.yaml index 6578ec0229..0d75e6d4a1 100644 --- a/docs/sample_config.yaml +++ b/docs/sample_config.yaml @@ -1,12 +1,12 @@ # This file is maintained as an up-to-date snapshot of the default # homeserver.yaml configuration generated by Synapse. You can find a # complete accounting of possible configuration options at -# https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html +# https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html # # It is *not* intended to be copied and used as the basis for a real # homeserver.yaml. Instead, if you are starting from scratch, please generate # a fresh config using Synapse by following the instructions in -# https://matrix-org.github.io/synapse/latest/setup/installation.html. +# https://element-hq.github.io/synapse/latest/setup/installation.html. # ################################################################################ @@ -20,7 +20,7 @@ # # For more information on how to configure Synapse, including a complete accounting of # each option, go to docs/usage/configuration/config_documentation.md or -# https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html +# https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html server_name: "SERVERNAME" pid_file: DATADIR/homeserver.pid listeners: diff --git a/docs/sample_log_config.yaml b/docs/sample_log_config.yaml index ae0318122e..dcbe88854c 100644 --- a/docs/sample_log_config.yaml +++ b/docs/sample_log_config.yaml @@ -7,7 +7,7 @@ # be ingested by ELK stacks. See [2] for details. # # [1]: https://docs.python.org/3/library/logging.config.html#configuration-dictionary-schema -# [2]: https://matrix-org.github.io/synapse/latest/structured_logging.html +# [2]: https://element-hq.github.io/synapse/latest/structured_logging.html version: 1 diff --git a/docs/server_notices.md b/docs/server_notices.md index aae25d23b8..33b2f4c9ee 100644 --- a/docs/server_notices.md +++ b/docs/server_notices.md @@ -44,14 +44,16 @@ section, which should look like this: server_notices: system_mxid_localpart: server system_mxid_display_name: "Server Notices" - system_mxid_avatar_url: "mxc://server.com/oumMVlgDnLYFaPVkExemNVVZ" + system_mxid_avatar_url: "mxc://example.com/oumMVlgDnLYFaPVkExemNVVZ" room_name: "Server Notices" + room_avatar_url: "mxc://example.com/oumMVlgDnLYFaPVkExemNVVZ" + room_topic: "Room used by your server admin to notice you of important information" auto_join: true ``` The only compulsory setting is `system_mxid_localpart`, which defines the user id of the Server Notices user, as above. `room_name` defines the name of the -room which will be created. +room which will be created, `room_avatar_url` its avatar and `room_topic` its topic. `system_mxid_display_name` and `system_mxid_avatar_url` can be used to set the displayname and avatar of the Server Notices user. diff --git a/docs/setup/installation.md b/docs/setup/installation.md index 1f13864a8f..fb64c9ba4d 100644 --- a/docs/setup/installation.md +++ b/docs/setup/installation.md @@ -26,9 +26,9 @@ for most users. #### Docker images and Ansible playbooks There is an official synapse image available at -<https://hub.docker.com/r/matrixdotorg/synapse> or at [`ghcr.io/matrix-org/synapse`](https://ghcr.io/matrix-org/synapse) +<https://hub.docker.com/r/vectorim/synapse> or at [`ghcr.io/element-hq/synapse`](https://ghcr.io/element-hq/synapse) which can be used with the docker-compose file available at -[contrib/docker](https://github.com/matrix-org/synapse/tree/develop/contrib/docker). +[contrib/docker](https://github.com/element-hq/synapse/tree/develop/contrib/docker). Further information on this including configuration options is available in the README on hub.docker.com. @@ -48,10 +48,12 @@ For more details, see ##### Matrix.org packages Matrix.org provides Debian/Ubuntu packages of Synapse, for the amd64 -architecture via <https://packages.matrix.org/debian/>. +architecture via <https://packages.matrix.org/debian/>. To install the latest release: +TODO UPDATE ALL THIS + ```sh sudo apt install -y lsb-release wget apt-transport-https sudo wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg @@ -446,9 +448,9 @@ listeners: ``` - 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 + `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 +- 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 diff --git a/docs/sso_mapping_providers.md b/docs/sso_mapping_providers.md index a5d4659619..77cc02c541 100644 --- a/docs/sso_mapping_providers.md +++ b/docs/sso_mapping_providers.md @@ -115,7 +115,7 @@ A custom mapping provider must specify the following methods: Synapse has a built-in OpenID mapping provider if a custom provider isn't specified in the config. It is located at -[`synapse.handlers.oidc.JinjaOidcMappingProvider`](https://github.com/matrix-org/synapse/blob/develop/synapse/handlers/oidc.py). +[`synapse.handlers.oidc.JinjaOidcMappingProvider`](https://github.com/element-hq/synapse/blob/develop/synapse/handlers/oidc.py). ## SAML Mapping Providers @@ -202,4 +202,4 @@ A custom mapping provider must specify the following methods: Synapse has a built-in SAML mapping provider if a custom provider isn't specified in the config. It is located at -[`synapse.handlers.saml.DefaultSamlMappingProvider`](https://github.com/matrix-org/synapse/blob/develop/synapse/handlers/saml.py). +[`synapse.handlers.saml.DefaultSamlMappingProvider`](https://github.com/element-hq/synapse/blob/develop/synapse/handlers/saml.py). diff --git a/docs/systemd-with-workers/README.md b/docs/systemd-with-workers/README.md index d516501085..e2b96698d0 100644 --- a/docs/systemd-with-workers/README.md +++ b/docs/systemd-with-workers/README.md @@ -6,10 +6,10 @@ well as a `matrix-synapse-worker@` service template for any workers you require. Additionally, to group the required services, it sets up a `matrix-synapse.target`. -See the folder [system](https://github.com/matrix-org/synapse/tree/develop/docs/systemd-with-workers/system/) +See the folder [system](https://github.com/element-hq/synapse/tree/develop/docs/systemd-with-workers/system/) for the systemd unit files. -The folder [workers](https://github.com/matrix-org/synapse/tree/develop/docs/systemd-with-workers/workers/) +The folder [workers](https://github.com/element-hq/synapse/tree/develop/docs/systemd-with-workers/workers/) contains an example configuration for the `generic_worker` worker. ## Synapse configuration files @@ -33,7 +33,7 @@ There is no need for a separate configuration file for the master process. ## Set up 1. Adjust synapse configuration files as above. -1. Copy the `*.service` and `*.target` files in [system](https://github.com/matrix-org/synapse/tree/develop/docs/systemd-with-workers/system/) +1. Copy the `*.service` and `*.target` files in [system](https://github.com/element-hq/synapse/tree/develop/docs/systemd-with-workers/system/) to `/etc/systemd/system`. 1. Run `systemctl daemon-reload` to tell systemd to load the new unit files. 1. Run `systemctl enable matrix-synapse.service`. This will configure the @@ -74,7 +74,7 @@ systemctl restart matrix-synapse.target **Optional:** If further hardening is desired, the file `override-hardened.conf` may be copied from -[contrib/systemd/override-hardened.conf](https://github.com/matrix-org/synapse/tree/develop/contrib/systemd/) +[contrib/systemd/override-hardened.conf](https://github.com/element-hq/synapse/tree/develop/contrib/systemd/) in this repository to the location `/etc/systemd/system/matrix-synapse.service.d/override-hardened.conf` (the directory may have to be created). It enables certain sandboxing features in diff --git a/docs/templates.md b/docs/templates.md index 453ac90dd8..fec6e1f39b 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -3,7 +3,7 @@ Synapse uses parametrised templates to generate the content of emails it sends and webpages it shows to users. -By default, Synapse will use the templates listed [here](https://github.com/matrix-org/synapse/tree/master/synapse/res/templates). +By default, Synapse will use the templates listed [here](https://github.com/element-hq/synapse/tree/master/synapse/res/templates). Server admins can configure an additional directory for Synapse to look for templates in, allowing them to specify custom templates: @@ -128,7 +128,7 @@ registration and password reset: page above. When rendering, `password_reset_success.html` is given no variable, and `password_reset_failure.html` is given a `failure_reason`, which contains the reason - for the password reset failure. + for the password reset failure. * `registration_success.html` and `registration_failure.html`: HTML pages for success and failure that a user will see when they follow the link in an address verification email sent during registration. diff --git a/docs/upgrade.md b/docs/upgrade.md index 329c9c7787..8fc146566f 100644 --- a/docs/upgrade.md +++ b/docs/upgrade.md @@ -110,13 +110,13 @@ date. ## App service query parameter authorization is now a configuration option Synapse v1.81.0 deprecated application service authorization via query parameters as this is -considered insecure - and from Synapse v1.71.0 forwards the application service token has also been sent via +considered insecure - and from Synapse v1.71.0 forwards the application service token has also been sent via [the `Authorization` header](https://spec.matrix.org/v1.6/application-service-api/#authorization)], making the insecure -query parameter authorization redundant. Since removing the ability to continue to use query parameters could break -backwards compatibility it has now been put behind a configuration option, `use_appservice_legacy_authorization`. -This option defaults to false, but can be activated by adding +query parameter authorization redundant. Since removing the ability to continue to use query parameters could break +backwards compatibility it has now been put behind a configuration option, `use_appservice_legacy_authorization`. +This option defaults to false, but can be activated by adding ```yaml -use_appservice_legacy_authorization: true +use_appservice_legacy_authorization: true ``` to your configuration. @@ -144,9 +144,9 @@ packages or Docker images, no action is required. As mentioned previously in [Upgrading to v1.84.0](#upgrading-to-v1840), the following deprecated settings are being removed in this release of Synapse: -* [`worker_replication_host`](https://matrix-org.github.io/synapse/v1.86/usage/configuration/config_documentation.html#worker_replication_host) -* [`worker_replication_http_port`](https://matrix-org.github.io/synapse/v1.86/usage/configuration/config_documentation.html#worker_replication_http_port) -* [`worker_replication_http_tls`](https://matrix-org.github.io/synapse/v1.86/usage/configuration/config_documentation.html#worker_replication_http_tls) +* [`worker_replication_host`](https://element-hq.github.io/synapse/v1.86/usage/configuration/config_documentation.html#worker_replication_host) +* [`worker_replication_http_port`](https://element-hq.github.io/synapse/v1.86/usage/configuration/config_documentation.html#worker_replication_http_port) +* [`worker_replication_http_tls`](https://element-hq.github.io/synapse/v1.86/usage/configuration/config_documentation.html#worker_replication_http_tls) Please ensure that you have migrated to using `main` on your shared configuration's `instance_map` (or create one if necessary). This is required if you have ***any*** workers at all; @@ -184,7 +184,7 @@ When using workers, * `worker_replication_host` * `worker_replication_http_port` * `worker_replication_http_tls` - + should now be removed from individual worker YAML configurations and the main process should instead be added to the `instance_map` in the shared YAML configuration, using the name `main`. @@ -260,7 +260,7 @@ worker_listeners: worker_log_config: /etc/matrix-synapse/generic-worker-log.yaml ``` -Notes: +Notes: * `tls` is optional but mirrors the functionality of `worker_replication_http_tls` @@ -352,8 +352,8 @@ and device replication will resume as normal. ## Minimum version of Poetry is now 1.3.2 -The minimum supported version of Poetry is now 1.3.2 (previously 1.2.0, [since -Synapse 1.67](#upgrading-to-v1670)). If you have used `poetry install` to +The minimum supported version of Poetry is now 1.3.2 (previously 1.2.0, [since +Synapse 1.67](#upgrading-to-v1670)). If you have used `poetry install` to install Synapse from a source checkout, you should upgrade poetry: see its [installation instructions](https://python-poetry.org/docs/#installation). For all other installation methods, no acction is required. @@ -499,7 +499,7 @@ the names of Prometheus metrics. If you want to test your changes before legacy names are disabled by default, you may specify `enable_legacy_metrics: false` in your homeserver configuration. -A list of affected metrics is available on the [Metrics How-to page](https://matrix-org.github.io/synapse/v1.69/metrics-howto.html?highlight=metrics%20deprecated#renaming-of-metrics--deprecation-of-old-names-in-12). +A list of affected metrics is available on the [Metrics How-to page](https://element-hq.github.io/synapse/v1.69/metrics-howto.html?highlight=metrics%20deprecated#renaming-of-metrics--deprecation-of-old-names-in-12). ## Deprecation of the `generate_short_term_login_token` module API method @@ -556,7 +556,7 @@ are not affected. Building from a source checkout of Synapse now requires a recent Rust compiler (currently Rust 1.58.1, but see also the -[Platform Dependency Policy](https://matrix-org.github.io/synapse/latest/deprecation_policy.html)). +[Platform Dependency Policy](https://element-hq.github.io/synapse/latest/deprecation_policy.html)). Installations using @@ -626,7 +626,7 @@ homeserver administrators more notice of the change. To continue to allow users to add email addresses to their homeserver accounts, and perform password resets, make sure that Synapse is configured with a working email server in the [`email` configuration -section](https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html#email) +section](https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html#email) (including, at a minimum, a `notif_from` setting.) Specifying an `email` setting under `account_threepid_delegates` will now cause @@ -639,7 +639,7 @@ an error at startup. Synapse v1.66.0 will remove the ability to delegate the tasks of verifying email address ownership, and password reset confirmation, to an identity server. If you require your homeserver to verify e-mail addresses or to support password resets via e-mail, please configure your homeserver with SMTP access so that it can send e-mails on its own behalf. -[Consult the configuration documentation for more information.](https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html#email) +[Consult the configuration documentation for more information.](https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html#email) The option that will be removed is `account_threepid_delegates.email`. @@ -849,7 +849,7 @@ The names of user devices are no longer visible to users on other homeservers by Device IDs are unaffected, as these are necessary to facilitate end-to-end encryption. To re-enable this functionality, set the -[`allow_device_name_lookup_over_federation`](https://matrix-org.github.io/synapse/v1.59/usage/configuration/config_documentation.html#federation) +[`allow_device_name_lookup_over_federation`](https://element-hq.github.io/synapse/v1.59/usage/configuration/config_documentation.html#federation) homeserver config option to `true`. @@ -968,7 +968,7 @@ experimental_features: Synapse now refuses to start when using PostgreSQL with non-`C` values for `COLLATE` and `CTYPE` unless the config flag `allow_unsafe_locale`, found in the database section of -the configuration file, is set to `true`. See the [PostgreSQL documentation](https://matrix-org.github.io/synapse/latest/postgres.html#fixing-incorrect-collate-or-ctype) +the configuration file, is set to `true`. See the [PostgreSQL documentation](https://element-hq.github.io/synapse/latest/postgres.html#fixing-incorrect-collate-or-ctype) for more information and instructions on how to fix a database with incorrect values. # Upgrading to v1.55.0 @@ -1007,7 +1007,7 @@ please upgrade Mjolnir to version 1.3.2 or later before upgrading Synapse. This release removes support for the `structured: true` logging configuration which was deprecated in Synapse v1.23.0. If your logging configuration contains `structured: true` then it should be modified based on the -[structured logging documentation](https://matrix-org.github.io/synapse/v1.56/structured_logging.html#upgrading-from-legacy-structured-logging-configuration). +[structured logging documentation](https://element-hq.github.io/synapse/v1.56/structured_logging.html#upgrading-from-legacy-structured-logging-configuration). # Upgrading to v1.53.0 @@ -1067,10 +1067,10 @@ are now active by default. As announced with the release of [Synapse 1.47.0](#deprecation-of-the-user_may_create_room_with_invites-module-callback), the deprecated `user_may_create_room_with_invites` module callback has been removed. -Modules relying on it can instead implement [`user_may_invite`](https://matrix-org.github.io/synapse/latest/modules/spam_checker_callbacks.html#user_may_invite) -and use the [`get_room_state`](https://github.com/matrix-org/synapse/blob/872f23b95fa980a61b0866c1475e84491991fa20/synapse/module_api/__init__.py#L869-L876) +Modules relying on it can instead implement [`user_may_invite`](https://element-hq.github.io/synapse/latest/modules/spam_checker_callbacks.html#user_may_invite) +and use the [`get_room_state`](https://github.com/element-hq/synapse/blob/872f23b95fa980a61b0866c1475e84491991fa20/synapse/module_api/__init__.py#L869-L876) module API to infer whether the invite is happening while creating a room (see [this function](https://github.com/matrix-org/synapse-domain-rule-checker/blob/e7d092dd9f2a7f844928771dbfd9fd24c2332e48/synapse_domain_rule_checker/__init__.py#L56-L89) -as an example). Alternately, modules can also implement [`on_create_room`](https://matrix-org.github.io/synapse/latest/modules/third_party_rules_callbacks.html#on_create_room). +as an example). Alternately, modules can also implement [`on_create_room`](https://element-hq.github.io/synapse/latest/modules/third_party_rules_callbacks.html#on_create_room). # Upgrading to v1.52.0 @@ -1117,14 +1117,14 @@ The following admin APIs were deprecated in [Synapse 1.34](https://github.com/ma - `POST /_synapse/admin/v1/<room_id>/delete` Any scripts still using the above APIs should be converted to use the -[Delete Room API](https://matrix-org.github.io/synapse/latest/admin_api/rooms.html#delete-room-api). +[Delete Room API](https://element-hq.github.io/synapse/latest/admin_api/rooms.html#delete-room-api). ## Deprecation of the `user_may_create_room_with_invites` module callback The `user_may_create_room_with_invites` is deprecated and will be removed in a future version of Synapse. Modules implementing this callback can instead implement -[`user_may_invite`](https://matrix-org.github.io/synapse/latest/modules/spam_checker_callbacks.html#user_may_invite) -and use the [`get_room_state`](https://github.com/matrix-org/synapse/blob/872f23b95fa980a61b0866c1475e84491991fa20/synapse/module_api/__init__.py#L869-L876) +[`user_may_invite`](https://element-hq.github.io/synapse/latest/modules/spam_checker_callbacks.html#user_may_invite) +and use the [`get_room_state`](https://github.com/element-hq/synapse/blob/872f23b95fa980a61b0866c1475e84491991fa20/synapse/module_api/__init__.py#L869-L876) module API method to infer whether the invite is happening in the context of creating a room. @@ -1150,7 +1150,7 @@ deleted from any configured storage providers to reclaim space. ## The spaces summary APIs can now be handled by workers -The [available worker applications documentation](https://matrix-org.github.io/synapse/latest/workers.html#available-worker-applications) +The [available worker applications documentation](https://element-hq.github.io/synapse/latest/workers.html#available-worker-applications) has been updated to reflect that calls to the `/spaces`, `/hierarchy`, and `/summary` endpoints can now be routed to workers for both client API and federation requests. @@ -1166,13 +1166,13 @@ The following admin APIs were deprecated in [Synapse 1.25](https://github.com/ma - `POST /_synapse/admin/v1/shutdown_room/<room_id>` Any scripts still using the above APIs should be converted to use the -[Delete Room API](https://matrix-org.github.io/synapse/latest/admin_api/rooms.html#delete-room-api). +[Delete Room API](https://element-hq.github.io/synapse/latest/admin_api/rooms.html#delete-room-api). ## User-interactive authentication fallback templates can now display errors This may affect you if you make use of custom HTML templates for the -[reCAPTCHA (`synapse/res/templates/recaptcha.html`)](https://github.com/matrix-org/synapse/tree/develop/synapse/res/templates/recaptcha.html) or -[terms (`synapse/res/templates/terms.html`)](https://github.com/matrix-org/synapse/tree/develop/synapse/res/templates/terms.html) fallback pages. +[reCAPTCHA (`synapse/res/templates/recaptcha.html`)](https://github.com/element-hq/synapse/tree/develop/synapse/res/templates/recaptcha.html) or +[terms (`synapse/res/templates/terms.html`)](https://github.com/element-hq/synapse/tree/develop/synapse/res/templates/terms.html) fallback pages. The template is now provided an `error` variable if the authentication process failed. See the default templates linked above for an example. @@ -1214,14 +1214,14 @@ The `template_dir` settings in the `sso`, `account_validity` and `email` section configuration file are now deprecated. Server admins should use the new `templates.custom_template_directory` setting in the configuration file and use one single custom template directory for all aforementioned features. Template file names remain -unchanged. See [the related documentation](https://matrix-org.github.io/synapse/latest/templates.html) +unchanged. See [the related documentation](https://element-hq.github.io/synapse/latest/templates.html) for more information and examples. We plan to remove support for these settings in October 2021. ## `/_synapse/admin/v1/users/{userId}/media` must be handled by media workers -The [media repository worker documentation](https://matrix-org.github.io/synapse/latest/workers.html#synapseappmedia_repository) +The [media repository worker documentation](https://element-hq.github.io/synapse/latest/workers.html#synapseappmedia_repository) has been updated to reflect that calls to `/_synapse/admin/v1/users/{userId}/media` must now be handled by media repository workers. This is due to the new `DELETE` method of this endpoint modifying the media store. @@ -1624,7 +1624,7 @@ lock down external access to the Admin API endpoints. This release deprecates use of the `structured: true` logging configuration for structured logging. If your logging configuration contains `structured: true` then it should be modified based on the -[structured logging documentation](https://matrix-org.github.io/synapse/v1.56/structured_logging.html#upgrading-from-legacy-structured-logging-configuration). +[structured logging documentation](https://element-hq.github.io/synapse/v1.56/structured_logging.html#upgrading-from-legacy-structured-logging-configuration). The `structured` and `drains` logging options are now deprecated and should be replaced by standard logging configuration of `handlers` and @@ -1671,7 +1671,7 @@ update your reverse proxy configuration to reflect this change. ## New HTML templates A new HTML template, -[password_reset_confirmation.html](https://github.com/matrix-org/synapse/blob/develop/synapse/res/templates/password_reset_confirmation.html), +[password_reset_confirmation.html](https://github.com/element-hq/synapse/blob/develop/synapse/res/templates/password_reset_confirmation.html), has been added to the `synapse/res/templates` directory. If you are using a custom template directory, you may want to copy the template over and modify it. @@ -1724,7 +1724,7 @@ updated. When setting up worker processes, we now recommend the use of a Redis server for replication. **The old direct TCP connection method is deprecated and will be removed in a future release.** See -the [worker documentation](https://matrix-org.github.io/synapse/v1.66/workers.html) for more details. +the [worker documentation](https://element-hq.github.io/synapse/v1.66/workers.html) for more details. # Upgrading to v1.14.0 @@ -1770,7 +1770,7 @@ New templates (`sso_auth_confirm.html`, `sso_auth_success.html`, and is configured to use SSO and a custom `sso_redirect_confirm_template_dir` configuration then these templates will need to be copied from -[`synapse/res/templates`](https://github.com/matrix-org/synapse/tree/develop/synapse/res/templates) into that directory. +[`synapse/res/templates`](https://github.com/element-hq/synapse/tree/develop/synapse/res/templates) into that directory. ## Synapse SSO Plugins Method Deprecation @@ -1923,7 +1923,7 @@ included. Synapse will expect these files to exist inside the configured template directory, and **will fail to start** if they are absent. To view the default templates, see -[synapse/res/templates](https://github.com/matrix-org/synapse/tree/master/synapse/res/templates). +[synapse/res/templates](https://github.com/element-hq/synapse/tree/master/synapse/res/templates). ## 3pid verification changes diff --git a/docs/usage/administration/monitoring/reporting_homeserver_usage_statistics.md b/docs/usage/administration/monitoring/reporting_homeserver_usage_statistics.md index 60b758e33b..4c0dbb5acd 100644 --- a/docs/usage/administration/monitoring/reporting_homeserver_usage_statistics.md +++ b/docs/usage/administration/monitoring/reporting_homeserver_usage_statistics.md @@ -74,3 +74,4 @@ consider using one of the following known implementations: * [Matrix.org's Panopticon](https://github.com/matrix-org/panopticon) * [Famedly's Barad-dûr](https://gitlab.com/famedly/infra/services/barad-dur) +* [Synapse Usage Exporter](https://github.com/loelkes/synapse-usage-exporter) for Prometheus diff --git a/docs/usage/administration/request_log.md b/docs/usage/administration/request_log.md index 292e3449f1..6154108934 100644 --- a/docs/usage/administration/request_log.md +++ b/docs/usage/administration/request_log.md @@ -1,6 +1,6 @@ # Request log format -HTTP request logs are written by synapse (see [`synapse/http/site.py`](https://github.com/matrix-org/synapse/tree/develop/synapse/http/site.py) for details). +HTTP request logs are written by synapse (see [`synapse/http/site.py`](https://github.com/element-hq/synapse/tree/develop/synapse/http/site.py) for details). See the following for how to decode the dense data available from the default logging configuration. @@ -19,7 +19,7 @@ See the following for how to decode the dense data available from the default lo | EEEE | Request Identifier (This identifier is shared by related log lines)| | FFFF | Source IP (Or X-Forwarded-For if enabled) | | GGGG | Server Port | -| HHHH | Federated Server or Local User making request (blank if unauthenticated or not supplied).<br/>If this is of the form `@aaa:example.com|@bbb:example.com`, then that means that `@aaa:example.com` is authenticated but they are controlling `@bbb:example.com`, e.g. if `aaa` is controlling `bbb` [via the admin API](https://matrix-org.github.io/synapse/latest/admin_api/user_admin_api.html#login-as-a-user). | +| HHHH | Federated Server or Local User making request (blank if unauthenticated or not supplied).<br/>If this is of the form `@aaa:example.com|@bbb:example.com`, then that means that `@aaa:example.com` is authenticated but they are controlling `@bbb:example.com`, e.g. if `aaa` is controlling `bbb` [via the admin API](https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#login-as-a-user). | | IIII | Total Time to process the request | | JJJJ | Time to send response over network once generated (this may be negative if the socket is closed before the response is generated)| | KKKK | Userland CPU time | diff --git a/docs/usage/administration/understanding_synapse_through_grafana_graphs.md b/docs/usage/administration/understanding_synapse_through_grafana_graphs.md index c365cc3923..a2cb9f5386 100644 --- a/docs/usage/administration/understanding_synapse_through_grafana_graphs.md +++ b/docs/usage/administration/understanding_synapse_through_grafana_graphs.md @@ -1,14 +1,14 @@ ## Understanding Synapse through Grafana graphs -It is possible to monitor much of the internal state of Synapse using [Prometheus](https://prometheus.io) -metrics and [Grafana](https://grafana.com/). -A guide for configuring Synapse to provide metrics is available [here](../../metrics-howto.md) -and information on setting up Grafana is [here](https://github.com/matrix-org/synapse/tree/master/contrib/grafana). +It is possible to monitor much of the internal state of Synapse using [Prometheus](https://prometheus.io) +metrics and [Grafana](https://grafana.com/). +A guide for configuring Synapse to provide metrics is available [here](../../metrics-howto.md) +and information on setting up Grafana is [here](https://github.com/element-hq/synapse/tree/master/contrib/grafana). In this setup, Prometheus will periodically scrape the information Synapse provides and store a record of it over time. Grafana is then used as an interface to query and present this information through a series of pretty graphs. -Once you have grafana set up, and assuming you're using [our grafana dashboard template](https://github.com/matrix-org/synapse/blob/master/contrib/grafana/synapse.json), look for the following graphs when debugging a slow/overloaded Synapse: +Once you have grafana set up, and assuming you're using [our grafana dashboard template](https://github.com/element-hq/synapse/blob/master/contrib/grafana/synapse.json), look for the following graphs when debugging a slow/overloaded Synapse: ## Message Event Send Time @@ -57,7 +57,7 @@ Cross-referencing this with the Eviction Rate graph, which shows that entries ar  -we should probably consider raising the size of that cache by raising its cache factor (a multiplier value for the size of an individual cache). Information on doing so is available [here](https://github.com/matrix-org/synapse/blob/ee421e524478c1ad8d43741c27379499c2f6135c/docs/sample_config.yaml#L608-L642) (note that the configuration of individual cache factors through the configuration file is available in Synapse v1.14.0+, whereas doing so through environment variables has been supported for a very long time). Note that this will increase Synapse's overall memory usage. +we should probably consider raising the size of that cache by raising its cache factor (a multiplier value for the size of an individual cache). Information on doing so is available [here](https://github.com/element-hq/synapse/blob/ee421e524478c1ad8d43741c27379499c2f6135c/docs/sample_config.yaml#L608-L642) (note that the configuration of individual cache factors through the configuration file is available in Synapse v1.14.0+, whereas doing so through environment variables has been supported for a very long time). Note that this will increase Synapse's overall memory usage. ## Forward Extremities @@ -71,14 +71,13 @@ If a room has >10 forward extremities, it's worth checking which room is the cul  -Large spikes in garbage collection times (bigger than shown here, I'm talking in the -multiple seconds range), can cause lots of problems in Synapse performance. It's more an +Large spikes in garbage collection times (bigger than shown here, I'm talking in the +multiple seconds range), can cause lots of problems in Synapse performance. It's more an indicator of problems, and a symptom of other problems though, so check other graphs for what might be causing it. ## Final Thoughts -If you're still having performance problems with your Synapse instance and you've +If you're still having performance problems with your Synapse instance and you've tried everything you can, it may just be a lack of system resources. Consider adding -more CPU and RAM, and make use of [worker mode](../../workers.md) +more CPU and RAM, and make use of [worker mode](../../workers.md) to make use of multiple CPU cores / multiple machines for your homeserver. - diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md index 425ec75542..8723b9a3fe 100644 --- a/docs/usage/configuration/config_documentation.md +++ b/docs/usage/configuration/config_documentation.md @@ -495,10 +495,10 @@ Unix socket support (_Added in Synapse 1.89.0_): * **Note**: The use of both `path` and `port` options for the same `listener` is not compatible. * The `x_forwarded` option defaults to true when using Unix sockets and can be omitted. - * Other options that would not make sense to use with a UNIX socket, such as + * Other options that would not make sense to use with a UNIX socket, such as `bind_addresses` and `tls` will be ignored and can be removed. * `mode`: The file permissions to set on the UNIX socket. Defaults to `666` -* **Note:** Must be set as `type: http` (does not support `metrics` and `manhole`). +* **Note:** Must be set as `type: http` (does not support `metrics` and `manhole`). Also make sure that `metrics` is not included in `resources` -> `names` @@ -549,7 +549,7 @@ listeners: # that unwraps TLS. # # If you plan to use a reverse proxy, please see - # https://matrix-org.github.io/synapse/latest/reverse_proxy.html. + # https://element-hq.github.io/synapse/latest/reverse_proxy.html. # - port: 8008 tls: false @@ -581,7 +581,7 @@ listeners: # conflicts, and providing enhanced security through system file permissions. # # Note that x_forwarded will default to true, when using a UNIX socket. Please see - # https://matrix-org.github.io/synapse/latest/reverse_proxy.html. + # https://element-hq.github.io/synapse/latest/reverse_proxy.html. # - path: /run/synapse/main_public.sock type: http @@ -680,6 +680,11 @@ This setting has the following sub-options: has missed. Disabled by default. * `notif_for_new_users`: Set to false to disable automatic subscription to email notifications for new users. Enabled by default. +* `notif_delay_before_mail`: The time to wait before emailing about a notification. + This gives the user a chance to view the message via push or an open client. + Defaults to 10 minutes. + + _New in Synapse 1.99.0._ * `client_base_url`: Custom URL for client links within the email notifications. By default links will be based on "https://matrix.to". (This setting used to be called `riot_base_url`; the old name is still supported for backwards-compatibility but is now deprecated.) @@ -1411,7 +1416,7 @@ kill -HUP [PID_OF_SYNAPSE_PROCESS] If you are running multiple workers, you must individually update the worker config file and send this signal to each worker process. -If you're using the [example systemd service](https://github.com/matrix-org/synapse/blob/develop/contrib/systemd/matrix-synapse.service) +If you're using the [example systemd service](https://github.com/element-hq/synapse/blob/develop/contrib/systemd/matrix-synapse.service) file in Synapse's `contrib` directory, you can send a `SIGHUP` signal by using `systemctl reload matrix-synapse`. @@ -2675,7 +2680,7 @@ Example configuration: refreshable_access_token_lifetime: 10m ``` --- -### `refresh_token_lifetime: 24h` +### `refresh_token_lifetime` Time that a refresh token remains valid for (provided that it is not exchanged for another one first). @@ -2774,6 +2779,10 @@ enable_metrics: true Use this option to enable sentry integration. Provide the DSN assigned to you by sentry with the `dsn` setting. + An optional `environment` field can be used to specify an environment. This allows + for log maintenance based on different environments, ensuring better organization + and analysis.. + NOTE: While attempts are made to ensure that the logs don't contain any sensitive information, this cannot be guaranteed. By enabling this option the sentry server may therefore receive sensitive @@ -2783,6 +2792,7 @@ through insecure notification channels if so configured. Example configuration: ```yaml sentry: + environment: "production" dsn: "..." ``` --- @@ -2932,7 +2942,7 @@ access tokens via a query parameter. Example configuration: ```yaml -use_appservice_legacy_authorization: true +use_appservice_legacy_authorization: true ``` --- @@ -3613,7 +3623,7 @@ This setting has the following sub-options: * `enabled`: Defaults to true. Set to false to disable password authentication. Set to `only_for_reauth` to allow users with existing passwords to use them - to log in and reauthenticate, whilst preventing new users from setting passwords. + to reauthenticate (not log in), whilst preventing new users from setting passwords. * `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. @@ -3832,16 +3842,22 @@ Sub-options for this setting include: * `system_mxid_display_name`: set the display name of the "notices" user * `system_mxid_avatar_url`: set the avatar for the "notices" user * `room_name`: set the room name of the server notices room +* `room_avatar_url`: optional string. The room avatar to use for server notice rooms. If set to the empty string `""`, notice rooms will not be given an avatar. Defaults to the empty string. _Added in Synapse 1.99.0._ +* `room_topic`: optional string. The topic to use for server notice rooms. If set to the empty string `""`, notice rooms will not be given a topic. Defaults to the empty string. _Added in Synapse 1.99.0._ * `auto_join`: boolean. If true, the user will be automatically joined to the room instead of being invited. Defaults to false. _Added in Synapse 1.98.0._ +Note that the name, topic and avatar of existing server notice rooms will only be updated when a new notice event is sent. + Example configuration: ```yaml server_notices: system_mxid_localpart: notices system_mxid_display_name: "Server Notices" - system_mxid_avatar_url: "mxc://server.com/oumMVlgDnLYFaPVkExemNVVZ" + system_mxid_avatar_url: "mxc://example.com/oumMVlgDnLYFaPVkExemNVVZ" room_name: "Server Notices" + room_avatar_url: "mxc://example.com/oumMVlgDnLYFaPVkExemNVVZ" + room_topic: "Room used by your server admin to notice you of important information" auto_join: true ``` --- @@ -3865,7 +3881,7 @@ This setting is an optional list of 0 or more rules. By default, no list is provided, meaning that all alias creations are permitted. Otherwise, requests to create aliases are matched against each rule in order. -The first rule that matches decides if the request is allowed or denied. If no +The first rule that matches decides if the request is allowed or denied. If no rule matches, the request is denied. In particular, this means that configuring an empty list of rules will deny every alias creation request. @@ -3877,7 +3893,7 @@ Each rule is a YAML object containing four fields, each of which is an optional * `action`: either `allow` or `deny`. What to do with the request if the rule matches. Defaults to `allow`. Each of the glob patterns is optional, defaulting to `*` ("match anything"). -Note that the patterns match against fully qualified IDs, e.g. against +Note that the patterns match against fully qualified IDs, e.g. against `@alice:example.com`, `#room:example.com` and `!abcdefghijk:example.com` instead of `alice`, `room` and `abcedgghijk`. @@ -3914,7 +3930,7 @@ alias_creation_rules: alias_creation_rules: - user_id: "@bad_user:example.com" action: deny - + - action: allow ``` @@ -3992,7 +4008,7 @@ room_list_publication_rules: room_list_publication_rules: - user_id: "@bad_user:example.com" action: deny - + - action: allow ``` @@ -4408,7 +4424,7 @@ must be declared, in the same way as the [`listeners` option](#listeners) in the shared config. Workers declared in [`stream_writers`](#stream_writers) and [`instance_map`](#instance_map) - will need to include a `replication` listener here, in order to accept internal HTTP + will need to include a `replication` listener here, in order to accept internal HTTP requests from other workers. Example configuration: diff --git a/docs/website_files/theme/index.hbs b/docs/website_files/theme/index.hbs index b169323a43..9cf7521e80 100644 --- a/docs/website_files/theme/index.hbs +++ b/docs/website_files/theme/index.hbs @@ -142,7 +142,7 @@ <!-- Versions will be added dynamically in version-picker.js --> </ul> </div> - </div> + </div> </div> <h1 class="menu-title">{{ book_title }}</h1> diff --git a/docs/website_files/version.js b/docs/website_files/version.js index 8048916372..73f7e67f6a 100644 --- a/docs/website_files/version.js +++ b/docs/website_files/version.js @@ -1 +1 @@ -window.SYNAPSE_VERSION = 'v1.98'; +window.SYNAPSE_VERSION = "latest"; diff --git a/docs/welcome_and_overview.md b/docs/welcome_and_overview.md index 451759f06e..ae5d0f5d90 100644 --- a/docs/welcome_and_overview.md +++ b/docs/welcome_and_overview.md @@ -1,8 +1,7 @@ # Introduction -Welcome to the documentation repository for Synapse, a -[Matrix](https://matrix.org) homeserver implementation developed by the matrix.org core -team. +Welcome to the documentation repository for Synapse, a +[Matrix](https://matrix.org) homeserver implementation developed by Element. ## Installing and using Synapse @@ -37,17 +36,17 @@ following documentation: * Read the [Contributing Guide](development/contributing_guide.md). It is meant to walk new contributors through the process of developing and submitting a change to the Synapse codebase (which is [hosted on - GitHub](https://github.com/matrix-org/synapse)). + GitHub](https://github.com/element-hq/synapse)). * Set up your [development environment](development/contributing_guide.md#2-what-do-i-need), then learn how to [lint](development/contributing_guide.md#run-the-linters) and [test](development/contributing_guide.md#8-test-test-test) your code. -* Look at [the issue tracker](https://github.com/matrix-org/synapse/issues) for +* Look at [the issue tracker](https://github.com/element-hq/synapse/issues) for bugs to fix or features to add. If you're new, it may be best to start with those labeled [good first - issue](https://github.com/matrix-org/synapse/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22). + issue](https://github.com/element-hq/synapse/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22). * Understand [how Synapse is built](development/internal_documentation/index.html), how to [migrate @@ -59,18 +58,7 @@ following documentation: do so! * And finally, contribute to this documentation! The source for which is - [located here](https://github.com/matrix-org/synapse/tree/develop/docs). - -## Donating to Synapse development - -Want to help keep Synapse going but don't know how to code? Synapse is a -[Matrix.org Foundation](https://matrix.org) project. Consider becoming a -supporter on [Liberapay](https://liberapay.com/matrixdotorg), -[Patreon](https://patreon.com/matrixdotorg) or through -[PayPal](https://paypal.me/matrixdotorg) via a one-time donation. - -If you are an organisation or enterprise and would like to sponsor development, -reach out to us over email at: support (at) matrix.org + [located here](https://github.com/element-hq/synapse/tree/develop/docs). ## Reporting a security vulnerability diff --git a/docs/workers.md b/docs/workers.md index dc76b073de..ab6b8d47af 100644 --- a/docs/workers.md +++ b/docs/workers.md @@ -62,8 +62,8 @@ pip install "matrix-synapse[redis]" Note that these dependencies are included when synapse is installed with `pip install matrix-synapse[all]`. They are also included in the debian packages from -`matrix.org` and in the docker images at -https://hub.docker.com/r/matrixdotorg/synapse/. +`packages.matrix.org` and in the docker images at +https://hub.docker.com/r/ectorim/synapse/. To make effective use of the workers, you will need to configure an HTTP reverse-proxy such as nginx or haproxy, which will direct incoming requests to @@ -94,7 +94,7 @@ file suitable for use with workers: for the main process * Secondly, you need to enable [redis-based replication](usage/configuration/config_documentation.md#redis) -* You will need to add an [`instance_map`](usage/configuration/config_documentation.md#instance_map) +* You will need to add an [`instance_map`](usage/configuration/config_documentation.md#instance_map) with the `main` process defined, as well as the relevant connection information from it's HTTP `replication` listener (defined in step 1 above). * Note that the `host` defined is the address the worker needs to look for the `main` @@ -432,7 +432,7 @@ To enable this, the worker must have: * An [HTTP `replication` listener](usage/configuration/config_documentation.md#listeners) configured, * Have a [`worker_name`](usage/configuration/config_documentation.md#worker_name) and be listed in the [`instance_map`](usage/configuration/config_documentation.md#instance_map) -config. +config. * Have the main process declared on the [`instance_map`](usage/configuration/config_documentation.md#instance_map) as well. Note: The same worker can handle multiple streams, but unless otherwise documented, @@ -629,7 +629,7 @@ worker application type. You can designate generic worker to sending push notifications to a [push gateway](https://spec.matrix.org/v1.5/push-gateway-api/) such as -[sygnal](https://github.com/matrix-org/sygnal) and email. +[sygnal](https://github.com/vector-im/sygnal) and email. This will stop the main process sending push notifications. |