register_new_matrix_user
Register a new Matrix user account
TLDR
Create a user interactively
Create an admin user interactively
Create an admin user non-interactively (not recommended)
SYNOPSIS
register_new_matrix_user [options]
PARAMETERS
-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`.
DESCRIPTION
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.
CAVEATS
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.
SECURITY CONSIDERATIONS
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.
CONFIGURATION
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.
EXAMPLE USAGE
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
HISTORY
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.
SEE ALSO
synctl(1), matrix-synapse(1)