-
Notifications
You must be signed in to change notification settings - Fork 3
/
AppendixB-Mosquitto.html
191 lines (163 loc) · 11.1 KB
/
AppendixB-Mosquitto.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
<section data-type="appendix" id="appendix_mosquitto" xmlns="http://www.w3.org/1999/xhtml">
<h1>Mosquitto</h1>
<p class="lead">In this appendix, we describe how to install the <a href="http://mosquitto.org">Mosquitto broker</a> and its tools to produce and consume MQTT messages from the command line.<a contenteditable="false" data-primary="brokers" data-secondary="Mosquitto broker" data-type="indexterm" id="brokersMos"> </a><a contenteditable="false" data-primary="Mosquitto broker" data-type="indexterm"> </a></p>
<section data-type="sect1" id="_download_and_installation_2">
<h1>Download and Installation</h1>
<p>Mosquitto is an open source message broker that implements the MQTT protocol. The public MQTT broker <a contenteditable="false" data-primary="Mosquitto broker" data-secondary="downloading and installing" data-type="indexterm"> </a>hosted on <em>iot.eclipse.org</em> that we used in <a data-type="xref" href="#ch_mobile_mqtt">#ch_mobile_mqtt</a> and <a data-type="xref" href="#ch_web_mqtt">#ch_web_mqtt</a> is an instance of Mosquitto.<a contenteditable="false" data-primary="Eclipse" data-secondary="Mosquitto broker on" data-type="indexterm"> </a></p>
<p>Mosquitto also comes with two command-line tools to send and receive MQTT messages. These tools are handy when writing an application using MQTT to be able to quickly produce and consume messages and check that the application is working as expected.</p>
<p>To install Mosquitto on your operating system, please consult its <a href="http://mosquitto.org/download/">documentation page</a>, which contains instructions for various operating systems and package managers.</p>
</section>
<section data-type="sect1" id="_produce_messages_with_code_mosquitto_pub_code">
<h1>Produce Messages with mosquitto_pub</h1>
<p>The <code>mosquitto_pub</code> command-line tool can be used to<a contenteditable="false" data-primary="Mosquitto broker" data-secondary="producing messages with mosquitto_pub" data-type="indexterm"> </a> produce MQTT messages.<a contenteditable="false" data-primary="messages" data-secondary="producing MQTT messages with mosquitto_pub" data-type="indexterm"> </a></p>
<p>In this book, we use it in the simplest fashion to send a message. The parameters we must pass to the tool are:</p>
<ul>
<li>
<p><code>-h host</code> to specify the host of the MQTT broker</p>
</li>
<li>
<p><code>-t topic</code> to specify the topic of the MQTT message</p>
</li>
<li>
<p><code>-m message</code> to specify the message payload to send</p>
</li>
</ul>
<p>For example, to send a message with the text <code>yellow</code> for payload on the topic <code>/mwm/XYZ/alert</code> on the broker hosted on <em>iot.eclipse.org</em>, the command line is:</p>
<pre data-code-language="sh" data-type="programlisting">
$ mosquitto_pub -h iot.eclipse.org -t /mwm/XYZ/alert -m yellow</pre>
<p>The full list of the <code>mosquitto_pub</code> parameters is available by calling <code>mosquitto_pub --help</code>:</p>
<pre data-type="programlisting">
$ mosquitto_pub --help
mosquitto_pub is a simple mqtt client that will publish a message on a single topic and exit.
mosquitto_pub version 1.3.1 running on libmosquitto 1.3.1.
Usage: mosquitto_pub [-h host] [-p port] [-q qos] [-r] {-f file | -l | -n | -m message} -t topic
[-A bind_address] [-S]
[-i id] [-I id_prefix]
[-d] [--quiet]
[-M max_inflight]
[-u username [-P password]]
[--will-topic [--will-payload payload] [--will-qos qos]
[--will-retain]]
[{--cafile file | --capath dir} [--cert file] [--key file]
[--ciphers ciphers] [--insecure]]
[--psk hex-key --psk-identity identity [--ciphers ciphers]]
mosquitto_pub --help
-A : bind the outgoing socket to this host/ip address. Use to control which interface the client communicates over.
-d : enable debug messages.
-f : send the contents of a file as the message.
-h : mqtt host to connect to. Defaults to localhost.
-i : id to use for this client. Defaults to mosquitto_pub_ appended with the process id.
-I : define the client id as id_prefix appended with the process id. Useful for when the broker is using the clientid_prefixes option.
-l : read messages from stdin, sending a separate message for each line.
-m : message payload to send.
-M : the maximum inflight messages for QoS 1/2..
-n : send a null (zero length) message.
-p : network port to connect to. Defaults to 1883.
-q : quality of service level to use for all messages. Defaults to 0.
-r : message should be retained.
-s : read message from stdin, sending the entire input as a message.
-S : use SRV lookups to determine which host to connect to.
-t : mqtt topic to publish to.
-u : provide a username (requires MQTT 3.1 broker)
-P : provide a password (requires MQTT 3.1 broker)
--help : display this message.
--quiet : don't print error messages.
--will-payload : payload for the client Will, which is sent by the broker in
case of unexpected disconnection. If not given and will-topic is set, a zero
length message will be sent.
--will-qos : QoS level for the client Will.
--will-retain : if given, make the client Will retained.
--will-topic : the topic on which to publish the client Will.
--cafile : path to a file containing trusted CA certificates to enable
encrypted communication.
--capath : path to a directory containing trusted CA certificates to enable
encrypted communication.
--cert : client certificate for authentication, if required by server.
--key : client private key for authentication, if required by server.
--ciphers : openssl compatible list of TLS ciphers to support.
--tls-version : TLS protocol version, can be one of tlsv1.2 tlsv1.1 or tlsv1.
Defaults to tlsv1.2 if available.
--insecure : do not check that the server certificate hostname matches the
remote hostname. Using this option means that you cannot be sure that the
remote host is the server you wish to connect to and so is insecure. Do not
use this option in a production environment.
--psk : pre-shared-key in hexadecimal (no leading 0x) to enable TLS-PSK mode.
--psk-identity : client identity string for TLS-PSK mode.
See http://mosquitto.org/ for more information.</pre>
</section>
<section data-type="sect1" id="_consume_messages_with_code_mosquitto_sub_code">
<h1>Consume Messages with mosquitto_sub</h1>
<p>The <code>mosquitto_sub</code> command-line tool can be used<a contenteditable="false" data-primary="Mosquitto broker" data-secondary="consuming messages with mosquitto_sub" data-type="indexterm"> </a> to consume MQTT messages.<a contenteditable="false" data-primary="messages" data-secondary="consuming MQTT messages with mosquitto_sub" data-type="indexterm"> </a></p>
<p>The minimal parameters we must pass to the tool are:</p>
<ul>
<li>
<p><code>-h host</code> to specify the host of the MQTT broker</p>
</li>
<li>
<p><code>-t topic</code> to specify the topic to consume from</p>
</li>
</ul>
<p>For example, to consume messages from the topic <code>/mwm/XYZ/alert</code> on the broker hosted on <em>iot.eclipse.org</em>, the command line is:</p>
<pre data-code-language="sh" data-type="programlisting">
$ mosquitto_sub -h iot.eclipse.org -t /mwm/XYZ/alert
...
yellow</pre>
<p>Each message consumed by the tool will be displayed on a new line. You can type <span class="keep-together">Ctrl+c</span> to exit the tool and stop consuming messages.</p>
<p>The full list of the <code>mosquitto_sub</code> parameters is available by calling <code>mosquitto_sub --help</code>:</p>
<pre data-type="programlisting">
$ mosquitto_sub --help
mosquitto_sub is a simple mqtt client that will subscribe to a single topic and print all messages it receives.
mosquitto_sub version 1.3.1 running on libmosquitto 1.3.1.
Usage: mosquitto_sub [-c] [-h host] [-k keepalive] [-p port] [-q qos] [-R] -t topic ...
[-T filter_out]
[-A bind_address] [-S]
[-i id] [-I id_prefix]
[-d] [-N] [--quiet] [-v]
[-u username [-P password]]
[--will-topic [--will-payload payload] [--will-qos qos]
[--will-retain]]
[{--cafile file | --capath dir} [--cert file] [--key file]
[--ciphers ciphers] [--insecure]]
[--psk hex-key --psk-identity identity [--ciphers ciphers]]
mosquitto_sub --help
-A : bind the outgoing socket to this host/ip address. Use to control which interface the client communicates over.
-c : disable 'clean session' (store subscription and pending messages when client disconnects).
-d : enable debug messages.
-h : mqtt host to connect to. Defaults to localhost.
-i : id to use for this client. Defaults to mosquitto_sub_ appended with the process id.
-I : define the client id as id_prefix appended with the process id. Useful for when the broker is using the clientid_prefixes option.
-k : keep alive in seconds for this client. Defaults to 60.
-N : do not add an end of line character when printing the payload.
-p : network port to connect to. Defaults to 1883.
-q : quality of service level to use for the subscription. Defaults to 0.
-R : do not print stale messages (those with retain set).
-S : use SRV lookups to determine which host to connect to.
-t : mqtt topic to subscribe to. May be repeated multiple times.
-u : provide a username (requires MQTT 3.1 broker)
-v : print published messages verbosely.
-P : provide a password (requires MQTT 3.1 broker)
--help : display this message.
--quiet : don't print error messages.
--will-payload : payload for the client Will, which is sent by the broker in case of unexpected disconnection. If not given and will-topic is set, a zero
length message will be sent.
--will-qos : QoS level for the client Will.
--will-retain : if given, make the client Will retained.
--will-topic : the topic on which to publish the client Will.
--cafile : path to a file containing trusted CA certificates to enable
encrypted certificate based communication.
--capath : path to a directory containing trusted CA certificates to
enable encrypted communication.
--cert : client certificate for authentication, if required by server.
--key : client private key for authentication, if required by server.
--ciphers : openssl compatible list of TLS ciphers to support.
--tls-version : TLS protocol version, can be one of tlsv1.2 tlsv1.1 or tlsv1.
Defaults to tlsv1.2 if available.
--insecure : do not check that the server certificate hostname matches the
remote hostname. Using this option means that you cannot be sure that the
remote host is the server you wish to connect to and so is insecure.
Do not use this option in a production environment.
--psk : pre-shared-key in hexadecimal (no leading 0x) to enable TLS-PSK mode.
--psk-identity : client identity string for TLS-PSK mode.
See http://mosquitto.org/ for more information.<a contenteditable="false" data-primary="brokers" data-secondary="Mosquitto broker" data-startref="brokersMos" data-type="indexterm"> </a></pre>
</section>
</section>