diff --git a/blog/2022-05-12-s6-overlay-base-images.md b/blog/2022-05-12-s6-overlay-base-images.md new file mode 100644 index 00000000..022f3884 --- /dev/null +++ b/blog/2022-05-12-s6-overlay-base-images.md @@ -0,0 +1,39 @@ +--- +author: Pascal Vizeli +authorURL: https://twitter.com/pvizeli +authorTwitter: pvizeli +title: S6-Overlay 3.x update on our docker base images +--- + +We started to update our base images to use the new s6-Overlay v3. A [migration article](https://github.com/just-containers/s6-overlay/blob/master/MOVING-TO-V3.md) also explains the new possibilities around this change. This blog post explains the minimal changes needed to be able to use our new base images. + +We have updated our [example add-on](https://github.com/home-assistant/addons-example) to include the new behaviors. + +## Minimum + +Make sure all your executable/script files have the execution permission set on your git repository rootfs folder. You can update the permissions using: + +```sh +$ git update-index --chmod=+x rootfs/etc/service.d/my-service/run +``` + +If you use `finish` scripts in your S6-overlay services, for example, to stop the container on an error, you have to replace the line `s6-svscanctl -t /var/run/s6/services` with `/run/s6/basedir/bin/halt`. + +## AppArmor + +You have to tweak your [AppArmor profile](/docs/add-ons/presentation#apparmor) to get it working with the new s6-Overlay. We updated our documentation with the default profile. The following changes need to be made: + +```txt +# S6-Overlay + /init ix, + /bin/** ix, + /usr/bin/** ix, + /run/{s6,s6-rc*,service}/** ix, + /package/** ix, + /command/** ix, + /etc/services.d/** rwix, + /etc/cont-init.d/** rwix, + /etc/cont-finish.d/** rwix, + /run/{,**} rwk, + /dev/tty rw, +``` diff --git a/docs/add-ons/presentation.md b/docs/add-ons/presentation.md index 3c932e56..e9037ad2 100644 --- a/docs/add-ons/presentation.md +++ b/docs/add-ons/presentation.md @@ -60,41 +60,68 @@ apparmor.txt profile ADDON_SLUG flags=(attach_disconnected,mediate_deleted) { #include - + # Capabilities file, - signal, + signal (send) set=(kill,term,int,hup,cont), # S6-Overlay - /init rix, + /init ix, /bin/** ix, /usr/bin/** ix, - /etc/s6/** rix, - /run/s6/** rwix, + /run/{s6,s6-rc*,service}/** ix, + /package/** ix, + /command/** ix, /etc/services.d/** rwix, /etc/cont-init.d/** rwix, /etc/cont-finish.d/** rwix, - /run/** rwk, + /run/{,**} rwk, + /dev/tty rw, # Bashio /usr/lib/bashio/** ix, - /tmp/** rw, + /tmp/** rwk, # Access to options.json and other files within your addon /data/** rw, - + # Start new profile for service - /usr/bin/myprogram cx, - - profile /usr/bin/myprogram flags=(attach_disconnected,mediate_deleted) { + /usr/bin/myprogram cx -> myprogram, + + profile myprogram flags=(attach_disconnected,mediate_deleted) { #include - + # Receive signals from S6-Overlay - signal receive, + signal (receive) peer=*_ADDON_SLUG, + + # Access to options.json and other files within your addon + /data/** rw, + + # Access to mapped volumes specified in config.json + /share/** rw, + + # Access required for service functionality + /usr/bin/myprogram r, + /bin/bash rix, + /bin/echo ix, + /etc/passwd r, + /dev/tty rw, } } ``` +When working on this for your own add-ons, the following tips should help you get started: + +1. The S6 part of this is fairly standard. You may need to add things to accommodate your setup scripts but generally don't remove anything. +2. If a service being run provides an AppArmor profile, apply that to the service. Always prefer one written by the developers. +3. If there isn't one for a service and you want to make one then do the following: + a. Add minimum required access you're aware of. Things you definitely know the service needs + b. Add `complain` as a flag to the profile + c. Run the add-on and review the audit log with `journalctl _TRANSPORT="audit" -g 'apparmor="ALLOWED"` + d. Add access as necessary until using the add-on does not generate any audit warnings + e. Remove the `complain` flag so ungranted access is DENIED not ALLOWED +4. Repeat #3 when updating the service as new access may be required + ## Ingress Ingress allows users to access the add-on web interface via the Home Assistant UI. Authentication is handled by Home Assistant, so neither the user nor the add-on developer will need to care about the security or port forwarding. Users love this feature! It connects your user directly to the add-on, can provide a seamless UX within Home Assistant and grants your add-on 2 points of security.