=============== Getting Started =============== Installation ============ ``synadm`` can run either on the server running Synapse (recommended), or off the Synapse server (requires additional external configuration). It functions on Linux and macOS. If running ``synadm`` outside of the Synapse server, this will change how Synapse and reverse proxies are configured. .. :ref:`how Synapse and reverser proxies are configured `. There are multiple ways to install ``synadm``: * Using ``pipx`` * From your distribution's package manager pipx method (recommended) ------------------------- To install ``synadm``, we recommend using `pipx`_ to install it from `PyPI`_ on your Synapse server: .. code-block:: pipx install synadm Updating is not much different, just a different command: .. code-block:: pipx upgrade synadm .. _pipx: https://pipx.pypa.io/latest/installation/ .. _PyPI: https://pypi.org/project/synadm/ The easiest way to `install pipx `_ is from your Linux distribution's package manager (or homebrew on macOS). .. _pipx: https://pipx.pypa.io/latest/installation/ Distribution packages method ---------------------------- You can alternatively also install ``synadm`` directly from your Linux distribution's repositories, if a package exists. The disadvantage is that they may be a couple releases behind, even for rolling release distributions, but differences won't be much. .. image:: https://repology.org/badge/vertical-allrepos/synadm.svg?exclude_unsupported=1&minversion=0.44&columns=2 :target: https://repology.org/project/synadm/versions :alt: Repology packaging status list. Currently as of writing contains Alpine Linux 3.22, nixpkgs stable 25.05, and pkgsrc current as having the latest version (0.48). Other distributions also package it, like Debian, Gentoo, and Ubuntu, but are on older versions. Things may have changed since writing this on 2025-10-14. You can click the list to open Repology to also see distributions which are out of support. Anything older than 0.44 is colored extremely red because it is very outdated (2+ years old), and is missing a significant amount of features. How to install a package depends on your distribution. We don't have all the commands documented here. Configuring synadm ================== Now that synadm is installed, here's the overview: 0. (Optional, not documented here) Creating a dedicated admin account 1. Run ``synadm config``, but typing anything for the "user token" 2. Run ``synadm matrix login `` to get a token 3. Run ``synadm config`` again but adding a usable token 4. Test things work by running ``synadm version`` or some other command Running ``synadm config`` before logging in is required, because ``synadm`` automatically launches the configuration process if it's not completely configured, even for the login command (this is known under `issue #141 `_). .. _issue_141: https://codeberg.org/synadm/synadm/issues/141 You can alternatively get an access token by logging into an admin account using Element/SchildiChat, and grabbing the access in the "Help & About" section of settings. Detailed walk through --------------------- Here's the full setup process with details and terminal output: 1. Run ``synadm config`` and configure it. Here's an example run through in v0.49 with a new config: .. _synadm_config_run: .. code-block:: :caption: Example ``synadm config`` run $ synadm config ERROR [Errno 2] No such file or directory: '/home/username/.config/synadm.yaml' while reading configuration file ERROR Config entry missing: user, Running configurator... Synapse admin user name []: @synapse_admin_api_user:example.com Synapse admin user token [NOT SET]: Synapse protocol (http, unix) [http]: Synapse base URL (or path to socket) [http://localhost:8008]: http://localhost:8448 Synapse Admin API path [/_synapse/admin]: Matrix API path [/_matrix]: Default output format (yaml, json, minified, human, pprint): human Default http timeout [30]: 600 Homeserver name ("auto-retrieval" or the domain part in your MXID) [auto-retrieval]: example.com Verify certificate [True]: Server discovery mode (used with homeserver name auto-retrieval) (well-known, dns) [well-known]: Restricting access to config file to user only. When asked for the "Synapse admin user token", keymash on the keyboard and press enter, you'll retrieve a valid token later. If you do have a valid token, you can input the token instead. Currently, anything you type/paste will be invisible with no feedback, not even redacted characters. With "Synapse protocol" set to ``http``, "Synapse base URL" must be prefixed with ``http://`` or ``https://``. Otherwise with "Synapse protocol" set to ``unix``, the "Synapse base URL" becomes the absolute path to the unix socket. This should only be used if Synapse is configured to listen on a unix socket, and you wish to interface directly with Synapse. "Homeserver name" must be the domain name after the colon in your Matrix User ID (MXID). You can set it to auto-retrieval for ``synadm`` to figure that out for you, but it's best if you set this value manually. This is however only used with Media Quarantine/Unquarantine and Local Media Deletion, but those will not function without the correct homeserver name. 2. Run ``synadm matrix login `` to get a token. If at this stage ``synadm`` seems to launching the configuration, enter anything for "Synapse admin user token", it does not matter for now. You do need to specify the MXID again on the command line. After running the command, you'll be asked for the password, then you'll get a token from Synapse if the login is successful. .. code-block:: :caption: Example ``synadm matrix login`` run $ synadm matrix login @synapse_admin_api_user:example.com Password: user_id @synapse_admin_api_user:example.com access_token syt_Yg_mjSzQDosTiKyLoLiFjIh_4F8t0w home_server example.com device_id YSQKGHVGHG well_known {'m.homeserver': {'base_url': 'http://example.com/'}} Copy the value after ``access_token``, starting with ``syt_`` followed by random characters. Make sure to keep this value a secret, because this is the token for the Matrix account that presumably has admin privileges, which can do a lot of things. **This command only works with direct password logins, and not SSO logins.** Use Element/SchildiChat to login and take access token from settings (within the "Advanced & Help" section in settings) if you cannot use a direct password login. 3. Run ``synadm config`` again to add the token to the configuration. Your configuration is not overwritten when you run ``synadm config`` with an existing config. You can press enter to use configured values. If you didn't input a valid token earlier (because you're logging in), you will need to run it again and then paste the token. See :ref:`example syandm config run ` for how ``synadm config`` looks like again. Remember that ``synadm config`` will not give any visual typing feedback at all, not even redacted characters. **Note: The access token is written in the configuration (at ~/.config/synadm.yml), stored in plain-text, and guarded purely through filesystem permissions, which is not perfectly secure.** synadm does not automatically adjust permissions to be unreadable for anyone other than the user on operating systems not considered "posix" `by Python `_. The access token being stored in plain text is kind a moot point for ``synadm`` users using it on the same server that's also running Synapse, because Synapse stores access tokens directly in the database and more critical things like the signing keys (See `issue #189 `_). This will be different if you're using ``synadm`` on your laptop/desktop, accessing your Synapse remotely, which becomes less of a moot point. .. _issue_189: https://codeberg.org/synadm/synadm/issues/189 .. _python_os_name: https://docs.python.org/3/library/os.html#os.name 4. Run ``synadm version`` to see if it works ``synadm version`` is a command that fetches the currently running Synapse version, using the Admin API .. code-block:: :caption: Example ``synadm version`` output $ synadm version server_version 1.139.2 If this doesn't work, check the following things: * Does the account you're using have Admin API privileges? See `how to make an account become a Synapse server admin `_. .. _synapse_server_admin_enable: https://element-hq.github.io/synapse/latest/usage/administration/admin_api/index.html#authenticate-as-a-server-admin Using synadm ============ You can now run ``synadm`` and do various API calls and stuff to administrate your Synapse homeserver. The rule of thumb of using synadm is: add ``--help`` to commands if you're not sure what arguments to pass, or what commands exist. All commands have some sort of help text, accessible with ``--help``. The documentation on this site is mostly a mirror of that, at least within :doc:`index_cli_reference`. ``synadm`` commands can be structured differently. If you know your way around Synapse's Admin API documentation but don't know which command that correlates to, :doc:`features` lists the correlations. You can also use ``synadm`` as part of shell scripts. We have some surface information at :doc:`examples`. We don't recommend importing ``synadm`` into Python scripts however, as that use case is currently poorly supported. We suggest running ``synadm`` like a program, even for Python scripts. Troubleshooting =============== * Is Synapse reachable over the configured URL? Can you ``curl`` it, and the API endpoints? * Does the account you're using have Admin API privileges? See `how to make an account become a Synapse server admin `_. * Are you using Media Workers, and are media specific commands failing? `synadm currently does not support Media Workers `_. A workaround is making your reverse proxy to the media workers and the main Synapse instance, directing requests to the right thing based on endpoints. We currently don't have documentation on how to configure your reverse proxy, but `the Admin API endpoints handled by the media worker is in Synapse's docs `_. .. _media_worker_support: https://codeberg.org/synadm/synadm/issues/172 .. _media_worker_docs: https://element-hq.github.io/synapse/latest/workers.html#synapseappmedia_repository Getting help ============ If you're still scratching your head confused, you can `join our Matrix room at #synadm:peek-a-boo.at `_ to ask synadm questions. We currently don't have other platforms available. The synadm room is separate from the `Synapse room at #synapse:matrix.org `_. If your homeserver is broken, you may get better help there. Note that the Synapse room may be difficult to join on resource limited Synapse homeservers, and will generally take at least a few minutes. .. _matrix_room_link: https://matrix.to/#/%23synadm%3Apeek-a-boo.at?via=jacksonchen666.com&via=matrix.org&via=peek-a-boo.at .. _synapse_matrix_room_link: https://matrix.to/#/#synapse:matrix.org?via=matrix.org ``synadm`` also supports the ``--verbose`` or ``-v`` argument, placed like this: ``synadm -v subcommand``. This is incorrect: ``synadm subcommand -v``, the verbose argument must be place immediately after ``synadm`` and before any subcommands. Repeating the ``-v`` argument means more verbose log levels, the first enabling ``INFO``, and the second enabling ``DEBUG``, and more. Be careful when sharing logs if you use ``synadm -vvv subcommand``, as your token is certainly exposed beyond the ``DEBUG`` level. .. .. _synapse_expose_admin_api: ======================================= Configuring reverse proxies to expose admin endpoints ======================================= ``synadm`` access the ``/_synapse/admin/`` endpoints, and `the Synapse documentation suggests `_ not exposing the endpoints under that path to the wider internet. .. _synapse_admin_api: https://element-hq.github.io/synapse/latest/usage/administration/admin_api/index.html TODO