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 ```
  19
  20 are container aware such that the values displayed (e.g. in `/proc/uptime`)
  21 really reflect how long the container is running and not how long the host is
  22 running.
  23
  24 Prior to the implementation of cgroup namespaces by Serge Hallyn `LXCFS` also
  25 provided a container aware `cgroupfs` tree. It took care that the container
  26 only had access to cgroups underneath it's own cgroups and thus provided
  27 additional safety. For systems without support for cgroup namespaces `LXCFS`
  28 will still provide this feature.
  29
  30 ## Usage
  31 The recommended command to run lxcfs is:
  32
  33     sudo mkdir -p /var/lib/lxcfs
  34     sudo lxcfs /var/lib/lxcfs
  35
  36 A container runtime wishing to use `LXCFS` should then bind mount the
  37 approriate files into the correct places on container startup.
  38
  39 ### LXC
  40 In order to use lxcfs with systemd-based containers, you can either use
  41 LXC 1.1 in which case it should work automatically, or otherwise, copy
  42 the `lxc.mount.hook` and `lxc.reboot.hook` files (once built) from this tree to
  43 `/usr/share/lxcfs`, make sure it is executable, then add the
  44 following lines to your container configuration:
  45 ```
  46 lxc.mount.auto = cgroup:mixed
  47 lxc.autodev = 1
  48 lxc.kmsg = 0
  49 lxc.include = /usr/share/lxc/config/common.conf.d/00-lxcfs.conf
  50 ```
  51
  52 ## Upgrading LXCFS without breaking running containers
  53 LXCFS is implemented using a simple shared library without any external
  54 dependencies other than `FUSE`. It is completely reloadable without having to
  55 umount it. This ensures that container can be kept running even when the shared
  56 library is upgraded.
  57
  58 To force a reload of the shared library at the next possible instance simply
  59 send `SIGUSR1` to the pid of the running `LXCFS` process. This can be as simple
  60 as doing:
  61
  62     kill -s USR1 $(pidof lxcfs)