'\" t
.\" Title: mosquitto_passwd
.\" Author: [see the "Author" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" Date: 06/09/2021
.\" Manual: Commands
.\" Source: Mosquitto Project
.\" Language: English
.\"
.TH "MOSQUITTO_PASSWD" "1" "06/09/2021" "Mosquitto Project" "Commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
mosquitto_passwd \- manage password files for mosquitto
.SH "SYNOPSIS"
.HP \w'\fBmosquitto_passwd\fR\ 'u
\fBmosquitto_passwd\fR [\fB\-H\fR\ \fIhash\fR] [\fB\-c\fR | \fB\-D\fR] \fIpasswordfile\fR \fIusername\fR
.HP \w'\fBmosquitto_passwd\fR\ 'u
\fBmosquitto_passwd\fR [\fB\-H\fR\ \fIhash\fR] \fB\-b\fR \fIpasswordfile\fR \fIusername\fR \fIpassword\fR
.HP \w'\fBmosquitto_passwd\fR\ 'u
\fBmosquitto_passwd\fR \fB\-U\fR \fIpasswordfile\fR
.SH "DESCRIPTION"
.PP
\fBmosquitto_passwd\fR
is a tool for managing password files for the mosquitto MQTT broker\&.
.PP
Usernames must not contain ":"\&. Passwords are stored in a similar format to
\fBcrypt\fR(3)\&.
.SH "OPTIONS"
.PP
\fB\-b\fR
.RS 4
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\&.
.RE
.PP
\fB\-c\fR
.RS 4
Create a new password file\&. If the file already exists, it will be overwritten\&.
.RE
.PP
\fB\-D\fR
.RS 4
Delete the specified user from the password file\&.
.RE
.PP
\fB\-H\fR
.RS 4
Choose the hash to use\&. Can be one of
\fIsha512\-pbkdf2\fR
or
\fIsha512\fR\&. Defaults to
\fIsha512\-pbkdf2\fR\&. The
\fIsha512\fR
option is provided for creating password files for use with Mosquitto 1\&.6 and earlier\&.
.RE
.PP
\fB\-U\fR
.RS 4
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\&.
.RE
.PP
\fBpasswordfile\fR
.RS 4
The password file to modify\&.
.RE
.PP
\fBusername\fR
.RS 4
The username to add/update/delete\&.
.RE
.PP
\fBpassword\fR
.RS 4
The password to use when in batch mode\&.
.RE
.SH "EXIT STATUS"
.PP
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\&.
.PP
MQTT v3\&.1\&.1 CONNACK codes:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB0\fR
Success
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB1\fR
Connection refused: Bad protocol version
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB2\fR
Connection refused: Identifier rejected
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB3\fR
Connection refused: Server unavailable
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB4\fR
Connection refused: Bad username/password
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB5\fR
Connection refused: Not authorized
.RE
.PP
MQTT v5 CONNACK codes:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB0\fR
Success
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB128\fR
Unspecified error
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB129\fR
Malformed packet
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB130\fR
Protocol error
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB131\fR
Implementation specific error
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB132\fR
Unsupported protocol version
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB133\fR
Client ID not valid
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB134\fR
Bad username or password
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB135\fR
Not authorized
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB136\fR
Server unavailable
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB137\fR
Server busy
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB138\fR
Banned
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB139\fR
Server shutting down
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB140\fR
Bad authentication method
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB141\fR
Keep alive timeout
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB142\fR
Session taken over
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB143\fR
Topic filter invalid
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB144\fR
Topic name invalid
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB147\fR
Receive maximum exceeded
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB148\fR
Topic alias invalid
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB149\fR
Packet too large
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB148\fR
Message rate too high
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB151\fR
Quota exceeded
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB152\fR
Administrative action
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB153\fR
Payload format invalid
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB154\fR
Retain not supported
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB155\fR
QoS not supported
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB156\fR
Use another server
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB157\fR
Server moved
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB158\fR
Shared subscriptions not supported
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB159\fR
Connection rate exceeded
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB160\fR
Maximum connect time
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB161\fR
Subscription IDs not supported
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB162\fR
Wildcard subscriptions not supported
.RE
.SH "EXAMPLES"
.PP
Add a user to a new password file:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
mosquitto_passwd
\-c
/etc/mosquitto/passwd
ral
.RE
.PP
Delete a user from a password file
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
mosquitto_passwd
\-D
/etc/mosquitto/passwd
ral
.RE
.SH "BUGS"
.PP
\fBmosquitto\fR
bug information can be found at
\m[blue]\fB\%https://github.com/eclipse/mosquitto/issues\fR\m[]
.SH "SEE ALSO"
\fBmosquitto\fR(8), \fBmosquitto.conf\fR(5), \fBmqtt\fR(7)
.SH "AUTHOR"
.PP
Roger Light