Decommissioning a Matrix server
As an administrator of several Matrix servers, every now and then I have to decommission one.
You can't just power the server down, throw it away and be done with it (really, you can't!). You'll have to remove all users first, and give those removals some time to propagate over the Matrix universe. After that, you can power the server down and junk it.
A handful of users can be removed manually with, for example, Synapse-Admin. But today I have a server with several thousands of users... I've had problems with Carpal Tunnel Syndrome before, so there's no way I'm going to spend several hours moving my mouse the same directions over and over again for hours.
PrepareI use the
Matrix API and curl (thanks for that, @
daniel:// stenberg://) to do this the easy way. Well, some of you may scratch your heads when I call this the easy way... 😏
All the commands I show here, are run on the Matrix server itself. You can run them anywhere, but then you'll have to replace "localhost" for the URL of your server, of course.
First of all, you'll need an access token for an account with admin rights. If you happen to have a session open, you can simply copy it from there. If you don't, here's how to get one.
curl -s -X POST http://localhost:8008/_matrix/client/r0/login \
-H "Content-Type: application/json" \
-d '{ \
"type": "m.login.password", \
"user": "@administrator:EXAMPLE.COM" , \
"password": "SECRET ADMIN PASSWORD" \
}' \
| jq '.access_token'
This will give you a string like "syt_YWRtaW5pc3RyYXRvcg_dQCZlHWPsGluyHLYyhnH_2aI2ln", provided you used the right username, password and URL. I'll use "xxxx" for better visibility.
Check the number of usersLet's verify our access by checking how many users we're talking about.
curl -s -X GET http://localhost:8008/_synapse/admin/v2/users?limit=1000000&deactivated=true \
-H "Authorization: Bearer xxxx" \
| jq '.users[] | .name' \
| wc -l
The limit of 1 million is sort of necessary: you can't say "every user", but if you don't provide a limit, you'll only get the first 100.
Now that you know how many users there are in your database, let's remove them all.
Remove all usersYou may be thinking, "if I remove
all users, I also remove my admin account, which could complicate things". Good thinking, but no: Matrix won't remove your admin account. This means you'll have to manually leave
all rooms you've joined with that account. The same goes for all other admin accounts. THIS IS IMPORTANT!
We'll now remove all users, by first listing them all and passing the output of that command to the next, which does the actual removing.
curl -s -X GET http://localhost:8008/_synapse/admin/v2/limit=1000000 \
-H "Authorization: Bearer xxxx" \
| jq '.users[] | .name' \
| xargs -I % \
curl -s -X POST -H "Authorization: Bearer xxxx" \
-H "Content-Type: application/json" \
-d '{ "erase": true }' \
http://localhost:8008/_synapse/admin/v1/deactivate/% \
| tee removal.log \
| wc -l
This will take a looong time, and that's why I have the command write its output to "removal.log", so you can check what's happening.
Every successful removal prints this result:
{"id_server_unbind_result":"success"}So once no new entries like that are being added to the log file, you're done and should be left with only your admin account(s).
Give it a few days for the rest of the Matrix universe to pick these removals up, say a week, and then you can junk your server.
#
Matrix #
curl #
API
