mosquitto/man/mosquitto_signal.1.xml

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

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

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

	<refnamediv>
		<refname>mosquitto_signal</refname>
		<refpurpose>a utility for sending signal events to Mosquitto brokers running on the local computer.</refpurpose>
	</refnamediv>

	<refsynopsisdiv>
		<cmdsynopsis>
			<command>mosquitto_signal</command>
			<group choice='req'>
				<arg choice='plain'><option>-a</option></arg>
				<arg choice='plain'><option>-p</option> <replaceable>pid</replaceable></arg>
			</group>
			<arg choice='plain'><replaceable>signal</replaceable></arg>
		</cmdsynopsis>
		<cmdsynopsis>
			<command>mosquitto_signal</command>
			<arg choice='plain'><option>--help</option></arg>
		</cmdsynopsis>
	</refsynopsisdiv>

	<refsect1>
		<title>Description</title>
		<para>
			<command>mosquitto_signal</command>
			is a utility that can send named signals to one or all
			instances of a Mosquitto broker running on the local
			computer.
		</para>
		<para>
			On POSIX like systems, it is a convenient replacement for the
			<citerefentry>
				<refentrytitle><link xlink:href="https://man7.org/linux/man-pages/man1/kill.1.html">kill</link></refentrytitle><manvolnum>1</manvolnum>
			</citerefentry>
			command, with the added enhancement of being able to use named
			signals rather than generic system signals like SIGUSR1, and
			with the ability to signal multiple brokers at once.
		</para>
		<para>
			On Windows, it is the only means of sending signals to a broker.
		</para>
	</refsect1>

	<refsect1>
		<title>Options</title>
		<variablelist>
			<varlistentry>
				<term><option>-a</option></term>
				<listitem>
					<para>
						Send the given signal to all processes matching the name
						<command>mosquitto</command>. As with all signal sending,
						only those processes you have permission to send the signal
						to will receive the signal.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>-p</option> <replaceable>pid</replaceable></term>
				<listitem>
					<para>
						Send the signal to a specific process id. <command>mosquitto_signal</command>
						will always attempt to send the corresponding signal to the given
						process and will not check whether it appears to be a mosquitto
						process.
					</para>
				</listitem>
			</varlistentry>
		</variablelist>
	</refsect1>

	<refsect1>
		<title>Signals</title>
		<para>
			The following named signals are available for use.
		</para>
		<variablelist>
			<varlistentry>
				<term><option>config-reload</option></term>
				<listitem>
					<para>
						Trigger the broker to reload its configuration file, if in use.
					</para>
					<para>
						On POSIX like systems this can also be triggered using the
						<option>SIGHUP</option> signal. Note that <option>SIGHUP</option>
						is used by other named signals.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>log-rotate</option></term>
				<listitem>
					<para>
						If the broker is using <option>log_dest file</option>, then this
						will trigger the broker to close and reopen the log file.
					</para>
					<para>
						On POSIX like systems this can also be triggered using the
						<option>SIGHUP</option> signal. Note that <option>SIGHUP</option>
						is used by other named signals.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>shutdown</option></term>
				<listitem>
					<para>
						Trigger the broker to quit.
					</para>
					<para>
						On POSIX like systems this can also be triggered using the
						<option>SIGINT</option> signal.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>tree-print</option></term>
				<listitem>
					<para>
						Trigger the broker to print a representation of the subscription
						and retain trees to stdout. This is intended for debugging purposes
						only.
					</para>
					<para>
						On POSIX like systems this can also be triggered using the
						<option>SIGUSR2</option> signal. Note that <option>SIGUSR2</option>
						is used by other named signals.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>xtreport</option></term>
				<listitem>
					<para>
						Trigger the broker to write some internal state information to
						<option>/tmp/xtmosquitto.kcg.&lt;pid&gt;.&lt;iteration&gt;</option>
						on POSIX systems or
						<option>xtmosquitto.kcg.&lt;pid&gt;.&lt;iteration&gt;</option>
						on Windows systems. This is intended for debugging purposes only.
					</para>
					<para>
						This signal is only used by the broker when appropriate support
						is compiled in, which is not the case by default.
					</para>
					<para>
						On POSIX like systems this can also be triggered using the
						<option>SIGRTMIN</option> signal.
					</para>
				</listitem>
			</varlistentry>
		</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>
		</simplelist>
	</refsect1>

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