mirror of
https://github.com/etkecc/synapse-admin.git
synced 2024-11-23 16:25:21 +03:00
add docs/
This commit is contained in:
Aine
parent
fb71b5ed08
commit
75b9aeea01
4 changed files with 133 additions and 105 deletions
109
README.md
109
README.md
|
|
@ -28,7 +28,6 @@
|
||||||
* [Restricting available homeserver](#restricting-available-homeserver)
|
* [Restricting available homeserver](#restricting-available-homeserver)
|
||||||
* [Protecting appservice managed users](#protecting-appservice-managed-users)
|
* [Protecting appservice managed users](#protecting-appservice-managed-users)
|
||||||
* [Adding custom menu items](#adding-custom-menu-items)
|
* [Adding custom menu items](#adding-custom-menu-items)
|
||||||
* [Providing support URL](#providing-support-url)
|
|
||||||
* [Usage](#usage)
|
* [Usage](#usage)
|
||||||
* [Supported Synapse](#supported-synapse)
|
* [Supported Synapse](#supported-synapse)
|
||||||
* [Prerequisites](#prerequisites)
|
* [Prerequisites](#prerequisites)
|
||||||
|
|
@ -157,120 +156,20 @@ That way `username` and `homeserver` fields will be pre-filled with `admin` and
|
||||||
|
|
||||||
You can restrict the homeserver(s), so that the user can no longer define it himself.
|
You can restrict the homeserver(s), so that the user can no longer define it himself.
|
||||||
|
|
||||||
Edit `config.json` to restrict either to a single homeserver:
|
[Documentation](./docs/restrict-hs.md)
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"restrictBaseUrl": "https://matrix.example.com"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
similar for `/.well-known/matrix/client`:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"cc.etke.synapse-admin": {
|
|
||||||
"restrictBaseUrl": "https://matrix.example.com"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
or to a list of homeservers:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"restrictBaseUrl": ["https://your-first-matrix-server.example.com", "https://your-second-matrix-server.example.com"]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
similar for `/.well-known/matrix/client`:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"cc.etke.synapse-admin": {
|
|
||||||
"restrictBaseUrl": ["https://your-first-matrix-server.example.com", "https://your-second-matrix-server.example.com"]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Protecting appservice managed users
|
### Protecting appservice managed users
|
||||||
|
|
||||||
To avoid accidental adjustments of appservice-managed users (e.g., puppets created by a bridge) and breaking the bridge,
|
To avoid accidental adjustments of appservice-managed users (e.g., puppets created by a bridge) and breaking the bridge,
|
||||||
you can specify the list of MXIDs (regexp) that should be prohibited from any changes, except display name and avatar.
|
you can specify the list of MXIDs (regexp) that should be prohibited from any changes, except display name and avatar.
|
||||||
|
|
||||||
Example for [mautrix-telegram](https://github.com/mautrix/telegram)
|
[Documentation](./docs/system-users.md)
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"asManagedUsers": ["^@telegram_[a-zA-Z0-9]+:example\\.com$"]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
similar for `/.well-known/matrix/client`:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"cc.etke.synapse-admin": {
|
|
||||||
"asManagedUsers": ["^@telegram_[a-zA-Z0-9]+:example\\.com$"]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Adding custom menu items
|
### Adding custom menu items
|
||||||
|
|
||||||
You can add custom menu items to the main menu by providing a `menu` array in the `config.json`.
|
You can add custom menu items to the main menu by providing a `menu` array in the config.
|
||||||
|
|
||||||
```json
|
[Documentation](./docs/custom-menu.md)
|
||||||
{
|
|
||||||
"menu": [
|
|
||||||
{
|
|
||||||
"label": "Contact support",
|
|
||||||
"icon": "SupportAgent",
|
|
||||||
"url": "https://github.com/etkecc/synapse-admin/issues"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
similar for `/.well-known/matrix/client`:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"cc.etke.synapse-admin": {
|
|
||||||
"menu": [
|
|
||||||
{
|
|
||||||
"label": "Contact support",
|
|
||||||
"icon": "SupportAgent",
|
|
||||||
"url": "https://github.com/etkecc/synapse-admin/issues"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Where `icon` is one of the [preloaded icons](./src/components/icons.ts)
|
|
||||||
|
|
||||||
### Providing support URL
|
|
||||||
|
|
||||||
**Deprecated**: use `menu` config option described above. Automatically migrated to the `menu` if the `supportURL` is present.
|
|
||||||
|
|
||||||
~~Synapse Admin provides a support link in the main menu - `Contact support`. By default, the link points to the GitHub issues page of the project. You can change this link by providing a `supportURL` in the `config.json`.~~
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"supportURL": "https://example.com/support"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
similar for `/.well-known/matrix/client`:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"cc.etke.synapse-admin": {
|
|
||||||
"supportURL": "https://example.com/support"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
|
|
|
||||||
45
docs/custom-menu.md
Normal file
45
docs/custom-menu.md
Normal file
|
|
@ -0,0 +1,45 @@
|
||||||
|
# Custom Menu Items
|
||||||
|
|
||||||
|
You can add custom menu items to the main menu (sidebar) by providing a `menu` array in the config.
|
||||||
|
This is useful for adding links to external sites or other pages in your documentation, like a support page or internal wiki.
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
The examples below contain the configuration settings to add a link to the [Synapse Admin issues](https://github.com/etke.cc/synapse-admin/issues).
|
||||||
|
|
||||||
|
Each `menu` item can contain the following fields:
|
||||||
|
|
||||||
|
* `label` (required): The text to display in the menu.
|
||||||
|
* `icon` (optional): The icon to display next to the label, one of the [../src/components/icons.ts] icons, otherwise a
|
||||||
|
default icon will be used.
|
||||||
|
* `url` (required): The URL to navigate to when the menu item is clicked.
|
||||||
|
|
||||||
|
### config.json
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"menu": [
|
||||||
|
{
|
||||||
|
"label": "Contact support",
|
||||||
|
"icon": "SupportAgent",
|
||||||
|
"url": "https://github.com/etkecc/synapse-admin/issues"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### `/.well-known/matrix/client`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"cc.etke.synapse-admin": {
|
||||||
|
"menu": [
|
||||||
|
{
|
||||||
|
"label": "Contact support",
|
||||||
|
"icon": "SupportAgent",
|
||||||
|
"url": "https://github.com/etkecc/synapse-admin/issues"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
42
docs/restrict-hs.md
Normal file
42
docs/restrict-hs.md
Normal file
|
|
@ -0,0 +1,42 @@
|
||||||
|
# Restricting available homeserver
|
||||||
|
|
||||||
|
If you want to have your Synapse Admin instance work only with specific homeserver(-s),
|
||||||
|
you can do that by setting `restrictBaseUrl` in the configuration.
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
You can do that for a single homeserver or multiple homeservers at once, as `restrictBaseUrl` accepts both a string and
|
||||||
|
an array of strings.
|
||||||
|
|
||||||
|
The examples below contain the configuration settings to restrict the Synapse Admin instance to work only with
|
||||||
|
`example.com` (with Synapse runing at `matrix.example.com`) and
|
||||||
|
`example.net` (with Synapse running at `synapse.example.net`) homeservers.
|
||||||
|
Note that the homeserver URL should be the _actual_ homeserver URL, and not the delegated one.
|
||||||
|
|
||||||
|
So, if you have a homeserver `example.com` where users have MXIDs like `@user:example.com`,
|
||||||
|
but actual Synapse is installed on `matrix.example.com` subdomain, you should use `https://matrix.example.com` in the
|
||||||
|
configuration.
|
||||||
|
|
||||||
|
### config.json
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"restrictBaseUrl": [
|
||||||
|
"https://matrix.example.com",
|
||||||
|
"https://synapse.example.net"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### `/.well-known/matrix/client`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"cc.etke.synapse-admin": {
|
||||||
|
"restrictBaseUrl": [
|
||||||
|
"https://matrix.example.com",
|
||||||
|
"https://synapse.example.net"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
42
docs/system-users.md
Normal file
42
docs/system-users.md
Normal file
|
|
@ -0,0 +1,42 @@
|
||||||
|
# System / Appservice-managed Users
|
||||||
|
|
||||||
|
Inadvertently altering system user accounts managed by appservices (such as bridges) / system (such as bots) is a common issue.
|
||||||
|
Editing, deleting, locking, or changing the passwords of these appservice-managed accounts can cause serious problems.
|
||||||
|
To prevent this, we've added a new feature that blocks these types of modifications to such accounts,
|
||||||
|
while still allowing other risk-free changes (changing display names and avatars).
|
||||||
|
By defining a list of MXID regex patterns in the new `asManagedUsers` configuration setting,
|
||||||
|
you can protect these accounts from accidental changes.
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
The examples below contain the configuration settings to mark
|
||||||
|
[Telegram bridge (mautrix-telegram)](https://github.com/mautrix/telegram),
|
||||||
|
[Slack bridge (mautrix-slack)](https://github.com/mautrix/slack),
|
||||||
|
and [Baibot](https://github.com/etkecc/baibot) users of `example.com` homeserver as appservice-managed users,
|
||||||
|
just to illustrate the options to protect both specific MXIDs (as in the Baibot example) and all puppets of a bridge (as in the Telegram and Slack examples).
|
||||||
|
|
||||||
|
### config.json
|
||||||
|
|
||||||
|
```json
|
||||||
|
"asManagedUsers": [
|
||||||
|
"^@baibot:example\\.com$",
|
||||||
|
"^@slackbot:example\\.com$",
|
||||||
|
"^@slack_[a-zA-Z0-9\\-]+:example\\.com$",
|
||||||
|
"^@telegrambot:example\\.com$",
|
||||||
|
"^@telegram_[a-zA-Z0-9]+:example\\.com$"
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
### `/.well-known/matrix/client`
|
||||||
|
|
||||||
|
```json
|
||||||
|
"cc.etke.synapse-admin": {
|
||||||
|
"asManagedUsers": [
|
||||||
|
"^@baibot:example\\.com$",
|
||||||
|
"^@slackbot:example\\.com$",
|
||||||
|
"^@slack_[a-zA-Z0-9\\-]+:example\\.com$",
|
||||||
|
"^@telegrambot:example\\.com$",
|
||||||
|
"^@telegram_[a-zA-Z0-9]+:example\\.com$"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
Loading…
Reference in a new issue