|
1 | 1 | # Mosquitto |
| 2 | + |
2 | 3 | ## References |
3 | 4 | - [Docker](https://hub.docker.com/_/eclipse-mosquitto) |
4 | 5 | - [Website](https://mosquitto.org/) |
| 6 | +- [mosquitto.conf](https://mosquitto.org/man/mosquitto-conf-5.html) documentation |
| 7 | +- [Setting up passwords](https://www.youtube.com/watch?v=1msiFQT_flo) video |
| 8 | + |
| 9 | +## Definitions |
| 10 | + |
| 11 | +- `docker-compose.yml` ⇒ ~/IOTstack/docker-compose.yml |
| 12 | +- `mosquitto.conf` ⇒ ~/IOTstack/services/mosquitto/mosquitto.conf |
| 13 | +- `mosquitto.log` ⇒ ~/IOTstack/volumes/mosquitto/log/mosquitto.log |
| 14 | +- `volumes/mosquitto` ⇒ ~/IOTstack/volumes/mosquitto/ |
| 15 | + |
| 16 | +## Logging |
| 17 | + |
| 18 | +Mosquitto logging is controlled by `mosquitto.conf`. This is the default configuration: |
| 19 | + |
| 20 | +``` |
| 21 | +#log_dest file /mosquitto/log/mosquitto.log |
| 22 | +# To avoid flash wearing |
| 23 | +log_dest stdout |
| 24 | +``` |
| 25 | + |
| 26 | +When `log_dest` is set to `stdout`, you inspect Mosquitto's logs like this: |
| 27 | + |
| 28 | +``` |
| 29 | +$ docker logs mosquitto |
| 30 | +``` |
| 31 | + |
| 32 | +Logs written to `stdout` are ephemeral and will disappear when your IOTstack is restarted but this configuration reduces wear and tear on your SD card. |
| 33 | + |
| 34 | +The alternative, which *may* be more appropriate if you are running on an SSD or HD, is to change `mosquitto.conf` to be like this: |
5 | 35 |
|
6 | | -[Setting up passwords](https://www.youtube.com/watch?v=1msiFQT_flo) |
| 36 | +``` |
| 37 | +log_dest file /mosquitto/log/mosquitto.log |
| 38 | +# To avoid flash wearing |
| 39 | +#log_dest stdout |
| 40 | +``` |
| 41 | + |
| 42 | +and then restart Mosquitto: |
| 43 | + |
| 44 | +``` |
| 45 | +$ cd ~/IOTstack |
| 46 | +$ docker-compose restart mosquitto |
| 47 | +``` |
| 48 | + |
| 49 | +With this configuration, you inspect Mosquitto's logs like this: |
| 50 | + |
| 51 | +``` |
| 52 | +$ tail ~/IOTstack/volumes/mosquitto/log/mosquitto.log |
| 53 | +``` |
| 54 | + |
| 55 | +Logs written to `mosquitto.log` do not disappear when your IOTstack is restarted. They persist until you take action to prune the file. |
7 | 56 |
|
8 | 57 | ## Security |
9 | | -By default, the Mosquitto container has no password. You can leave it that way if you like but its always a good idea to secure your services. |
10 | 58 |
|
11 | | -Step 1 |
12 | | -To add the password run `./services/mosquitto/terminal.sh`, I put some helper text in the script. Basically, you use the `mosquitto_passwd -c /mosquitto/config/pwfile MYUSER` command, replacing MYUSER with your username. it will then ask you to type your password and confirm it. exiting with `exit`. |
| 59 | +By default, the Mosquitto container has no password. You can leave it that way if you like but it's always a good idea to secure your services. |
| 60 | + |
| 61 | +Assuming your IOTstack is running: |
| 62 | + |
| 63 | +1. Open a shell in the mosquitto container: |
| 64 | + |
| 65 | + ``` |
| 66 | + $ docker exec -it mosquitto sh |
| 67 | + ``` |
| 68 | + |
| 69 | +2. In the following, replace «MYUSER» with the username you want to use for controlling access to Mosquitto and then run these commands: |
| 70 | + |
| 71 | + ``` |
| 72 | + $ mosquitto_passwd -c /mosquitto/pwfile/pwfile «MYUSER» |
| 73 | + $ exit |
| 74 | + ``` |
| 75 | + |
| 76 | + `mosquitto_passwd` will ask you to type a password and confirm it. |
| 77 | + |
| 78 | + The path on the right hand side of: |
| 79 | + |
| 80 | + ``` |
| 81 | + -c /mosquitto/pwfile/pwfile |
| 82 | + ``` |
| 83 | + |
| 84 | + is **inside** the container. **Outside** the container, it maps to: |
| 85 | + |
| 86 | + ``` |
| 87 | + ~/IOTstack/volumes/mosquitto/pwfile/pwfile |
| 88 | + ``` |
| 89 | + |
| 90 | + You should be able to see the result of setting a username and password like this: |
| 91 | + |
| 92 | + ``` |
| 93 | + $ cat ~/IOTstack/volumes/mosquitto/pwfile/pwfile |
| 94 | + MYUSER:$6$lBYlxjWtLON0fm96$3qgcEyr/nKvxk3C2Jk36kkILJK7nLdIeLhuywVOVkVbJUjBeqUmCLOA/T6qAq2+hyyJdZ52ALTi+onMEEaM0qQ== |
| 95 | + $ |
| 96 | + ``` |
| 97 | + |
| 98 | +3. Open `mosquitto.conf` in a text editor. Find this line: |
| 99 | + |
| 100 | + ``` |
| 101 | + #password_file /mosquitto/pwfile/pwfile |
| 102 | + ``` |
| 103 | + |
| 104 | + Remove the # in front of password_file. Save. |
| 105 | + |
| 106 | +4. Restart Mosquitto: |
| 107 | + |
| 108 | + ``` |
| 109 | + $ cd ~/IOTstack |
| 110 | + $ docker-compose restart mosquitto |
| 111 | + ``` |
| 112 | + |
| 113 | +5. Use the new credentials where necessary (eg Node-Red). |
| 114 | + |
| 115 | +Notes: |
| 116 | + |
| 117 | +* You can revert to password-disabled state by going back to step 3, re-inserting the "#", then restarting Mosquitto as per step 4. |
| 118 | +* If mosquitto keeps restarting after you implement password checking, the most likely explanation will be something wrong with the password file. Implement the advice in the previous note. |
| 119 | + |
| 120 | +## Running as root |
| 121 | + |
| 122 | +By default, the Mosquitto container is launched as root but then downgrades its privileges to run as user ID 1883. |
| 123 | + |
| 124 | +Mosquitto is unusual because most containers just accept the privileges they were launched with. In most cases, that means containers run as root. |
| 125 | + |
| 126 | +> <small>Don't make the mistake of thinking this means that processes running **inside** containers can do whatever they like to your host system. A process inside a container is **contained**. What a process can affect **outside** its container is governed by the port, device and volume mappings you see in the `docker-compose.yml`.</small> |
| 127 | +
|
| 128 | +You can check how mosquitto has been launched like this: |
| 129 | + |
| 130 | +``` |
| 131 | +$ ps -eo euser,ruser,suser,fuser,comm | grep mosquitto |
| 132 | +EUSER RUSER SUSER FUSER COMMAND |
| 133 | +1883 1883 1883 1883 mosquitto |
| 134 | +``` |
| 135 | + |
| 136 | +If you have a use-case that needs Mosquitto to run with root privileges: |
| 137 | + |
| 138 | +1. Open `docker-compose.yml` in a text editor and find this: |
| 139 | + |
| 140 | + ``` |
| 141 | + mosquitto: |
| 142 | + … [snip] … |
| 143 | + user: "1883" |
| 144 | + ``` |
| 145 | + |
| 146 | + change it to: |
| 147 | + |
| 148 | + ``` |
| 149 | + mosquitto: |
| 150 | + … [snip] … |
| 151 | + user: "0" |
| 152 | + ``` |
| 153 | + |
| 154 | +2. Edit `mosquitto.conf` to add this line: |
| 155 | + |
| 156 | + ``` |
| 157 | + user root |
| 158 | + ``` |
| 159 | + |
| 160 | +3. Apply the change: |
13 | 161 |
|
14 | | -Step 2 |
15 | | -Edit the file called services/mosquitto/mosquitto.conf and remove the comment in front of password_file. Restart the container with `docker-compose restart mosquitto`. Type those credentials into Node-red etc. |
| 162 | + ``` |
| 163 | + $ cd ~/IOTstack |
| 164 | + $ docker-compose stop mosquitto |
| 165 | + $ docker-compose up -d |
| 166 | + ``` |
| 167 | + |
| 168 | +> <small>A clean install of Mosquitto via the IOTstack menu sets everything in `volumes/mosquitto` to user and group 1883. That permission structure will still work if you change Mosquitto to run with root privileges. However, running as root **may** have the side effect of changing privilege levels within `volumes/mosquitto`. Keep this in mind if you decide to switch back to running Mosquitto as user 1883 because it is less likely to work.</small> |
0 commit comments