Scroll to navigation



mosquitto_passwd - manage password files for mosquitto


mosquitto_passwd [-H hash] [-c | -D] passwordfile username

mosquitto_passwd [-H hash] -b passwordfile username password

mosquitto_passwd -U passwordfile


mosquitto_passwd is a tool for managing password files for the mosquitto MQTT broker.

Usernames must not contain ":". Passwords are stored in a similar format to crypt(3).



Run in batch mode. This allows the password to be provided at the command line which can be convenient but should be used with care because the password will be visible on the command line and in command history.


Create a new password file. If the file already exists, it will be overwritten.


Delete the specified user from the password file.


Choose the hash to use. Can be one of sha512-pbkdf2 or sha512. Defaults to sha512-pbkdf2. The sha512 option is provided for creating password files for use with Mosquitto 1.6 and earlier.


This option can be used to upgrade/convert a password file with plain text passwords into one using hashed passwords. It will modify the specified file. It does not detect whether passwords are already hashed, so using it on a password file that already contains hashed passwords will generate new hashes based on the old hashes and render the password file unusable.


The password file to modify.


The username to add/update/delete.


The password to use when in batch mode.


mosquitto_sub returns zero on success, or non-zero on error. If the connection is refused by the broker at the MQTT level, then the exit code is the CONNACK reason code. If another error occurs, the exit code is a libmosquitto return value.

MQTT v3.1.1 CONNACK codes:

0 Success

1 Connection refused: Bad protocol version

2 Connection refused: Identifier rejected

3 Connection refused: Server unavailable

4 Connection refused: Bad username/password

5 Connection refused: Not authorized

MQTT v5 CONNACK codes:

0 Success

128 Unspecified error

129 Malformed packet

130 Protocol error

131 Implementation specific error

132 Unsupported protocol version

133 Client ID not valid

134 Bad username or password

135 Not authorized

136 Server unavailable

137 Server busy

138 Banned

139 Server shutting down

140 Bad authentication method

141 Keep alive timeout

142 Session taken over

143 Topic filter invalid

144 Topic name invalid

147 Receive maximum exceeded

148 Topic alias invalid

149 Packet too large

148 Message rate too high

151 Quota exceeded

152 Administrative action

153 Payload format invalid

154 Retain not supported

155 QoS not supported

156 Use another server

157 Server moved

158 Shared subscriptions not supported

159 Connection rate exceeded

160 Maximum connect time

161 Subscription IDs not supported

162 Wildcard subscriptions not supported


Add a user to a new password file:

•mosquitto_passwd -c /etc/mosquitto/passwd ral

Delete a user from a password file

•mosquitto_passwd -D /etc/mosquitto/passwd ral


mosquitto bug information can be found at


mosquitto(8), mosquitto.conf(5), mqtt(7)


Roger Light <>

06/09/2021 Mosquitto Project