Skip to main content

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() }