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, so let me show you how it's done.
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, I ran into that exact problem, because I did my previous user removals with Synapse-Admin (you know, selecting a handful users, clicking "remove", waiting... rince and repeat) and that wouldn't remove my admin account.
But when you use the API directly, you abandon the guard rails and you can actually hurt yourself. I was lucky enough to find that there was still one other admin account after I had removed mine, so I hijacked that one to finished the job. If yours is (was!) the only active admin account, you have a problem...
With this code we list all users MINUS OUR ADMIN ACCOUNT and pass them to the next command, that actually deletes them:
curl -s -X GET http://localhost:8008/_synapse/admin/v2/limit=1000000 \
-H "Authorization: Bearer xxxx" | \
jq '.users[] | .name' | \
sed '/@administrator:EXAMPLE.COM/d' | \
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
