|
1 | 1 | # Mosquitto |
2 | 2 |
|
3 | | -## References |
4 | | -- [Docker](https://hub.docker.com/_/eclipse-mosquitto) |
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 | | -- `service.yml` ⇒ ~/IOTstack/.templates/mosquitto/service.yml |
15 | | -- `volumes/mosquitto` ⇒ ~/IOTstack/volumes/mosquitto/ |
16 | | - |
17 | | -## Logging |
18 | | - |
19 | | -Mosquitto logging is controlled by `mosquitto.conf`. This is the default configuration: |
20 | | - |
21 | | -``` |
22 | | -#log_dest file /mosquitto/log/mosquitto.log |
23 | | -# To avoid flash wearing |
24 | | -log_dest stdout |
25 | | -``` |
26 | | - |
27 | | -When `log_dest` is set to `stdout`, you inspect Mosquitto's logs like this: |
28 | | - |
29 | | -``` |
30 | | -$ docker logs mosquitto |
31 | | -``` |
32 | | - |
33 | | -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. |
34 | | - |
35 | | -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: |
36 | | - |
37 | | -``` |
38 | | -log_dest file /mosquitto/log/mosquitto.log |
39 | | -# To avoid flash wearing |
40 | | -#log_dest stdout |
41 | | -``` |
42 | | - |
43 | | -and then restart Mosquitto: |
44 | | - |
45 | | -``` |
46 | | -$ cd ~/IOTstack |
47 | | -$ docker-compose restart mosquitto |
48 | | -``` |
49 | | - |
50 | | -With this configuration, you inspect Mosquitto's logs like this: |
51 | | - |
52 | | -``` |
53 | | -$ tail ~/IOTstack/volumes/mosquitto/log/mosquitto.log |
54 | | -``` |
55 | | - |
56 | | -Logs written to `mosquitto.log` do not disappear when your IOTstack is restarted. They persist until you take action to prune the file. |
57 | | - |
58 | | -## Security |
59 | | - |
60 | | -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. |
61 | | - |
62 | | -Assuming your IOTstack is running: |
63 | | - |
64 | | -1. Open a shell in the mosquitto container: |
65 | | - |
66 | | - ``` |
67 | | - $ docker exec -it mosquitto sh |
68 | | - ``` |
69 | | - |
70 | | -2. In the following, replace «MYUSER» with the username you want to use for controlling access to Mosquitto and then run these commands: |
71 | | - |
72 | | - ``` |
73 | | - $ mosquitto_passwd -c /mosquitto/pwfile/pwfile «MYUSER» |
74 | | - $ exit |
75 | | - ``` |
76 | | - |
77 | | - `mosquitto_passwd` will ask you to type a password and confirm it. |
78 | | - |
79 | | - The path on the right hand side of: |
80 | | - |
81 | | - ``` |
82 | | - -c /mosquitto/pwfile/pwfile |
83 | | - ``` |
84 | | - |
85 | | - is **inside** the container. **Outside** the container, it maps to: |
86 | | - |
87 | | - ``` |
88 | | - ~/IOTstack/volumes/mosquitto/pwfile/pwfile |
89 | | - ``` |
90 | | - |
91 | | - You should be able to see the result of setting a username and password like this: |
92 | | - |
93 | | - ``` |
94 | | - $ cat ~/IOTstack/volumes/mosquitto/pwfile/pwfile |
95 | | - MYUSER:$6$lBYlxjWtLON0fm96$3qgcEyr/nKvxk3C2Jk36kkILJK7nLdIeLhuywVOVkVbJUjBeqUmCLOA/T6qAq2+hyyJdZ52ALTi+onMEEaM0qQ== |
96 | | - $ |
97 | | - ``` |
98 | | - |
99 | | -3. Open `mosquitto.conf` in a text editor. Find this line: |
100 | | - |
101 | | - ``` |
102 | | - #password_file /mosquitto/pwfile/pwfile |
103 | | - ``` |
104 | | - |
105 | | - Remove the # in front of password_file. Save. |
106 | | - |
107 | | -4. Restart Mosquitto: |
108 | | - |
109 | | - ``` |
110 | | - $ cd ~/IOTstack |
111 | | - $ docker-compose restart mosquitto |
112 | | - ``` |
113 | | - |
114 | | -5. Use the new credentials where necessary (eg Node-Red). |
115 | | - |
116 | | -Notes: |
117 | | - |
118 | | -* You can revert to password-disabled state by going back to step 3, re-inserting the "#", then restarting Mosquitto as per step 4. |
119 | | -* 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. |
120 | | - |
121 | | -## Running as root |
122 | | - |
123 | | -By default, the Mosquitto container is launched as root but then downgrades its privileges to run as user ID 1883. |
124 | | - |
125 | | -Mosquitto is unusual because most containers just accept the privileges they were launched with. In most cases, that means containers run as root. |
126 | | - |
127 | | -> <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> |
128 | | -
|
129 | | -You can check how mosquitto has been launched like this: |
130 | | - |
131 | | -``` |
132 | | -$ ps -eo euser,ruser,suser,fuser,comm | grep mosquitto |
133 | | -EUSER RUSER SUSER FUSER COMMAND |
134 | | -1883 1883 1883 1883 mosquitto |
135 | | -``` |
136 | | - |
137 | | -If you have a use-case that needs Mosquitto to run with root privileges: |
138 | | - |
139 | | -1. Open `docker-compose.yml` in a text editor and find this: |
140 | | - |
141 | | - ``` |
142 | | - mosquitto: |
143 | | - … [snip] … |
144 | | - user: "1883" |
145 | | - ``` |
146 | | - |
147 | | - change it to: |
148 | | - |
149 | | - ``` |
150 | | - mosquitto: |
151 | | - … [snip] … |
152 | | - user: "0" |
153 | | - ``` |
154 | | - |
155 | | -2. Edit `mosquitto.conf` to add this line: |
156 | | - |
157 | | - ``` |
158 | | - user root |
159 | | - ``` |
160 | | - |
161 | | -3. Apply the change: |
162 | | - |
163 | | - ``` |
164 | | - $ cd ~/IOTstack |
165 | | - $ docker-compose stop mosquitto |
166 | | - $ docker-compose up -d |
167 | | - ``` |
168 | | - |
169 | | -> <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> |
170 | | -
|
171 | | -## Port 9001 |
172 | | - |
173 | | -In earlier versions of IOTstack, `service.yml` included two port mappings which were included in `docker-compose.yml` when Mosquitto was chosen in the menu: |
174 | | - |
175 | | -``` |
176 | | - ports: |
177 | | - - "1883:1883" |
178 | | - - "9001:9001" |
179 | | -``` |
180 | | - |
181 | | -[Issue 67](https://github.com/SensorsIot/IOTstack/issues/67) explored the topic of port 9001 and showed that: |
182 | | - |
183 | | -* The base image for mosquitto did not expose port 9001; and |
184 | | -* The running container was not listening to port 9001. |
185 | | - |
186 | | -On that basis, the mapping for port 9001 was removed from `service.yml`. |
187 | | - |
188 | | -If you have a use-case that needs port 9001, you can re-enable support by: |
189 | | - |
190 | | -1. Inserting the port mapping under the `mosquitto` definition in `docker-compose.yml`: |
191 | | - |
192 | | - ``` |
193 | | - - "9001:9001" |
194 | | - ``` |
195 | | - |
196 | | -2. Inserting the following lines in `mosquitto.conf`: |
197 | | - |
198 | | - ``` |
199 | | - listener 1883 |
200 | | - listener 9001 |
201 | | - ``` |
202 | | - |
203 | | - You need **both** lines. If you omit 1883 then mosquitto will stop listening to port 1883 and will only listen to port 9001. |
204 | | - |
205 | | -3. Restarting the container: |
206 | | - |
207 | | - ``` |
208 | | - $ cd ~/IOTstack |
209 | | - $ docker-compose up -d |
210 | | - ``` |
211 | | - |
212 | | -Please consider raising an issue to document your use-case. If you think your use-case has general application then please also consider creating a pull request to make the changes permanent. |
| 3 | +Please refer to the [documentation on the master branch](https://sensorsiot.github.io/IOTstack/Containers/Mosquitto/). |
0 commit comments