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]

-h, --help
    Show the help message and exit.

-u USER_ID, --user USER_ID
    The desired user ID (e.g. @user:example.com).

-p PASSWORD, --password PASSWORD
    The user's password.

--password-file PASSWORD_FILE
    File containing the user's password.

-a, --admin
    Make the new user an administrator.

-c CONFIG_PATH, --config-path CONFIG_PATH
    Path to the Synapse configuration file. Defaults to homeserver.yaml.

--no-verify-config
    Don't check the validity of the config file.

--database-url DATABASE_URL
    The database URL to connect to. Overrides value from config.

--no-input
    Do not prompt for any interactive input; errors will be raised instead.

--print-token
    Print the user's access token. This requires `--no-input`.

--token-validity TOKEN_VALIDITY
    Set the expiry of the user's access token, specified as an offset in days from now. This requires `--print-token`.

The `register_new_matrix_user` command is a utility provided by the Synapse Matrix homeserver to create new user accounts. It allows administrators to provision accounts directly, bypassing the standard registration process. This is useful for bulk user creation, internal testing, or cases where direct control over account creation is required.

The command typically connects to the Synapse database and adds a new user record with specified attributes like username, password, and whether the user is an administrator. Using this command typically requires direct access to the Synapse server or the server's administrative tools.

It is strongly recommended to use the command with care. Improper usage, especially regarding password generation or administrator privileges, can compromise the security of the Matrix homeserver. Refer to Synapse documentation for the most up-to-date information on its usage and security considerations. Remember to secure all credentials using appropriate system tooling.

This command directly modifies the Synapse database. Incorrect usage may lead to data corruption or security vulnerabilities. Always back up the database before making changes. Ensure you're running the command on the Synapse server or have proper network access to the database server. Using the `-a` or `--admin` flag grants administrator privileges, which should be used sparingly and only for trusted accounts.

Never store passwords directly in scripts. Use the `--password-file` option with appropriate file permissions or generate passwords using secure random number generators. Restrict access to the Synapse server and database to authorized personnel. Regularly audit user accounts and their permissions. Review the official Synapse documentation for security best practices.

The `register_new_matrix_user` command relies on the Synapse configuration file (`homeserver.yaml`) to determine database connection details and other settings. Ensure the configuration file is properly configured before running the command. Use the `-c` or `--config-path` option to specify a custom configuration file path if needed.

To create a new user with username `@testuser:example.com` and password `securepassword`:
register_new_matrix_user -u @testuser:example.com -p securepassword

To create a user as an administrator:
register_new_matrix_user -u @adminuser:example.com -p adminpass -a

The `register_new_matrix_user` command was developed as part of the Synapse Matrix homeserver project to provide a means for administrators to manage user accounts programmatically. It has evolved alongside Synapse, with updates to accommodate new features and security enhancements. Initially, it offered basic user creation capabilities, but later gained features like password file support, administrative privilege assignment, and token generation. The command is crucial for managing user accounts in various deployment scenarios, especially in larger Matrix instances.

synctl(1), matrix-synapse(1)