Why does the documentation say we need priviledged mode for a docker install now?

A new user recently had an issue with configuring their Nortek HUSBZB-1 (a combined zwave and zigbee stick) on a docker install (ie Home Assistant Container), and asked a question about not being able to get it to work on this thread - Debugging Zigbee on Nortek HUSBZB-1 w/Docker on linux/Ubuntu They posted log issues related to the install that stated the following:

Sep  5 11:36:04 chipmunk dockerd[762]: time="2021-09-05T11:36:04.803994908-04:00" level=warning msg="path in container /dev/ttyUSB0 already exists in privileged mode" container=ff9c21f65f7d768dda4a2f999359c0577fa999673a15e5356063f0950ac1f566
Sep  5 11:36:04 chipmunk dockerd[762]: time="2021-09-05T11:36:04.804072798-04:00" level=warning msg="path in container /dev/ttyUSB1 already exists in privileged mode" container=ff9c21f65f7d768dda4a2f999359c0577fa999673a15e5356063f0950ac1f566
Sep  5 11:36:04 chipmunk dockerd[762]: time="2021-09-05T11:36:04.804106409-04:00" level=warning msg="path in container /dev/serial/by-id/usb-Silicon_Labs_HubZ_Smart_Home_Controller_31200456-if00-port0 already exists in privileged mode" container=ff9c21f65f7d768dda4a2f999359c0577fa999673a15e5356063f0950ac1f566
Sep  5 11:36:04 chipmunk dockerd[762]: time="2021-09-05T11:36:04.804143320-04:00" level=warning msg="path in container /dev/serial/by-id/usb-Silicon_Labs_HubZ_Smart_Home_Controller_31200456-if01-port0 already exists in privileged mode" container=ff9c21f65f7d768dda4a2f999359c0577fa999673a15e5356063f0950ac1f566

I’m not exactly sure why the poster on the other thread can’t get their zwave/zigbee stick to work, but the log issue appears to be a direct result of installing the container in with the --privileged:true option while still specifying devices with the --device option in the docker run command/compose.

Looking into this further, as a result of a recent github issue stating a user couldn’t get a zigbee stick to work - https://github.com/home-assistant/home-assistant.io/issues/18014
The documentation was then updated to say a home assistant container install should be installed in privileged mode through this PR - https://github.com/home-assistant/home-assistant.io/pull/18275. The updated documentation on this is here - Linux - Home Assistant

However, further down on the same page in that documentation, it still says that to map devices, you need to use the --device flag - Linux - Home Assistant

This appears inconsistent and will create issues, as demonstrated by the log warnings posted above. Using the --device flag properly should not need the --privileged:true flag. Also, it doesn’t seem necessary and is not best practice to give a container privileged, root access to the OS just to map a USB stick. In addition, if you use --privileged:true you shouldn’t use the --device flag, which will create the log errors posted above. Also, even If you do go with -privileged:true, I think you still need to map the usb devices in the dev directory as a volume (I could be wrong on this though since I’ve never installed a docker container in privileged mode)

I was going to submit an issue to at least suggest fixing the documentation around “Exposing devices” to be consistent with privileged mode, or is it best to just recommend removing -privileged mode and go back to the way it was with needing to specify devices under the --device flag? I’m not sure what the best way to suggest a fix to the documentation would be, or am I missing something here and the docker install documentation is ok? Despite what the documentation says, I’m not personally planning to install Home Assistant in privileged mode. I also don’t map USB drives to Home Assistant, and use other docker containers for that (zwavejs2mqtt with zstick mapped and zigbee2mqtt with zigbee stick mapped).

1 Like

I’ve been using HA Container for a few years (before it was even called that) and I’ve never needed to run in privileged mode.

It works fine right now without it and I pass both of my USB devices (zwave & zigbee sticks) into HA using the --device directive.

I actually thought that the OP in the other thread was running Supervised for some reason until I just went and looked again. OOPS. :neutral_face:

I run HA Container on a Synology NAS. I’ve been running HA in Container since circa v0.45. The only way I have been able to get my Aeotec ZWave Z-Stick Gen 5 to work in HA is by using privileged mode AND mapping the device. If I don’t use privileged mode, the container complains about not having permissions to open the serial port. I can however chmod 777 the device from the command line in an ssh session to the Synology box, but that does not persist across reboots. Additionally, I’d rather trust HA in privileged mode than allow anything on my Synology or that may connect to my Synology to connect to the Z-Stick.

I did have an Aetoec zstick mapped without priviledge mode to Home-assistant with just the device flag before zwavejs2mqtt came along. I only had a couple devices at the time, but I used Home Assistant to turn off the annoying disco light show on the stick. I don’t recall any issues, but I’m running Ubuntu.

At least you confirmed specifying both priviledged and device doesn’t create any issues, and appears necessary even for your case. Probably best to leave the documentation as is and the user can decide to omit priviledged mode if they don’t need it, similar to how some don’t use host networking mode either.

Maybe it’s machine/OS related.

I run my HA on a nuc with Debian as the OS.

Maybe there is something different with synology, etc and the way they pass devices around.

I would not be surprised if Synology does something different or non-standard with their device access. 1) you cannot do a device link by device ID to avoid issues when a device is unplugged and it jumps from ttyACM0 to ttyACM1. The device ID path just does not get created when the device is connected. 2) just look at their scorched earth policy on USB devices in the latest OS (DSM 7). They removed support (drivers/kernel modules) for like 99% of USB devices people would connect to a Synology NAS such as a TV tuner, wireless dongle, etc. One of the many reasons I still have not and probably will not update my NAS.

Anyway, this is getting off topic. I think you’re right, it’s highly host OS dependent. Same can be said for those with issues with a modem manager and needing to make sure it was either disabled or uninstalled to make ZWave work. That’s not applicable to a Synology NAS, but applies to Ubuntu based installs at least.

Strongly disagree that “privileged” should be the default setup, since it basically removes many of the security advantages of running dockerised. While I’ll happily run any container that needs it with host networking, privileged should only be used if it’s absolutely necessary, which does not appear to be the case for most users. This should be documented in a way that indicates in what scenarios privileged mode is required, and leaves it up to the user to decide whether or not to enable it.