You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -13,33 +14,55 @@ Appservice mode can be used together with the regular [Draupnir bot](configuring
13
14
14
15
## Draupnir Appservice mode compared to Draupnir bot mode
15
16
16
-
The administrative functions for managing the appservice are alpha quality and very limited. However, the experience of using an appservice-provisioned Draupnir is on par with the experience of using Draupnir from bot mode except in the case of avatar customisation as described later on in this document.
17
+
The administrative functions for managing the appservice are alpha quality and very limited. However, the experience of using an appservice-provisioned Draupnir is on par with the experience of using Draupnir from bot mode.
17
18
18
-
Draupnir for all is the way to go if you need more than 1 Draupnir instance, but you don't need access to Synapse Admin features as they are not accessible through Draupnir for All (Even though the commands do show up in help).
19
+
Draupnir for all is the way to go if you need more than 1 Draupnir instance, but you don't need access to Synapse Admin features as they are not accessible through Draupnir for All.
19
20
20
21
Draupnir for all in the playbook is rate-limit-exempt automatically as its appservice configuration file does not specify any rate limits.
21
22
22
-
Normal Draupnir does come with the benefit of access to Synapse Admin features. You are also able to more easily customise your normal Draupnir than D4A as D4A even on the branch with the Avatar command (To be Upstreamed to Mainline Draupnir) that command is clunky as it requires the use of things like Element Web devtools. In normal Draupnir this is a quick operation where you login to Draupnir with a normal client and set Avatar and Display name normally.
23
+
Normal Draupnir does come with the benefit of access to Synapse Admin features. You are also able to more easily customise your normal Draupnir than D4A as the avatar command is clunky as it requires the use of things like Element Web devtools. In normal Draupnir this can be done while logged in to the Draupnir account with a normal client and set Avatar and Display name normally.
23
24
24
-
Draupnir for all does not support external tooling like [MRU](https://mru.rory.gay) as it can't access Draupnir's user account.
25
+
Draupnir for all only has limited support for external tooling like [MRU](https://mru.rory.gay) as it can't access Draupnir's user account.
25
26
26
27
## Prerequisites
27
28
28
-
### Create a main management room
29
+
### Prerequisites for Zero Touch Deployment (Recomended)
29
30
30
-
The playbook does not create a management room for your Main Draupnir. You **need to create the room manually** before setting up the bot.
31
+
Zero Touch Deployment of Draupnir Appservice Mode (Draupnir for all) requires as of Draupnir 3.1.0 that you supply Draupnir the following:
32
+
33
+
- MXID of the the first person who gets invited to the admin room the bot creates for you.
34
+
35
+
That is all. The appservice manages everything on its own after you provide it a MXID to invite.
36
+
37
+
If proceeding with Zero Touch Deployment proceed to [Adjusting the playbook configuration](#adjusting-the-playbook-configuration)
38
+
39
+
### Create a admin room (Optional)
40
+
41
+
The playbook does not create a admin room for your Admin Draupnir but the appservice it self can do this. You **can create room manually** before setting up the bot.
31
42
32
43
Note that the room must be unencrypted.
33
44
34
-
The management room has to be given an alias, and your bot has to be invited to the room.
45
+
The admin room has to be given an alias, and your bot has to be invited to the room.
35
46
36
-
This management room is used to control who has access to your D4A deployment. The room stores this data inside of the control room state so your bot must have sufficient powerlevel to send custom state events. This is default 50 or moderator as Element clients call this powerlevel.
47
+
This admin room is used to control who has access to your D4A deployment. The room stores this data inside of the control room state so your bot must have sufficient powerlevel to send custom state events. This is default 50 or moderator as Element clients call this powerlevel.
37
48
38
49
> [!WARNING]
39
50
> Anyone in this room can control the bot so it is important that you only invite trusted users to this room.
40
51
41
52
## Adjusting the playbook configuration
42
53
54
+
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `INITIAL_MANAGER_MXID_HERE`.
If you made it through all the steps above and your main control room was joined by a user called `@draupnir-main:example.com` you have successfully installed Draupnir for All and can now start using it.
107
130
108
-
The installation of Draupnir for all in this playbook is very much Alpha quality. Usage-wise, Draupnir for all is almost identical to Draupnir bot mode.
131
+
If using Zero Touch Deployment the flow will be reversed and the success signal is the initial manager account being invited to the admin room.
132
+
133
+
The installation of Draupnir for all in Usage-wise, Draupnir for all is almost identical to Draupnir bot mode.
134
+
135
+
Draupnir for all installation via this playbook is very much Alpha quality. Usage-wise, Draupnir for all is almost identical to Draupnir bot mode, except that protections requiring homeserver admin access are not available, and the config file is shared between all bots so legacy protections like wordlist share a single global config.
109
136
110
137
### Granting Users the ability to use D4A
111
138
112
139
Draupnir for all includes several security measures like that it only allows users that are on its allow list to ask for a bot. To add a user to this list we have 2 primary options. Using the chat to tell Draupnir to do this for us or if you want to automatically do it by sending `m.policy.rule.user` events that target the subject you want to allow provisioning for with the `org.matrix.mjolnir.allow` recommendation. Using the chat is recommended.
113
140
114
-
The bot requires a powerlevel of 50 in the management room to control who is allowed to use the bot. The bot does currently not say anything if this is true or false. (This is considered a bug and is documented in issue [#297](https://github.com/the-draupnir-project/Draupnir/issues/297))
141
+
The bot requires a powerlevel of 50 in the management room to control who is allowed to use the bot. The bot does currently not say anything if this is true or false. (This is considered a bug and is documented in issue [#297](https://github.com/the-draupnir-project/Draupnir/issues/297)) This issue is mittigated in large part by Zero Touch Deployment workflows that got introduced in Draupnir 3.1.0
115
142
116
-
To allow users or whole homeservers you type /plain !admin allow `target` and target can be either a MXID or a wildcard like `@*:example.com` to allow all users on example.com to register. We use /plain to force the client to not attempt to mess with this command as it can break Wildcard commands especially.
143
+
To allow users or whole homeservers you type /plain !admin allow `target` and target can be either a MXID or a wildcard like `@*:example.com` to allow all users on example.com to provision a bot. We use /plain to force the client to not attempt to mess with this command as it can break Wildcard commands especially.
117
144
118
145
### How to provision a D4A once you are allowed to
119
146
120
-
To provision a D4A, you need to start a chat with `@draupnir-main:example.com`. The bot will reject this invite and you will shortly get invited to the Draupnir control room for your newly provisioned Draupnir. From here its just a normal Draupnir experience.
147
+
Once someone is allowed to provision a bot. Simply provision them one with `!admin provision MXID`.
148
+
Self Service Provisioning is disabled as a security feature due to it being bugged. Force Provisioning bypasses this disabled status.
149
+
150
+
Please note that the reason you should always make sure there is an allow entry matching whoever is provisioned is that when
151
+
self service gets fixed the bot of anyone who is not allowed to provision a bot will refuse to start.
121
152
122
153
Congratulations if you made it all the way here because you now have a fully working Draupnir for all deployment.
@@ -19,7 +20,17 @@ If your migrating from [Mjolnir](configuring-playbook-bot-mjolnir.md), skip to [
19
20
20
21
## Prerequisites
21
22
22
-
### Create a management room
23
+
### Prerequisites for Zero Touch Deployment (Recomended)
24
+
25
+
Zero Touch Deployment of Draupnir bot mode requires as of Draupnir 3.1.0 that you supply Draupnir the following:
26
+
27
+
- MXID of the the first person who gets invited to the management room the bot creates for you.
28
+
- Permanent access token for authentication. Instructions for obtaining one can be found at [obtain an access token via curl](obtaining-access-tokens.md#obtain-an-access-token-via-curl)
29
+
- User account for Draupnir
30
+
31
+
Zero Touch Deployment is the officially preferred installation method for new deployments of Draupnir as of 3.1.0
32
+
33
+
### Create a management room (optional)
23
34
24
35
Using your own account, create a new invite only room that you will use to manage the bot. This is the room where you will see the status of the bot and where you will send commands to the bot, such as the command to ban a user from another room.
25
36
@@ -28,6 +39,8 @@ Using your own account, create a new invite only room that you will use to manag
28
39
29
40
It is possible to make the management room encrypted (E2EE). If doing so, then you need to enable the native E2EE support (see [below](#native-e2ee-support)).
30
41
42
+
E2EE Support for the management room is mutually exclusive with Zero Touch Deployment of Draupnir.
43
+
31
44
Once you have created the room you need to copy the room ID so you can specify it on your `inventory/host_vars/matrix.example.com/vars.yml` file. In Element Web you can check the ID by going to the room's settings and clicking "Advanced". The room ID will look something like `!qporfwt:example.com`.
To enable the bot, add the following configuration to your `vars.yml` file. Make sure to replace `MANAGEMENT_ROOM_ID_HERE` with the one of the room which you have created earlier.
79
+
To enable the bot, add the following configuration to your `vars.yml` file. Make sure to replace `INITIAL_MANAGER_MXID_HERE` with the MXID for whoever is to be invited to the management room first.
Then, invite the bot (`@bot.draupnir:example.com`) to its management room which you have created earlier.
104
133
134
+
### Creating user account for the bot
135
+
136
+
Since Zero Touch Deployment is not validated with login native we will create the user account manually.
137
+
138
+
Refer to [registering users](registering-users.md) for documentation on how to configure the user account.
139
+
105
140
### Make sure the account is free from rate limiting (optional, recommended)
106
141
107
142
If your homeserver's implementation is Synapse, you will need to prevent it from rate limiting the bot's account. **This is a highly recommended step. If you do not configure it, Draupnir performance will be degraded.**
@@ -115,6 +150,7 @@ The APIs can also be accessed via [Ketesa](https://github.com/etkecc/ketesa), a
115
150
#### Add the configuration
116
151
117
152
To expose the APIs publicly, add the following configuration to your `vars.yml` file:
These protections need to be manually activated and consulting the [enabling protections](#enabling-built-in-protections) guide can be helpful or consulting upstream documentation.
169
205
170
-
<!--
171
-
NOTE: this is unsupported by the playbook due to the admin API being inaccessible from containers currently.
172
-
173
206
The other method polls an Synapse Admin API endpoint, hence it is available only if using Synapse and if the Draupnir user is an admin (see [above](#register-the-bot-account)). To enable it, set `pollReports: true` on `vars.yml` file as below.
0 commit comments