From 8811a41980cd9a8cd075c680741aa3909b37f491 Mon Sep 17 00:00:00 2001
From: h7x4 <h7x4@nani.wtf>
Date: Mon, 15 Dec 2025 09:00:38 +0900
Subject: [PATCH] docs: split SUID/SGID installation section into its own
 document

---
 README.md              |  1 +
 docs/installation.md   | 11 ++++-------
 docs/suid-sgid-mode.md | 17 +++++++++++++++++
 3 files changed, 22 insertions(+), 7 deletions(-)
 create mode 100644 docs/suid-sgid-mode.md

diff --git a/README.md b/README.md
index 608b799..bc167ff 100644
--- a/README.md
+++ b/README.md
@@ -30,3 +30,4 @@ This software is designed for multi-user servers, like tilde servers, university
 - [Development and testing](docs/development.md)
 - [Compatibility mode with mysql-admutils](docs/mysql-admutils-compatibility.md)
 - [Use with NixOS](docs/nixos.md)
+- [SUID/SGID mode](docs/suid-sgid-mode.md)
diff --git a/docs/installation.md b/docs/installation.md
index 8687bd7..bedb7d1 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -1,5 +1,9 @@
 # Installation and configuration
 
+This document contains instructions for the recommended way of installing and configuring muscl.
+
+Note that there are separate instructions for [installing on NixOS](nixos.md) and [installing with SUID/SGID mode](suid-sgid-mode.md).
+
 ## Installing with deb on Debian
 
 You can install muscl by adding the [PVV apt repository][pvv-apt-repository] and installing the package:
@@ -68,13 +72,6 @@ If you are running systemd older than version 254 (see `systemctl --version`), y
 LoadCredentialEncrypted=muscl_mysql_password:/etc/credstore.encrypted/muscl_mysql_password
 ```
 
-## SUID/SGID mode
-
-For backwards compatibility reasons, it is possible to run the program without a daemon by utilizing SUID/SGID.
-In order to do this, you should set either the SUID/SGID bit and preferably make the executable owned by a non-privileged user.
-If the database is running on the same machine, the user/group will need access to write and read from the database socket.
-Otherwise, the only requirement is that the user/group is able to read the config file (typically `/etc/muscl/config.toml`).
-
 ## A note on minimum version requirements
 
 The muscl server will work with older versions of systemd, but the recommended version is 254 or newer.
diff --git a/docs/suid-sgid-mode.md b/docs/suid-sgid-mode.md
new file mode 100644
index 0000000..eed1daf
--- /dev/null
+++ b/docs/suid-sgid-mode.md
@@ -0,0 +1,17 @@
+# SUID/SGID mode
+
+> [!WARNING]
+> This will be deprecated in a future release, see https://git.pvv.ntnu.no/Projects/muscl/issues/101
+>
+> We do not recommend you use this mode unless you absolutely have to. The biggest reason why `muscl` was rewritten from scratch
+> was to fix an architectural issue that easily caused vulnerabilites due to reliance on SUID/SGID. Althought the architecture now
+> is more resistant against such vulnerabilites, it is not failsafe.
+
+For backwards compatibility reasons, it is possible to run the program without a daemon by utilizing SUID/SGID.
+
+In order to do this, you should set either the SUID/SGID bit and preferably make the executable owned by a non-privileged user.
+If the database is running on the same machine, the user/group will need access to write and read from the database socket.
+Otherwise, the only requirement is that the user/group is able to read the config file (typically `/etc/muscl/config.toml`).
+
+Note that the feature flag for SUID/SGID mode is not enabled by default, and is not included in the default deb package.
+You will need to compile the program yourself with `--features suid-sgid-mode`.