Add basic snap documentation.

www/conf.py

@@ -156,6 +156,7 @@ PAGES = (
     ("pages/*.txt", "", "story.tmpl"),
     ("pages/*.html", "", "story.tmpl"),
     ("pages/*.md", "", "story.tmpl"),
+    ("pages/documentation/*.md", "", "story.tmpl"),
     ("man/*.xml", "man", "story.tmpl"),
 )
 

www/pages/documentation.md

@@ -1,7 +1,7 @@
 <!--
 .. title: Documentation
 .. slug: documentation
-.. date: 2018-01-02 09:25:28 UTC
+.. date: 2020-07-06 17:25:28 UTC
 .. tags:
 .. category:
 .. link:
@@ -9,4 +9,6 @@
 .. type: text
 -->
 
-Write your page here.
+* [Using the snap package] - specific instructions on installing and configuring the Mosquitto snap package.
+
+[Using the snap package]:/documentation/using-the-snap/

www/pages/documentation/using-the-snap.md

@@ -0,0 +1,77 @@
+<!--
+.. title: Using the snap package
+.. slug: using-the-snap
+.. date: 2020-06-14 09:25:28 UTC
+.. tags:
+.. category:
+.. link:
+.. description:
+.. type: text
+-->
+
+On Linux systems that have snap support, Mosquitto can be installed from the
+graphical software installer, or with `snap install mosquitto`.
+
+After installing the Mosquitto snap, the Mosquitto broker will be running with
+the default configuration, which means it is listening for connections on port
+1883.
+
+To test the broker, you can use the `mosquitto_pub` and `mosquitto_sub` command
+line utilities, which are also provided in the snap. `mosquitto_pub` allows you
+to publish messages to an MQTT broker, and `mosquitto_sub` allows you to
+subscribe to messages from an MQTT broker. Both tools have a large number of
+options to control how they are used and as such are useful for a wide variety
+of tasks. In this case, we will just use them for some simple testing.
+
+To subscribe to all messages being published to the MQTT broker on the
+`snap/example` topic, use the following command. If your MQTT broker is not
+running on the same machine as `mosquitto_sub`, you will need to change the
+`localhost` argument to match your MQTT broker host or IP address.
+
+```
+mosquitto_sub -h localhost -t 'snap/example' -v
+```
+
+The `-t snap/example` option sets the topic to subscribe to, and can be
+provided multiple times. The `-v` option means to print both the topic of the
+message as well as its payload.
+
+Now to publish a message to the same topic, use the very similar `mosquitto_pub`
+command:
+
+```
+mosquitto_pub -h localhost -t 'snap/example' -m 'Hello from mosquitto_pub'
+```
+
+In this case the `-m` option provides the message payload to be published. If
+everything works as planned, you should see `mosquitto_sub` print
+
+```
+snap/example Hello from mosquitto_pub
+```
+
+This is of course a very simple example, but it does allow testing of the
+broker operation. Other things you may wish to try are subscribing to wildcard
+topics that include `#` or `+`, or subscribing to the `$SYS/#` topic to see
+information the broker is publishing about itself. Beware that the command line
+treats `#` as a special character, and `$SYS` will be expanded as a environment
+variable if you do not surround them with single quotes.
+
+Once you have finished your testing, you will want to configure your broker to
+have encrypted connections and use authentication, possibly configuring
+bridges, which allow different brokers to share topics, or many other options.
+
+To do this, you need to provide a new configuration file. The snap provides an
+example configuration file at
+`/var/snap/mosquitto/common/mosquitto_example.conf`. This file contains all of
+the broker configuration, in a similar manner to the man page. To create your
+own configuration, copy the example file to
+`/var/snap/mosquitto/common/mosquitto.conf` and edit according to your needs.
+
+Any additional files required by the configuration, such as TLS certificates
+and keys, must also be placed in `/var/snap/mosquitto/common/` - in new folders
+if wanted. This directory is the only place accessible by Mosquitto when
+running as a snap.
+
+All other aspects of running Mosquitto are the same as with any other
+installation methods.