Administrators and roles
How to create the first administrator, manage roles from the command line, announce and carry out the end of the service, process uploaded images again, rebuild the search index, handle the TLS certificates that the server serves itself, and export the maintenance page.
Prerequisites
Section titled “Prerequisites”- The configuration (
host,database,database_url,kek, and so on) is set as the configuration reference describes.my config checkverifies it. - The schema is applied to the database (
my schema apply; see database.md). hostandaccount_domainare final. The first command that uses the database records them, and every later command refuses to run when the configuration differs (see Settings you cannot change later).
Creating an administrator
Section titled “Creating an administrator”my admin create -username alice -email alice@example.com- From a terminal, the command asks for the password twice, without echoing it.
- When standard input is not a terminal, the first line of standard input is the password (for example
my admin create ... < password.txt). The password cannot be given as a command-line argument or an environment variable, because those end up in process lists and shell history. - Where a one-off command has neither a terminal nor standard input, such as a Cloud Run job, add
-password-link. The command then reads no password: it sets a random one that nobody learns and prints a link after thecreated adminline, which sets the password once, for one hour, likemy admin account password-reset-link(the audit log records it aspassword_reset_link_issued). Whoever can read the command’s output can use the link, and on such a platform that output stays in the platform’s logs until the link is used or expires. Open the link right away. If it expires, issue another withmy admin account password-reset-link @alice. If issuing the link fails, the administrator already exists: the command says so and exits with code 1, and the same command gives a new link. - A password has 8 to 128 characters. It never appears in the output, the logs, or an error message.
- One transaction creates the user, the password, the primary email address, the local account (with its keys), and the grant of the
adminrole (with no grantor, which means the CLI). The built-in roles are created first if they are missing. - On success the command prints
created admin @alice@<account_domain> (user <id>, account <id>)and exits with code 0. - On a one-person server the command creates no account and exits with code 1. While sign-in is limited to login providers, it also warns that the password cannot sign in until the limit ends.
Running it again
Section titled “Running it again”- When the username or the email address (both case-insensitive) is already taken, the command changes nothing, prints which one is taken, and exits with code 1. It never changes the password or the roles of the existing user.
- A failed run writes nothing, so you can fix the cause and run the same command again.
- Exit code 2 means a usage error.
Granting and revoking roles
Section titled “Granting and revoking roles”Roles hold permissions. The built-in roles are admin (position 1000, every permission) and
moderator (position 100, with manage_reports, manage_accounts, and view_audit).
my serve checks the built-in roles every time it starts (in a process of any role), and my admin role checks them every time it runs.
Each creates what is missing and gives admin every permission of the running version.
When an upgrade adds a permission, no manual step is needed. A moderator keeps the permissions and the position the administrator set.
my admin role list # each role's position, permissions (grouped as moderation, server administration, and member features), and holdersmy admin role list -user alice # the roles of alicemy admin role grant alice moderatormy admin role revoke alice moderator-
Permissions belong to one of three groups.
- Moderation:
manage_reports,manage_accounts,manage_domains,manage_invites,view_audit. - Server administration:
manage_settings,manage_rules,manage_roles,manage_jobs,manage_login_recovery,manage_custom_emojis,manage_webhooks,manage_announcements,manage_finance,manage_supporters,manage_oauth_apps,manage_service_closure,manage_errors,manage_login_providers. - Member features:
view_finance,create_custom_emojis,start_voice_rooms,create_invites,keep_posts_longer,create_articles,create_events.
listprints one column per group (MODERATION,SERVER,MEMBER). The web client shows “Moderation” and “Administration” for the first two groups and counts the member features toward neither (see moderation.md). - Moderation:
-
A change takes effect on the user’s next request. Notifications for moderators go to the people who hold the permission when the notification is created.
-
Grants and revocations are written to the audit log as
role_grantedandrole_revoked(target kindrole). The actor of a CLI operation iscli(my admin audit list -target-kind role). -
Granting a role the user already has, or revoking one they do not have, changes and records nothing.
-
The last holder of
admincannot lose it (exit code 1). Grantadminto another user first. -
The admin screen “Roles” (
/admin/roles) lists every role and creates, changes and deletes them: a role’s page sets its place, its permissions and its badge. It offers only what the rules below allow: a place no higher than your highest role, the permissions you hold (the others a role has are named and kept), only the badge ofadmin, and no deletion ofadminormoderator. Deleting a role asks for its name typed. The roles of a plan are set from the plan. -
The admin API is
GET /api/v1/admin/roles,GET /api/v1/admin/accounts/{id}/roles, andPUT/DELETE /api/v1/admin/accounts/{id}/roles/{role}, and it needs the permissionmanage_roles. Through the API, you cannot grant or revoke a role above the highestpositionamong your own roles (403). Revoking the lastadminreturns 409. -
Staff act only on lower ranks. Through the API, moderation actions and lifting them, deciding appeals, lifting email suppressions, revealing an account’s private data, issuing a password reset link, and removing two-factor authentication need the highest
positionamong your roles to be above that of every role of the target; a higher or equal rank, your own account included, returns 403. A moderator cannot act on an administrator, and one administrator cannot act on another. These commands (my admin account ...) have no such limit, so use them when administrators disagree. -
The only administrator cannot be locked out or removed:
disable_login,suspend, andbanon them are refused, through the API (409) and these commands (exit code 1), and they cannot delete their own account (409). Another holder ofadmincounts only while they can sign in: not after deleting their account, nor while suspended, banned, or underdisable_login.
Announcing the end of the service
Section titled “Announcing the end of the service”To close the server, announce the closure first. service-closure.md describes the whole procedure, from the announcement to discarding the data.
The server keeps working as usual during the announcement. closure in GET /api/v1/instance and metadata.serviceClosure in NodeInfo show the state and the dates.
my admin closure announce -closes-at 2027-01-31T15:00:00Z -message "Thank you for using this server."my admin closure announce -closes-at 2027-02-28 -export-until 2027-04-30 # change the dates (a bare date means 00:00 UTC)my admin closure status # the state and the schedule in effectmy admin closure withdraw # withdraw the announcement-closes-athas no lower bound.-export-until(the deadline for taking data out) must be on or after-closes-at, and defaults to 30 days after the closing date.- When the closing date is less than 30 days away, the command prints a warning to standard error (the announcement is still recorded).
- Changing the dates is recorded as a new announcement, and an announcement made after a withdrawal is a new one. Once the server is closed, you can neither announce nor withdraw (exit code 1).
- Announcing, changing the dates, and withdrawing are written to the audit log as
service_closure_announcedandservice_closure_withdrawn(target kindinstance; seemy admin audit list -target-kind instance). - The admin API is
GET /api/v1/admin/closure,PUT/DELETE /api/v1/admin/closure/announcement,GET /api/v1/admin/closure/check, andPOST /api/v1/admin/closure/close. It needs the permissionmanage_service_closure(among the built-in roles, onlyadminhas it). - During the announcement, the server accepts no new users and no new payments.
- The effective registration mode is
closed(the value ofregistration_modedoes not change, and returns to effect when the announcement is withdrawn). Neither sign-ups nor sign-ups with an invitation work, and pending applications cannot be approved (409). - Announcing rejects every pending application (recorded as decided by
service_closure) and cancels all running supporter subscriptions at the end of their period. The subscribers get a notification (supporter_service_closure) and an email. New subscriptions return409. Withdrawing the announcement does not undo the rejections or the cancellations. - Every announcement, change of dates, and withdrawal sends the notification
service_closureto all local users. All of this runs as jobs, so do not stop the worker. - Every user with a confirmed email address gets an email for the announcement, a change of dates, a withdrawal, 7 days and 1 day before the closing date, the closure, and 7 days before the export deadline. Users cannot opt out (see email.md).
- After the closing date, the people who hold
manage_service_closureget the notificationadmin_service_closure_due. The server does not close itself.
- The effective registration mode is
After the closing date, close the server. Closing cannot be undone.
my admin closure check # review what the closure endsmy admin closure close # show the review, then ask for y and the domain namemy admin closure close -confirm-domain social.example # for automation: pass the domain name instead of answeringcheckandcloseshow the number of local accounts, the number of destination inboxes (the known shared inboxes), an estimate of theDeleteactivities to send (their product), the number of running supporter subscriptions, the number of unfinished migrations (Move), and the number of accounts under a retention hold (retention_holds). When migrations remain or a hold exists, the command warns on standard error. Export the records of the accounts under a hold withmy admin account export-moderationand keep them before discarding the data.closerefuses without asking when there is no announcement and before the closing date (exit code 1). Any answer other thany, or an input that differs from the server’s domain (hostin the configuration, case-insensitive), changes nothing and exits with code 1.- The closure is written to the audit log as
service_closure_closed. In the same transaction it ends every running supporter subscription (reasonservice_closed) and enqueues the jobs that cancel the subscriptions at the payment provider immediately (CancelNow). - After the closure, the client API passes only these requests: reading your own account and settings, the exports (
/exports,/csv_exports), sessions (/sessions,/authorized_apps),GET /instance, and the administration of the closure and the job queue. Everything else is refused with403(/api/v1/problems/service-closed). Streams stop and Web Push sends nothing. Signing in and resetting a password still work. - After the closure, the worker delivers a
Deleteof the actor of every local account to the federation peers, 100 at a time (migrated accounts last). It sends them even whenfederation_modeisofforinbound, and never to a suspended domain.my admin closure status(andprogressinGET /api/v1/admin/closure) shows how many accounts have a recordedDelete, how many deliveries remain to be expanded, and the number of deliveries in each state (pending,succeeded,permanent_failure,skipped,dead). Keep the worker running during delivery. When every delivery has finished, a check that runs every 10 minutes recordsdelivery_completed(service_closure_delivery_completedin the audit log), and the local actors then answer410. The server does not rerundeaddeliveries by itself; rerun them withmy job retry.
After the export deadline has passed, write the static closing page that your domain serves once the server is stopped. The command reads the database, so run it before discarding the database.
my admin closure export-html -out ./closure # every locale (the instance's default locale first)my admin closure export-html -out ./closure -lang ja,en # choose the locales and the order in index.html- Output:
<dir>/<locale>.htmlfor each locale and<dir>/index.htmlwith every locale one after another. The pages use the same template asmy maintenance exportand show the server name, the closing date, the operator’s message of the announcement, andstatus_page_url. The output also holds configuration examples for the front end:nginx.conf,Caddyfile, andcloudfront-function.js. They answer410for/ap/*,/inbox, WebFinger, host-meta, NodeInfo, and/@*, and serve the closing page for everything else. - The command refuses (exit code 1) unless the server is closed. Before
delivery_completedit prints a warning and still writes the pages. service-closure.md describes how to switch the front end to the static page.
Processing uploaded images again
Section titled “Processing uploaded images again”Each uploaded image keeps three sizes, and an animation also its moving versions. A new release of my can change those sizes or formats, and an existing image keeps its files until you process it again:
my admin media reprocess -before 2027-01-31T09:00:00Z-beforetakes the time of the change, such as the time you upgraded, in RFC 3339. Only images last processed before that time are taken, and a time that has not passed is refused.- The worker does the work, 100 images a minute, each in a job of its own (
media.reprocess_walkandmedia.reprocessin the jobs reference). Keep a worker running; the admin jobs page (/admin/jobs) shows the queue. - Running it again with the same time is safe. Images already processed are left alone, and the ones the first run did not reach are picked up.
- Originals are not kept, so each image is made again from its large version. Detail that the large version lost does not come back, and each run with a later time re-encodes the images once more and loses a little quality. Run it once per change.
- Video and audio files are not re-encoded and are left alone. An image that the current limits no longer accept keeps its current version, and the worker logs a warning.
The new version of an image has new URLs. The old files stay for media_replaced_retention (30 days by default, configuration reference), so pages that are open and caches keep working, and the hourly job media.purge_replaced then deletes them. Other servers are not told about the new URLs: a server that still holds an old URL and has no copy of its own stops showing the image after that time. Allow for the extra storage until the old files go.
Rebuilding the search index
Section titled “Rebuilding the search index”my search handles the index of the full-text search of posts, on a server with a search engine. With search = none each command says so, does nothing, and exits with code 0.
my search rebuild # empty the index, then have the worker add every post that qualifiesmy search rebuild --keep # add them without emptying the indexmy search rebuild --rate 50 # at most 50 posts a second (20 by default, 1000 at most)my search clear # empty the index and end any rebuildmy search status # the backend and the progress and failures of the latest rebuildRun my search rebuild again to resume one that stopped. It goes on from the last post handled and does not empty the index again. While one is unfinished, the other mode is refused with exit code 1. Full-text search of posts says when to use each.
TLS certificates
Section titled “TLS certificates”my tls handles the certificates of a server that serves HTTPS itself (tls = acme or tls = files; see
Serving HTTPS from the server).
my tls status # each host: certificate, renewal, failures, latest ordersmy tls renew -host social.example # order a certificate now, without waitingmy tls revoke -host social.example -reason key_compromise # replace, then revoke the current certificatestatusshows, for each host, the current certificate (serial, issuer, expiry), when it is renewed, how many orders in a row obtained no certificate, and the latest orders with their errors. Withtls = filesit shows the certificate oftls_cert_file; withtls = offit says so.renewandrevokeneedtls = acme, the running server (it answers the certificate authority’s checks), and akvother thanmemory. They exit with code 1 when they fail, when another process is ordering the certificate of the host at that moment, and withtls = filesortls = off.-reasoniskey_compromisewhen the private key may be known to others, otherwisesupersededoroperator.revokeexits with code 0 and prints a warning when it revoked the certificate but could not order its replacement.
Commands and metrics explains what each one does to the running processes.
Exporting the maintenance page
Section titled “Exporting the maintenance page”my maintenance export writes the page of the maintenance mode as static HTML,
for a load balancer, CDN, or reverse proxy to serve while my serve itself cannot run (an image being replaced, a revision that does not start).
It uses the same template as the maintenance mode, so both show the same words and look.
my maintenance export -out ./maintenance -lang en,ja # reads the database for at most 5 secondsmy maintenance export -out ./maintenance -lang en,ja -offline # the configuration and the default theme only- Output:
<dir>/<locale>.htmlfor each locale of-lang, for front ends that choose a page byAccept-Language, and<dir>/index.htmlwith every locale one after another, for those that cannot. The pages have inline CSS, no script, and no external resource; their Content-Security-Policy is in a<meta>element. - Words: the settings
maintenance_server_name,maintenance_message,maintenance_until, andstatus_page_url(configuration reference). - Without
-offline, it also reads the instance’s name (whenmaintenance_server_nameis unset), its default locale (when-langis not given), and the token overrides of its published theme. When the database cannot be read, it prints a warning, writes the pages from the configuration and the default theme, and exits 0. - Run it again whenever those settings or the theme change, and before each maintenance, so that the pages in the front end stay current.
For LLMs and coding agents:this page as Markdown, llms.txt,llms-full.txt, llms-small.txt