]>
Commit | Line | Data |
---|---|---|
60f73aff SG |
1 | # lxcfs |
2 | ||
c397924a | 3 | ## Introduction |
12993ccc CB |
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. | |
758ad80c | 7 | |
12993ccc CB |
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 | |
71f17cd2 | 18 | /sys/devices/system/cpu/online |
12993ccc CB |
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` | |
8b9d0a3f CB |
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 | ||
3f9b9afb CB |
42 | To force a reload of the shared library at the next possible instance simply |
43 | send `SIGUSR1` to the pid of the running `LXCFS` process. This can be as simple | |
44 | as doing: | |
45 | ||
46 | kill -s USR1 $(pidof lxcfs) | |
47 | ||
8b9d0a3f CB |
48 | ### musl |
49 | ||
50 | To achieve smooth upgrades through shared library reloads `LXCFS` also relies | |
51 | on the fact that when `dlclose(3)` drops the last reference to the shared | |
52 | library destructors are run and when `dlopen(3)` is called constructors are | |
53 | run. While this is true for `glibc` it is not true for `musl` (See the section | |
54 | [Unloading libraries](https://wiki.musl-libc.org/functional-differences-from-glibc.html).). | |
3f9b9afb CB |
55 | So users of `LXCFS` on `musl` are advised to restart `LXCFS` completely and all |
56 | containers making use of it. | |
955ce662 | 57 | |
bbf99398 LW |
58 | ## Building |
59 | Build lxcfs as follows: | |
60 | ||
61 | yum install fuse fuse-lib fuse-devel | |
62 | git clone git://github.com/lxc/lxcfs | |
63 | cd lxcfs | |
64 | ./bootstrap.sh | |
65 | ./configure | |
66 | make | |
67 | make install | |
68 | ||
c397924a | 69 | ## Usage |
758ad80c SH |
70 | The recommended command to run lxcfs is: |
71 | ||
c397924a | 72 | sudo mkdir -p /var/lib/lxcfs |
40dd7f1b | 73 | sudo lxcfs /var/lib/lxcfs |
7456f3b5 | 74 | |
12993ccc CB |
75 | A container runtime wishing to use `LXCFS` should then bind mount the |
76 | approriate files into the correct places on container startup. | |
77 | ||
78 | ### LXC | |
7456f3b5 SG |
79 | In order to use lxcfs with systemd-based containers, you can either use |
80 | LXC 1.1 in which case it should work automatically, or otherwise, copy | |
77647bf9 EG |
81 | the `lxc.mount.hook` and `lxc.reboot.hook` files (once built) from this tree to |
82 | `/usr/share/lxcfs`, make sure it is executable, then add the | |
83 | following lines to your container configuration: | |
5b1e45dd | 84 | ``` |
77647bf9 | 85 | lxc.mount.auto = cgroup:mixed |
1a188fcb | 86 | lxc.autodev = 1 |
ef65395d | 87 | lxc.kmsg = 0 |
77647bf9 | 88 | lxc.include = /usr/share/lxc/config/common.conf.d/00-lxcfs.conf |
5b1e45dd | 89 | ``` |
12993ccc | 90 | |
7e60aa1b | 91 | ## Using with Docker |
92 | ||
93 | ``` | |
94 | docker run -it -m 256m --memory-swap 256m \ | |
95 | -v /var/lib/lxcfs/proc/cpuinfo:/proc/cpuinfo:rw \ | |
96 | -v /var/lib/lxcfs/proc/diskstats:/proc/diskstats:rw \ | |
97 | -v /var/lib/lxcfs/proc/meminfo:/proc/meminfo:rw \ | |
98 | -v /var/lib/lxcfs/proc/stat:/proc/stat:rw \ | |
99 | -v /var/lib/lxcfs/proc/swaps:/proc/swaps:rw \ | |
100 | -v /var/lib/lxcfs/proc/uptime:/proc/uptime:rw \ | |
101 | ubuntu:18.04 /bin/bash | |
102 | ``` | |
103 | ||
104 | 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. | |
105 | ||
106 | sudo lxcfs -u /var/lib/lxcfs |