<?xml version='1.0' encoding='UTF-8'?>
<?xml-stylesheet type="text/xsl" href="manpage.xsl"?>

<refentry xml:id="mosquitto_passwd"
		xmlns:xlink="http://www.w3.org/1999/xlink"
		xmlns:xi="http://www.w3.org/2001/XInclude">

	<refmeta>
		<refentrytitle>mosquitto_passwd</refentrytitle>
		<manvolnum>1</manvolnum>
		<refmiscinfo class="source">Mosquitto Project</refmiscinfo>
		<refmiscinfo class="manual">Commands</refmiscinfo>
	</refmeta>

	<refnamediv>
		<refname>mosquitto_passwd</refname>
		<refpurpose>manage password files for mosquitto</refpurpose>
	</refnamediv>

	<refsynopsisdiv>
		<cmdsynopsis>
			<command>mosquitto_passwd</command>
			<group>
				<arg choice='plain'><option>-H</option> <replaceable>hash</replaceable></arg>
			</group>
			<group>
				<arg choice='plain'><option>-c</option></arg>
				<arg choice='plain'><option>-D</option></arg>
			</group>
			<arg choice='plain'><replaceable>passwordfile</replaceable></arg>
			<arg choice='plain'><replaceable>username</replaceable></arg>
		</cmdsynopsis>
		<cmdsynopsis>
			<command>mosquitto_passwd</command>
			<group>
				<arg choice='plain'><option>-H</option> <replaceable>hash</replaceable></arg>
			</group>
			<arg choice='plain'><option>-b</option></arg>
			<arg choice='plain'><replaceable>passwordfile</replaceable></arg>
			<arg choice='plain'><replaceable>username</replaceable></arg>
			<arg choice='plain'><replaceable>password</replaceable></arg>
		</cmdsynopsis>
		<cmdsynopsis>
			<command>mosquitto_passwd</command>
			<arg choice='plain'><option>-U</option></arg>
			<arg choice='plain'><replaceable>passwordfile</replaceable></arg>
		</cmdsynopsis>
	</refsynopsisdiv>

	<refsect1>
		<title>Description</title>
		<para>
			<command>mosquitto_passwd</command> is a tool for managing
			password files for the mosquitto MQTT broker.
		</para>
		<para>
			Usernames must not contain ":". Passwords are stored in a similar
			format to
			<citerefentry><refentrytitle><link xlink:href="https://linux.die.net/man/3/crypt">crypt</link></refentrytitle><manvolnum>3</manvolnum></citerefentry>.
		</para>
	</refsect1>

	<refsect1>
		<title>Options</title>
		<variablelist>
			<varlistentry>
				<term><option>-b</option></term>
				<listitem>
					<para>
						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.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>-c</option></term>
				<listitem>
					<para>
						Create a new password file. If the file already
						exists, it will be overwritten. If the filename
						is specified as a dash <option>-</option>
						then the output will be to stdout. This only really
						makes sense with <option>-b</option>.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>-D</option></term>
				<listitem>
					<para>
						Delete the specified user from the password file.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>-H</option></term>
				<listitem>
					<para>
						Choose the hash to use. Can be one of
						<replaceable>argon2id</replaceable>,
						<replaceable>sha512-pbkdf2</replaceable>, or
						<replaceable>sha512</replaceable>. Defaults to
						<replaceable>argon2id</replaceable>. The
						<replaceable>sha512</replaceable> option is provided for
						creating password files for use with Mosquitto 1.6
						and earlier.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>-U</option></term>
				<listitem>
					<para>
						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.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>passwordfile</option></term>
				<listitem>
					<para>The password file to modify.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>username</option></term>
				<listitem>
					<para>The username to add/update/delete.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>password</option></term>
				<listitem>
					<para>The password to use when in batch mode.</para>
				</listitem>
			</varlistentry>
		</variablelist>
	</refsect1>


	<refsect1>
		<title>Exit Status</title>
			<para>
				mosquitto_passwd returns zero on success or non-zero on error.
			</para>
	</refsect1>

	<refsect1>
		<title>Examples</title>
		<para>Add a user to a new password file:</para>
		<itemizedlist mark="circle">
			<listitem><para>mosquitto_passwd <literal>-c</literal> /etc/mosquitto/passwd <literal>ral</literal></para></listitem>
		</itemizedlist>
		<para>Add a user to an existing password file:</para>
		<itemizedlist mark="circle">
			<listitem><para>mosquitto_passwd /etc/mosquitto/passwd <literal>ral</literal></para></listitem>
		</itemizedlist>
		<para>Add a user to an existing password file, passing the password on the command line:</para>
		<itemizedlist mark="circle">
			<listitem><para>mosquitto_passwd -b /etc/mosquitto/passwd <literal>ral</literal> <literal>z2Dr0BsvtZ</literal></para></listitem>
		</itemizedlist>
		<para>Update the password for a user in an existing password file:</para>
		<itemizedlist mark="circle">
			<listitem><para>mosquitto_passwd /etc/mosquitto/passwd <literal>ral</literal></para></listitem>
		</itemizedlist>
		<para>Add a user to an existing password file using the sha512 hash for Mosquitto 1.6 compatibility:</para>
		<itemizedlist mark="circle">
			<listitem><para>mosquitto_passwd -H sha512 /etc/mosquitto/passwd <literal>ral</literal></para></listitem>
		</itemizedlist>
		<para>Delete a user from a password file</para>
		<itemizedlist mark="circle">
			<listitem><para>mosquitto_passwd <literal>-D</literal> /etc/mosquitto/passwd <literal>ral</literal></para></listitem>
		</itemizedlist>
	</refsect1>

	<refsect1>
		<title>Environment Variables</title>
		<variablelist>
			<xi:include href="common/env-var-mosquitto-unsafe-allow-symlinks.xml" />
		</variablelist>
	</refsect1>

	<xi:include href="common/section-bugs.xml" />

	<refsect1>
		<title>See Also</title>
		<simplelist type="inline">
			<member>
				<citerefentry>
					<refentrytitle><link xlink:href="mosquitto-7.html">mosquitto</link></refentrytitle>
					<manvolnum>7</manvolnum>
				</citerefentry>
			</member>
			<member>
				<citerefentry>
					<refentrytitle><link xlink:href="mosquitto-8.html">mosquitto</link></refentrytitle>
					<manvolnum>8</manvolnum>
				</citerefentry>
			</member>
			<member>
				<citerefentry>
					<refentrytitle><link xlink:href="mosquitto-conf-5.html">mosquitto.conf</link></refentrytitle>
					<manvolnum>5</manvolnum>
				</citerefentry>
			</member>
			<member>
				<citerefentry>
					<refentrytitle><link xlink:href="mqtt-7.html">mqtt</link></refentrytitle>
					<manvolnum>7</manvolnum>
				</citerefentry>
			</member>
		</simplelist>
	</refsect1>

	<refsect1>
		<title>Author</title>
		<para>Roger Light <email>roger@atchoo.org</email></para>
	</refsect1>
</refentry>
