README.md

   1 # lxcfs
   2
   3 ## Introduction
   4 LXCFS is a small FUSE filesystem written with the intention of making Linux
   5 containers feel more like a virtual machine. It started as a side-project of
   6 `LXC` but is useable by any runtime.
   7
   8 LXCFS will take care that the information provided by crucial files in `procfs`
   9 such as:
  10
  11 ```
  12 /proc/cpuinfo
  13 /proc/diskstats
  14 /proc/meminfo
  15 /proc/stat
  16 /proc/swaps
  17 /proc/uptime
  18 /sys/devices/system/cpu/online
  19 ```
  20
  21 are container aware such that the values displayed (e.g. in `/proc/uptime`)
  22 really reflect how long the container is running and not how long the host is
  23 running.
  24
  25 Prior to the implementation of cgroup namespaces by Serge Hallyn `LXCFS` also
  26 provided a container aware `cgroupfs` tree. It took care that the container
  27 only had access to cgroups underneath it's own cgroups and thus provided
  28 additional safety. For systems without support for cgroup namespaces `LXCFS`
  29 will still provide this feature but it is mostly considered deprecated.
  30
  31 ## Upgrading `LXCFS` without restart
  32
  33 `LXCFS` is split into a shared library (a libtool module, to be precise)
  34 `liblxcfs` and a simple binary `lxcfs`. When upgrading to a newer version of
  35 `LXCFS` the `lxcfs` binary will not be restarted. Instead it will detect that
  36 a new version of the shared library is available and will reload it using
  37 `dlclose(3)` and `dlopen(3)`. This design was chosen so that the fuse main loop
  38 that `LXCFS` uses will not need to be restarted. If it were then all containers
  39 using `LXCFS` would need to be restarted since they would otherwise be left
  40 with broken fuse mounts.
  41
  42 ### musl
  43
  44 To achieve smooth upgrades through shared library reloads `LXCFS` also relies
  45 on the fact that when `dlclose(3)` drops the last reference to the shared
  46 library destructors are run and when `dlopen(3)` is called constructors are
  47 run. While this is true for `glibc` it is not true for `musl` (See the section
  48 [Unloading libraries](https://wiki.musl-libc.org/functional-differences-from-glibc.html).).
  49 So users of `LXCFS` on `musl` are advised to restart `LXCFS` completely and
  50 - by extension - all containers.
  51
  52 ## Building
  53 Build lxcfs as follows:
  54
  55     yum install fuse fuse-lib fuse-devel
  56     git clone git://github.com/lxc/lxcfs
  57     cd lxcfs
  58     ./bootstrap.sh
  59     ./configure
  60     make
  61     make install
  62
  63 ## Usage
  64 The recommended command to run lxcfs is:
  65
  66     sudo mkdir -p /var/lib/lxcfs
  67     sudo lxcfs /var/lib/lxcfs
  68
  69 A container runtime wishing to use `LXCFS` should then bind mount the
  70 approriate files into the correct places on container startup.
  71
  72 ### LXC
  73 In order to use lxcfs with systemd-based containers, you can either use
  74 LXC 1.1 in which case it should work automatically, or otherwise, copy
  75 the `lxc.mount.hook` and `lxc.reboot.hook` files (once built) from this tree to
  76 `/usr/share/lxcfs`, make sure it is executable, then add the
  77 following lines to your container configuration:
  78 ```
  79 lxc.mount.auto = cgroup:mixed
  80 lxc.autodev = 1
  81 lxc.kmsg = 0
  82 lxc.include = /usr/share/lxc/config/common.conf.d/00-lxcfs.conf
  83 ```
  84
  85 ## Upgrading LXCFS without breaking running containers
  86 LXCFS is implemented using a simple shared library without any external
  87 dependencies other than `FUSE`. It is completely reloadable without having to
  88 umount it. This ensures that container can be kept running even when the shared
  89 library is upgraded.
  90
  91 To force a reload of the shared library at the next possible instance simply
  92 send `SIGUSR1` to the pid of the running `LXCFS` process. This can be as simple
  93 as doing:
  94
  95     kill -s USR1 $(pidof lxcfs)
  96
  97 ## Using with Docker
  98
  99 ```
 100 docker run -it -m 256m --memory-swap 256m \
 101       -v /var/lib/lxcfs/proc/cpuinfo:/proc/cpuinfo:rw \
 102       -v /var/lib/lxcfs/proc/diskstats:/proc/diskstats:rw \
 103       -v /var/lib/lxcfs/proc/meminfo:/proc/meminfo:rw \
 104       -v /var/lib/lxcfs/proc/stat:/proc/stat:rw \
 105       -v /var/lib/lxcfs/proc/swaps:/proc/swaps:rw \
 106       -v /var/lib/lxcfs/proc/uptime:/proc/uptime:rw \
 107       ubuntu:18.04 /bin/bash
 108  ```
 109
 110  In a system with swap enabled, the parameter "-u" can be used to set all values in "meminfo" that refer to the swap to 0.
 111
 112  sudo lxcfs -u /var/lib/lxcfs