mosquitto_passwd

Add a new user to a password file (will prompt to enter the password)

$ mosquitto_passwd [path/to/password_file] [username]

$ mosquitto_passwd -c [path/to/password_file] [username]

$ mosquitto_passwd -D [path/to/password_file] [username]

$ mosquitto_passwd -U [path/to/password_file]

mosquitto_passwd [-c] [-D] [-b] [-P] password_file username [password]

password_file
    The path to the Mosquitto password file to create, update, or delete users from. This file will store the username and hashed password pairs.

username
    The specific username to add, update, or delete within the specified password file.

password
    (Optional) The password for the user. This argument is only used in conjunction with the -b (batch) option to provide the password directly on the command line.

-c
    Create a new password file. If a file already exists at the specified path, it will be overwritten. This option is mandatory when initializing the password file for the first time.

-D
    Delete the specified username from the password_file. When using this option, the password argument is not required.

-b
    Use the password provided directly as the password argument on the command line. While convenient for scripting, this method is less secure as the password might be visible in shell history or process listings. It should be used with caution.

-P
    Prompt for the password securely. This is the recommended method for entering passwords interactively, as it prevents the password from appearing in shell history or process lists. The command will prompt you to enter and confirm the password.

The mosquitto_passwd command is used to create and manage the password file for Mosquitto's built-in authentication system. This file contains username and hashed password pairs, which the Mosquitto broker uses to authenticate connecting clients. It supports creating new password files, adding new users, updating existing user passwords, and deleting users.

The command uses strong hashing algorithms to store passwords securely, never storing them in plain text. It's an essential tool for securing your MQTT broker by restricting access to authorized users.

Using the -b (batch) option with the password directly on the command line is less secure as the password might be visible in shell history or process listings. It is generally recommended to use the interactive mode (-P) or omit the password argument to be prompted securely.

The password file generated by mosquitto_passwd is a plain text file containing username:hashed_password pairs. Ensure its permissions are set correctly (e.g., `chmod 600`) to prevent unauthorized access, while still allowing the Mosquitto broker to read it.

The command employs strong, industry-standard cryptographic hashing algorithms (such as PBKDF2 with SHA-256) to hash passwords before storing them in the password file. This crucial security measure ensures that plain text passwords are never stored, significantly protecting user credentials even if the password file is compromised.

To activate authentication using the file generated by mosquitto_passwd, you must configure your Mosquitto broker. This typically involves modifying the `mosquitto.conf` file to include directives like `allow_anonymous false` (to disable anonymous access) and `password_file /path/to/your/password_file` (to specify the path to the authentication file).

mosquitto_passwd was developed as an integral part of the open-source Mosquitto project, an MQTT broker, to provide a simple and robust file-based authentication mechanism. Introduced in early versions, it addresses the fundamental need for client authentication, enabling administrators to manage user credentials directly without requiring complex external authentication plugins. Its development paralleled the growth of MQTT for IoT and message brokering, ensuring a straightforward way to secure broker access.

mosquitto(8), mosquitto_pub(1), mosquitto_sub(1), passwd(1), htpasswd(1)