register_new_matrix_user

Create a user interactively

$ register_new_matrix_user --config [path/to/homeserver.yaml]

$ register_new_matrix_user --config [path/to/homeserver.yaml] --admin

$ register_new_matrix_user --config [path/to/homeserver.yaml] --user [username] --password [password] --admin

register_new_matrix_user [options]
or
register_new_matrix_user -c CONFIG_FILE -u USERNAME [-p PASSWORD] [--no-password] [--make-guest] [-a]

-c CONFIG_FILE
    Specifies the path to the Synapse homeserver configuration file (e.g., homeserver.yaml). This is crucial for the script to connect to the correct database and settings.

-u USERNAME
    The desired username for the new Matrix user. If omitted, the script may prompt for interactive input.

-p PASSWORD
    The password for the new user. If omitted and --no-password is not used, the script will prompt for a password interactively.

--no-password
    Creates the user without an initial password. The user will need to use a password reset mechanism or be assigned one later.

--make-guest
    Registers the new user as a guest account. Guest accounts have limited permissions.

-a, --admin
    Grants administrator privileges to the newly created user. Admin users can manage other users, rooms, and homeserver settings.

register_new_matrix_user is a Python script included with the Matrix Synapse homeserver software. It provides a command-line interface for administrators to directly create new user accounts on their Synapse instance. This utility is particularly useful for bulk user creation, setting up administrative accounts, or bypassing the standard user registration process, which might be disabled or require email verification. It allows specifying a username, password, and whether the user should be an administrator. The script requires access to the Synapse configuration file to function correctly and typically needs to be run with appropriate permissions from the Synapse virtual environment. It interacts directly with the homeserver's database to provision new user entries.

This command directly modifies the Synapse homeserver's database. Incorrect usage or running it against a live server without proper understanding could lead to data corruption or unexpected behavior. It should typically be run by the user account that owns the Synapse installation or with elevated privileges. Ensure the Synapse server is stopped or in a maintenance state if significant user management is being performed, though this specific script is usually safe to run while Synapse is running.

If the -u or -p parameters are omitted, the script will typically run in an interactive mode, prompting the user to enter the username, password, and other details directly in the terminal.

The exact path to the script can vary depending on the Synapse installation method (e.g., source, Debian package, Docker). Common locations include virtual environments (e.g., /opt/matrix-synapse/env/bin/register_new_matrix_user), Python site-packages, or within Docker containers.

The script needs read access to the Synapse configuration file and write access to the Synapse database. This usually means running it as the user that owns the Synapse process or with root privileges.

The register_new_matrix_user script has been a fundamental part of the Matrix Synapse homeserver administration toolkit since its early development. It was introduced to provide a direct, programmatic way for server administrators to manage user accounts, complementing the standard registration flows which might involve email verification or be disabled on private instances. Its functionality has remained largely consistent, primarily focused on the core task of user provisioning, adapting slightly with Synapse database schema changes over time.