Skip to content

Commit baf310b

Browse files
worldwidewardworldwideward
committed
initial commit
1 parent 25ad6b5 commit baf310b

File tree

6 files changed

+904
-0
lines changed

6 files changed

+904
-0
lines changed

‎README.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Synapse Admin API CLI
2+
3+
This is a CLI tool written in **Bash** to interact with the Synapse Admin API.
4+
5+
## Installation
6+
7+
The installation of this tool is pretty straigthforward. Just clone this repository and run the installation script.
8+
9+
```bash
10+
git clone <>
11+
cd synapse-admin-api-cli/
12+
./install.sh
13+
```
14+
15+
## Access Token
16+
17+
Instructions to figure out your access token with Element (the flagship Matrix client).
18+
19+
1. Log in with and admin account
20+
21+
2. Open **Settings** > **Help & About**
22+
23+
3. Below **Advanced** you can view/copy the Access Token.
24+
25+
## Configuration
26+
27+
Create a file named `/etc/synapse-admin/cli.conf` and add:
28+
29+
```bash
30+
SYNAPSE_HOMESERVER="matrix.homeserver.example"
31+
SYNAPSE_ADMIN_USER="@admin:homeserver.example"
32+
SYNAPSE_ACCESS_TOKEN="<admin access token>"
33+
```
34+
35+
## Usage
36+
37+
Run `synapse-admin` to view the inline help

‎install.sh

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
#!/bin/bash
2+
3+
function install_dependencies() {
4+
5+
apt update
6+
7+
dependencies=(
8+
"openssl"
9+
"curl"
10+
"jq"
11+
)
12+
13+
for package in ${dependencies[@]}; do
14+
15+
which $package >> /dev/null
16+
17+
if [ "$?" != 0 ]; then
18+
apt install -y $package
19+
fi
20+
done
21+
}
22+
23+
function create_directories() {
24+
25+
mkdir -p /etc/synapse-admin
26+
mkdir -p /lib/synapse-admin
27+
}
28+
29+
function copy_libs() {
30+
31+
cp -ra $PWD/lib/*.sh /lib/synapse-admin/
32+
}
33+
34+
function copy_script() {
35+
36+
execution_path=$(echo $PATH | cut -d ":" -f 1)
37+
38+
cp -ra $PWD/synapse-admin $execution_path/synapse-admin
39+
40+
sed -i 's/$PWD\/lib/\/lib\/synapse-admin/' $execution_path/synapse-admin
41+
42+
43+
which synapse-admin
44+
45+
if [ "$?" != 0 ]; then
46+
echo "[ERROR] Something went wrong during the installation"
47+
else
48+
echo "[INFO] synapse admin succesfully installed"
49+
fi
50+
}
51+
52+
function main() {
53+
54+
if [ "$(id -u)" != 0 ]; then
55+
echo "[ERROR] You must run this installation script as root"
56+
exit 1
57+
fi
58+
59+
install_dependencies
60+
create_directories
61+
copy_libs
62+
copy_script
63+
64+
}
65+
66+
main

‎lib/help.sh

Lines changed: 288 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,288 @@
1+
#!/bin/bash
2+
3+
function general_help() {
4+
5+
echo "Synapse Admin v3 - CLI wrapper to interact with the Matrix Synapse Admin API"
6+
echo ""
7+
echo "Commands:"
8+
echo "---------"
9+
echo ""
10+
echo "get - retrieve inforamtion about resources on this server"
11+
echo "create - create new resources on this server"
12+
echo "update - update existing resources on this server"
13+
echo "delete - delete existing resources from this server"
14+
echo ""
15+
echo "Resources:"
16+
echo "----------"
17+
echo ""
18+
echo "users - users on this server"
19+
echo "rooms - chatrooms on this server"
20+
echo "media - media on this server (video, photos, ..)"
21+
echo "jobs - server maintenance background jobs "
22+
echo ""
23+
echo "Usage:"
24+
echo "------"
25+
echo ""
26+
echo "synapse-admin [verb] [resource] [options]"
27+
echo ""
28+
echo ""
29+
echo "To learn more about the Synapse Admin API, visit https://element-hq.github.io/synapse/latest/usage/administration/admin_api"
30+
echo ""
31+
}
32+
33+
function verb_help_get() {
34+
35+
echo "Resources:"
36+
echo "----------"
37+
echo ""
38+
echo "users - get detailed information about users on this server"
39+
echo "rooms - get detailed information about rooms on this server"
40+
echo "media - get detailed information about media on this server"
41+
echo "jobs - get detailed information about media on this server"
42+
echo "federation - get information about homeservers that are federated with this server"
43+
echo "version - get the synapse version this server is running"
44+
echo ""
45+
echo "Usage:"
46+
echo "------"
47+
echo ""
48+
echo "synapse-admin get [resource] [options]"
49+
}
50+
51+
function verb_help_create() {
52+
53+
echo "Resources:"
54+
echo "----------"
55+
echo ""
56+
echo "jobs - create background jobs for this server"
57+
echo "notices - send a server notice"
58+
echo ""
59+
echo "Usage:"
60+
echo "------"
61+
echo ""
62+
echo "synapse-admin create [resource] [options]"
63+
}
64+
65+
function verb_help_update() {
66+
67+
echo "Resources:"
68+
echo "----------"
69+
echo ""
70+
echo "users - update users on this server"
71+
echo "rooms - update rooms on this server"
72+
echo ""
73+
echo "Usage:"
74+
echo "------"
75+
echo ""
76+
echo "synapse-admin update [resource] [options]"
77+
}
78+
79+
function verb_help_delete() {
80+
81+
echo "Resources:"
82+
echo "----------"
83+
echo ""
84+
echo "media - delete media on this server"
85+
echo "rooms - delete rooms on this server"
86+
echo ""
87+
echo "Usage:"
88+
echo "------"
89+
echo ""
90+
echo "synapse-admin delete [resource] [options]"
91+
}
92+
93+
function resource_help_get_users() {
94+
95+
echo "Options:"
96+
echo "------"
97+
echo ""
98+
echo "--all - list all existing users, including deactivated & locked users"
99+
echo "--output [file] - save a list of users to a file"
100+
echo "--user-id [user_id] - show details about a specific user"
101+
echo "--show-memberships - show the rooms a user is a member to"
102+
echo "--statistics - get 100 biggest users in terms of diskspace consumption"
103+
echo ""
104+
echo "Usage:"
105+
echo "------"
106+
echo ""
107+
echo "synapse-admin get users [options]"
108+
echo ""
109+
echo "Example:"
110+
echo "--------"
111+
echo ""
112+
echo "synapse-admin get users --all --output users.json"
113+
echo "synapse-admin get user --user-id @john:oblak.be"
114+
echo "synapse-admin get user --user-id @john:oblak.be --show-memberships"
115+
}
116+
117+
function resource_help_get_rooms() {
118+
119+
echo "Options:"
120+
echo "------"
121+
echo ""
122+
echo "--all - list all existing rooms"
123+
echo "--output [file] - save list of rooms to a file"
124+
echo "--room-id [room_id] - show details about a specific room"
125+
echo "--show-members - show a list members of the room"
126+
echo "--statistics - get 10 largest rooms and estimated diskspace they are taking"
127+
echo "--is-blocked - show the blocked status of a room"
128+
echo ""
129+
echo "Usage:"
130+
echo "------"
131+
echo ""
132+
echo "synapse-admin get rooms [options]"
133+
echo ""
134+
echo "Example:"
135+
echo "--------"
136+
echo ""
137+
echo "synapse-admin get rooms --all --output rooms.json"
138+
echo "synapse-admin get rooms --statistics"
139+
echo "synapse-admin get room --room-id '!xfdfjsigedfsf:oblak.be'"
140+
echo "synapse-admin get room --room-id '!xfdfjsigedfsf:oblak.be' --show-members"
141+
}
142+
143+
function resource_help_get_rooms() {
144+
145+
echo "Options:"
146+
echo "------"
147+
echo ""
148+
echo "--all - list all existing rooms"
149+
echo "--output [file] - save list of rooms to a file"
150+
echo "--room-id [room_id] - show details about a specific room"
151+
echo "--show-members - show a list members of the room"
152+
echo "--statistics - get 10 largest rooms and estimated diskspace they are taking"
153+
echo "--is-blocked - show the blocked status of a room"
154+
echo ""
155+
echo "Usage:"
156+
echo "------"
157+
echo ""
158+
echo "synapse-admin get rooms [options]"
159+
echo ""
160+
echo "Example:"
161+
echo "--------"
162+
echo ""
163+
echo "synapse-admin get rooms --all --output rooms.json"
164+
echo "synapse-admin get rooms --statistics"
165+
echo "synapse-admin get room --room-id '!xfdfjsigedfsf:oblak.be'"
166+
echo "synapse-admin get room --room-id '!xfdfjsigedfsf:oblak.be' --show-members"
167+
}
168+
169+
function resource_help_create_jobs() {
170+
171+
echo "Options:"
172+
echo "------"
173+
echo ""
174+
echo "--regenerate-directory - recalculate the user directory if it is stale or out of sync"
175+
echo "--populate-stats - recalculate the stats for all rooms"
176+
echo ""
177+
echo "Usage:"
178+
echo "------"
179+
echo ""
180+
echo "synapse-admin create jobs [options]"
181+
echo ""
182+
echo "Example:"
183+
echo "--------"
184+
echo ""
185+
echo "synapse-admin create jobs --regenerate-directory"
186+
}
187+
188+
function resource_help_create_notices() {
189+
190+
echo "Options:"
191+
echo "------"
192+
echo ""
193+
echo "--message [message text] - send a serverwide text notice"
194+
echo ""
195+
echo "Usage:"
196+
echo "------"
197+
echo ""
198+
echo "synapse-admin create notice [options]"
199+
echo ""
200+
echo "Example:"
201+
echo "--------"
202+
echo ""
203+
echo "synapse-admin create notice --message 'This is a test notice'"
204+
}
205+
206+
function resource_help_update_users() {
207+
208+
echo "Options:"
209+
echo "------"
210+
echo ""
211+
echo "--user-id [user-id] - update a specific user"
212+
echo "--deactivate - deactive a user account"
213+
echo "--lock - lock a user account"
214+
echo "--suspend - suspend a user account"
215+
echo ""
216+
echo "Usage:"
217+
echo "------"
218+
echo ""
219+
echo "synapse-admin update users [options]"
220+
echo ""
221+
echo "Example:"
222+
echo "--------"
223+
echo ""
224+
echo "synapse-admin update users --user-id @john:oblak.be --suspend"
225+
}
226+
227+
function resource_help_update_rooms() {
228+
229+
echo "Options:"
230+
echo "------"
231+
echo ""
232+
echo "--room-id [room-id] - update a specific room"
233+
echo "--block - block a room"
234+
echo "--unblock - unblock a room"
235+
echo ""
236+
echo "Usage:"
237+
echo "------"
238+
echo ""
239+
echo "synapse-admin update users [options]"
240+
echo ""
241+
echo "Example:"
242+
echo "--------"
243+
echo ""
244+
echo "synapse-admin update users --user-id @john:oblak.be --suspend"
245+
}
246+
247+
function resource_help_delete_media() {
248+
249+
echo "Options:"
250+
echo "------"
251+
echo ""
252+
echo "--user-id [user-id] - delete all media for a specific user"
253+
echo "--local [MM/DD/YYYY] - delete local media since date"
254+
echo "--remote [MM/DD/YYYY] - delete remote media since date"
255+
echo ""
256+
echo "Usage:"
257+
echo "------"
258+
echo ""
259+
echo "synapse-admin delete media [options]"
260+
echo ""
261+
echo "Example:"
262+
echo "--------"
263+
echo ""
264+
echo "synapse-admin delete media --user-id @john:oblak.be"
265+
echo "synapse-admin delete media --local 01/01/2023"
266+
}
267+
268+
function resource_help_delete_rooms() {
269+
270+
echo "Options:"
271+
echo "------"
272+
echo ""
273+
echo "--room-id [room-id] - execute delete actions on a specific room"
274+
echo "--history [MM/DD/YYYY] - purge the history of the room since date (this does not delete the room itself)"
275+
echo "--force - delete and purge the room (this is irreversible)"
276+
echo "--status - show the status of a room that's being deleted"
277+
echo ""
278+
echo "Usage:"
279+
echo "------"
280+
echo ""
281+
echo "synapse-admin delete room [options]"
282+
echo ""
283+
echo "Example:"
284+
echo "--------"
285+
echo ""
286+
echo "synapse-admin delete room --room-id '!xfdfjsigedfsf:oblak.be' --force"
287+
echo "synapse-admin delete room --room-id '!xfdfjsigedfsf:oblak.be' --history 01/02/2023"
288+
}

0 commit comments

Comments
 (0)