tuwunel_core/config/admin.rs
1//! Configures server administration and command output.
2//!
3//! Startup and signal commands share administration policy with interactive
4//! commands. Room settings and the durable server-user identity govern
5//! administrative communication.
6
7use serde::Deserialize;
8use tuwunel_macros::config_example_generator;
9
10use super::{OwnedRoomOrAliasId, ServerUserLocalpart, true_fn};
11
12/// Server administration
13///
14/// Controls how admin commands run and how their output is posted. Admins
15/// are the accounts joined to the admin room, `#admins:<server_name>` (see
16/// `[global.admin.room]`), where a text message starting with `!admin` or
17/// the server user's ID (`@conduit:<server_name>` by default) runs a
18/// command. Commands can also run from the terminal console (`--console`),
19/// at startup (`execute` or `--execute`), or on `SIGUSR2` (`signal_execute`).
20///
21/// Tips:
22/// - On a new server the first account to register becomes an admin while
23/// `registration.grant_admin_to_first_user` is on (the default). Grant more
24/// with `!admin users make-user-admin <username>`.
25/// - To regain admin access, start the server once with
26/// `--execute "users make-user-admin <username>"`, or run that command in
27/// the console. See
28/// <https://tuwunel.chat/troubleshooting.html#lost-access-to-admin-room>.
29#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
30#[derive(Clone, Debug, Deserialize)]
31#[config_example_generator(
32 filename = "tuwunel-example.toml",
33 section = "global.admin",
34 group = "true",
35 ignore = "room"
36)]
37pub struct Admin {
38 /// Allows admins to run commands outside the admin room by prefixing
39 /// messages with "\!admin" or "\\!admin".
40 ///
41 /// Follow the prefix with a normal command, as in the "#admins" room; the
42 /// reply is publicly visible in the current room and originates from the
43 /// sender. This is disabled by default because we cannot distinguish a
44 /// typed command from a forwarded message or an account bot's repost.
45 /// Message formatting can also hide a command from the admin.
46 ///
47 /// reloadable: yes
48 /// example: \\!admin debug ping puppygock.gay
49 /// legacy: admin_escape_commands
50 #[serde(default)]
51 pub escape_commands: bool,
52
53 /// Activates the admin console automatically at startup.
54 ///
55 /// The console command-line argument also enables it. Activation requires
56 /// standard input to be a terminal.
57 ///
58 /// legacy: admin_console_automatic
59 #[serde(default)]
60 pub console_automatic: bool,
61
62 #[expect(clippy::doc_link_with_quotes)]
63 /// Lists admin commands to execute at startup.
64 ///
65 /// The execute command-line argument also configures these commands and
66 /// supports shell commands and environment-variable expansion. A shell
67 /// can, for example, supply `server admin-notice tuwunel has started up at
68 /// $(date)` as the execute argument.
69 ///
70 /// example: ["debug ping puppygock.gay", "debug echo hi"]
71 ///
72 /// default: []
73 /// legacy: admin_execute
74 #[serde(default)]
75 pub execute: Vec<String>,
76
77 /// Ignores failures in startup admin commands.
78 ///
79 /// When false, a failing command supplied by the execute command-line
80 /// argument or `admin.execute` prevents startup.
81 ///
82 /// reloadable: yes
83 /// legacy: admin_execute_errors_ignore
84 #[serde(default)]
85 pub execute_errors_ignore: bool,
86
87 /// Lists admin commands to execute on SIGUSR2.
88 ///
89 /// This is like `admin.execute`, but runs when the signal arrives on
90 /// supporting platforms.
91 ///
92 /// reloadable: yes
93 /// default: []
94 /// legacy: admin_signal_execute
95 #[serde(default)]
96 pub signal_execute: Vec<String>,
97
98 /// Sets the maximum log level captured during admin commands.
99 ///
100 /// The default is info for release builds and debug for debug builds.
101 ///
102 /// reloadable: yes
103 /// default: "info"
104 /// legacy: admin_log_capture
105 #[serde(default = "default_log_capture")]
106 pub log_capture: String,
107
108 /// Sets the localpart of the server's administrative user.
109 ///
110 /// The identity becomes durable after first boot. Changing it on an
111 /// existing database is unsupported and prevents startup.
112 ///
113 /// default: "conduit"
114 /// legacy: server_user_localpart
115 #[serde(default = "default_server_user_localpart")]
116 pub server_user_localpart: ServerUserLocalpart,
117
118 /// Selects a room for user, room, and event reports instead of the admin
119 /// room.
120 ///
121 /// Accepts a room ID or alias, and the server user must be joined with
122 /// permission to post. Reports fall back to the admin room when unset,
123 /// unresolvable, or the server user is not a member.
124 ///
125 /// reloadable: yes
126 /// default: (none)
127 /// legacy: report_room
128 #[serde(default)]
129 pub report_room: Option<OwnedRoomOrAliasId>,
130
131 /// Limits message events used for an admin command's output replies.
132 ///
133 /// Output requiring more events is uploaded to the media repository and
134 /// returned as a text attachment replying to the command. With 1, output
135 /// fitting one event is a single reply and larger output becomes an
136 /// attachment. With 0, output is always an attachment regardless of size.
137 ///
138 /// reloadable: yes
139 /// default: 1
140 /// legacy: admin_output_max_events
141 #[serde(default = "default_output_max_events")]
142 pub output_max_events: usize,
143
144 /// Posts admin-command output in a thread on the command event instead of
145 /// replies.
146 ///
147 /// Output split across events by `admin.output_max_events` stays in one
148 /// thread. Attachments are also posted in that thread.
149 ///
150 /// reloadable: yes
151 /// legacy: admin_output_threads
152 #[serde(default)]
153 pub output_threads: bool,
154
155 /// Settings for admin room.
156 ///
157 /// display: section
158 #[serde(default)]
159 pub room: Room,
160}
161
162/// Admin room
163///
164/// The invite-only room whose members are the server's admins. It is created
165/// the first time the server starts with an empty database, under the alias
166/// `#admins:<server_name>`, with the server user in charge.
167/// `!admin users make-user-admin <username>` joins a local account to it.
168///
169/// Tips:
170/// - `create` and `federate` act only at that first start; changing them
171/// later neither creates nor alters the room.
172/// - The server finds the room through its `#admins:<server_name>` alias and
173/// treats it as the admin room only while the server user is joined. With
174/// `create` off, the alias removed or the server user gone from the room,
175/// there is no admin room and only the server user is an admin.
176#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
177#[derive(Clone, Debug, Deserialize)]
178#[config_example_generator(
179 filename = "tuwunel-example.toml",
180 section = "global.admin.room",
181 group = "true"
182)]
183pub struct Room {
184 /// Logs guest registrations in the admin room, which may be noisy or
185 /// unnecessary on a public server.
186 ///
187 /// reloadable: yes
188 /// legacy: log_guest_registrations
189 #[serde(default)]
190 pub log_guest_registrations: bool,
191
192 /// Sets the default tag applied to the admin room, with `m.server_notice`
193 /// providing a dedicated, easily accessed shortcut pinned at the bottom of
194 /// the room list in clients such as Element.
195 ///
196 /// reloadable: yes
197 /// default: "m.server_notice"
198 /// legacy: admin_room_tag
199 #[serde(default = "default_tag")]
200 pub tag: String,
201
202 /// Creates the admin room on first startup and should remain enabled for
203 /// users, though developers can disable it in integration tests to reduce
204 /// activity and output.
205 ///
206 /// default: true
207 /// legacy: create_admin_room
208 #[serde(default = "true_fn")]
209 pub create: bool,
210
211 /// Enables federation for the admin room.
212 ///
213 /// This cannot be changed after the room is created.
214 ///
215 /// default: true
216 /// legacy: federate_admin_room
217 #[serde(default = "true_fn")]
218 pub federate: bool,
219
220 /// Sends administrative notices to the admin room.
221 ///
222 /// These include registrations, password changes, account deactivations,
223 /// and room-directory publications. Update notices and ordinary
224 /// admin-command responses are sent regardless.
225 ///
226 /// reloadable: yes
227 /// legacy: admin_room_notices
228 #[serde(default = "true_fn")]
229 pub notices: bool,
230}
231
232impl Default for Admin {
233 fn default() -> Self {
234 Self {
235 escape_commands: Default::default(),
236 console_automatic: Default::default(),
237 execute: Default::default(),
238 execute_errors_ignore: Default::default(),
239 signal_execute: Default::default(),
240 log_capture: default_log_capture(),
241 server_user_localpart: default_server_user_localpart(),
242 report_room: Default::default(),
243 output_max_events: default_output_max_events(),
244 output_threads: Default::default(),
245 room: Room::default(),
246 }
247 }
248}
249
250impl Default for Room {
251 fn default() -> Self {
252 Self {
253 log_guest_registrations: Default::default(),
254 tag: default_tag(),
255 create: true_fn(),
256 federate: true_fn(),
257 notices: true_fn(),
258 }
259 }
260}
261
262fn default_log_capture() -> String {
263 cfg!(debug_assertions)
264 .then_some("debug")
265 .unwrap_or("info")
266 .to_owned()
267}
268
269/// Preserves the administrative identity used before it was configurable.
270///
271/// Omitting the setting keeps existing installations on their original user.
272fn default_server_user_localpart() -> ServerUserLocalpart { "conduit".into() }
273
274fn default_output_max_events() -> usize { 1 }
275
276fn default_tag() -> String { "m.server_notice".to_owned() }