Merge pull request #416 from brauner/2020-06-09/fixes

[mirror_lxcfs.git] / README.md

diff --git a/README.md b/README.md
index e2b92eefa62e74cb1bac0ed1e89d3c31588e596b..5272a6c2e6342230133454f85d8706a994022491 100644 (file)
--- a/README.md
+++ b/README.md
@@ -26,7 +26,34 @@ Prior to the implementation of cgroup namespaces by Serge Hallyn `LXCFS` also
 provided a container aware `cgroupfs` tree. It took care that the container
 only had access to cgroups underneath it's own cgroups and thus provided
 additional safety. For systems without support for cgroup namespaces `LXCFS`
-will still provide this feature.
+will still provide this feature but it is mostly considered deprecated.
+
+## Upgrading `LXCFS` without restart
+
+`LXCFS` is split into a shared library (a libtool module, to be precise)
+`liblxcfs` and a simple binary `lxcfs`. When upgrading to a newer version of
+`LXCFS` the `lxcfs` binary will not be restarted. Instead it will detect that
+a new version of the shared library is available and will reload it using
+`dlclose(3)` and `dlopen(3)`. This design was chosen so that the fuse main loop
+that `LXCFS` uses will not need to be restarted. If it were then all containers
+using `LXCFS` would need to be restarted since they would otherwise be left
+with broken fuse mounts.
+
+To force a reload of the shared library at the next possible instance simply
+send `SIGUSR1` to the pid of the running `LXCFS` process. This can be as simple
+as doing:
+
+    kill -s USR1 $(pidof lxcfs)
+
+### musl
+
+To achieve smooth upgrades through shared library reloads `LXCFS` also relies
+on the fact that when `dlclose(3)` drops the last reference to the shared
+library destructors are run and when `dlopen(3)` is called constructors are
+run. While this is true for `glibc` it is not true for `musl` (See the section
+[Unloading libraries](https://wiki.musl-libc.org/functional-differences-from-glibc.html).).
+So users of `LXCFS` on `musl` are advised to restart `LXCFS` completely and all
+containers making use of it.
 
 ## Building
 Build lxcfs as follows:
@@ -61,18 +88,6 @@ lxc.kmsg = 0
 lxc.include = /usr/share/lxc/config/common.conf.d/00-lxcfs.conf
 ```
 
-## Upgrading LXCFS without breaking running containers
-LXCFS is implemented using a simple shared library without any external
-dependencies other than `FUSE`. It is completely reloadable without having to
-umount it. This ensures that container can be kept running even when the shared
-library is upgraded.
-
-To force a reload of the shared library at the next possible instance simply
-send `SIGUSR1` to the pid of the running `LXCFS` process. This can be as simple
-as doing:
-
-    kill -s USR1 $(pidof lxcfs)
-
 ## Using with Docker
 
 ```