this repo has no description
document admin endpoints
authored by
Brian Olson
and committed by
Brian Olson
1c106718
d8556af7
+187
+187
cmd/bigsky/README.md
+187
cmd/bigsky/README.md
···
150
150
151
151
# check sync progress for all hosts
152
152
cat hosts.txt | parallel -j1 ./sync_pds.sh {}
153
+
154
+
155
+
## Admin API
156
+
157
+
The relay has a number of admin HTTP API endpoints. Given a relay setup listening on port 2470 and with a reasonably secure admin secret:
158
+
159
+
```
160
+
RELAY_ADMIN_PASSWORD=$(openssl rand --hex 16)
161
+
bigsky --api-listen :2470 --admin-key ${RELAY_ADMIN_PASSWORD} ...
162
+
```
163
+
164
+
One can, for example, begin compaction of all repos
165
+
166
+
```
167
+
curl -H 'Authorization: Bearer '${RELAY_ADMIN_PASSWORD} -H 'Content-Type: application/x-www-form-urlencoded' --data '' http://127.0.0.1:2470/admin/repo/compactAll
168
+
```
169
+
170
+
### /admin/subs/getUpstreamConns
171
+
172
+
Return list of PDS host names in json array of strings: ["host", ...]
173
+
174
+
### /admin/subs/perDayLimit
175
+
176
+
Return `{"limit": int}` for the number of new PDS subscriptions that the relay may start in a rolling 24 hour window.
177
+
178
+
### /admin/subs/setPerDayLimit
179
+
180
+
POST with `?limit={int}` to set the number of new PDS subscriptions that the relay may start in a rolling 24 hour window.
181
+
182
+
### /admin/subs/setEnabled
183
+
184
+
POST with param `?enabled=true` or `?enabled=false` to enable or disable PDS-requested new-PDS crawling.
185
+
186
+
### /admin/subs/getEnabled
187
+
188
+
Return `{"enabled": bool}` if non-admin new PDS crawl requests are enabled
189
+
190
+
### /admin/subs/killUpstream
191
+
192
+
POST with `?host={pds host name}` to disconnect from their firehose.
193
+
194
+
Optionally add `&block=true` to prevent connecting to them in the future.
195
+
196
+
### /admin/subs/listDomainBans
197
+
198
+
Return `{"banned_domains": ["host name", ...]}`
199
+
200
+
### /admin/subs/banDomain
201
+
202
+
POST `{"Domain": "host name"}` to ban a domain
203
+
204
+
### /admin/subs/unbanDomain
205
+
206
+
POST `{"Domain": "host name"}` to un-ban a domain
207
+
208
+
### /admin/repo/takeDown
209
+
210
+
POST `{"did": "did:..."}` to take-down a bad repo; deletes all local data for the repo
211
+
212
+
### /admin/repo/reverseTakedown
213
+
214
+
POST `?did={did:...}` to reverse a repo take-down
215
+
216
+
### /admin/repo/compact
217
+
218
+
POST `?did={did:...}` to compact a repo. Optionally `&fast=true`. HTTP blocks until the compaction finishes.
219
+
220
+
### /admin/repo/compactAll
221
+
222
+
POST to begin compaction of all repos. Optional query params:
223
+
224
+
* `fast=true`
225
+
* `limit={int}` maximum number of repos to compact (biggest first) (default 50)
226
+
* `threhsold={int}` minimum number of shard files a repo must have on disk to merit compaction (default 20)
227
+
228
+
### /admin/repo/reset
229
+
230
+
POST `?did={did:...}` deletes all local data for the repo
231
+
232
+
### /admin/repo/verify
233
+
234
+
POST `?did={did:...}` checks that all repo data is accessible. HTTP blocks until done.
235
+
236
+
### /admin/pds/requestCrawl
237
+
238
+
POST `{"hostname":"pds host"}` to start crawling a PDS
239
+
240
+
### /admin/pds/list
241
+
242
+
GET returns JSON list of records
243
+
```json
244
+
[{
245
+
"Host": string,
246
+
"Did": string,
247
+
"SSL": bool,
248
+
"Cursor": int,
249
+
"Registered": bool,
250
+
"Blocked": bool,
251
+
"RateLimit": float,
252
+
"CrawlRateLimit": float,
253
+
"RepoCount": int,
254
+
"RepoLimit": int,
255
+
"HourlyEventLimit": int,
256
+
"DailyEventLimit": int,
257
+
258
+
"HasActiveConnection": bool,
259
+
"EventsSeenSinceStartup": int,
260
+
"PerSecondEventRate": {"Max": float, "Window": float seconds},
261
+
"PerHourEventRate": {"Max": float, "Window": float seconds},
262
+
"PerDayEventRate": {"Max": float, "Window": float seconds},
263
+
"CrawlRate": {"Max": float, "Window": float seconds},
264
+
"UserCount": int,
265
+
}, ...]
266
+
```
267
+
268
+
### /admin/pds/resync
269
+
270
+
POST `?host={host}` to start a resync of a PDS
271
+
272
+
GET `?host={host}` to get status of a PDS resync, return
273
+
274
+
```json
275
+
{"resync": {
276
+
"pds": {
277
+
"Host": string,
278
+
"Did": string,
279
+
"SSL": bool,
280
+
"Cursor": int,
281
+
"Registered": bool,
282
+
"Blocked": bool,
283
+
"RateLimit": float,
284
+
"CrawlRateLimit": float,
285
+
"RepoCount": int,
286
+
"RepoLimit": int,
287
+
"HourlyEventLimit": int,
288
+
"DailyEventLimit": int,
289
+
},
290
+
"numRepoPages": int,
291
+
"numRepos": int,
292
+
"numReposChecked": int,
293
+
"numReposToResync": int,
294
+
"status": string,
295
+
"statusChangedAt": time,
296
+
}}
297
+
```
298
+
299
+
### /admin/pds/changeLimits
300
+
301
+
POST to set the limits for a PDS. body:
302
+
303
+
```json
304
+
{
305
+
"host": string,
306
+
"per_second": int,
307
+
"per_hour": int,
308
+
"per_day": int,
309
+
"crawl_rate": int,
310
+
"repo_limit": int,
311
+
}
312
+
```
313
+
314
+
### /admin/pds/block
315
+
316
+
POST `?host={host}` to block a PDS
317
+
318
+
### /admin/pds/unblock
319
+
320
+
POST `?host={host}` to un-block a PDS
321
+
322
+
323
+
### /admin/pds/addTrustedDomain
324
+
325
+
POST `?domain={}` to make a domain trusted
326
+
327
+
### /admin/consumers/list
328
+
329
+
GET returns list json of clients currently reading from the relay firehose
330
+
331
+
```json
332
+
[{
333
+
"id": int,
334
+
"remote_addr": string,
335
+
"user_agent": string,
336
+
"events_consumed": int,
337
+
"connected_at": time,
338
+
}, ...]
339
+
```