[mirror_lxcfs.git] / README.md

# lxcfs

## Introduction
LXCFS is a small FUSE filesystem written with the intention of making Linux
containers feel more like a virtual machine. It started as a side-project of
`LXC` but is useable by any runtime.

LXCFS will take care that the information provided by crucial files in `procfs`
such as:

```
/proc/cpuinfo
/proc/diskstats
/proc/meminfo
/proc/stat
/proc/swaps
/proc/uptime
```

are container aware such that the values displayed (e.g. in `/proc/uptime`)
really reflect how long the container is running and not how long the host is
running.

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.

## Usage
The recommended command to run lxcfs is:

    sudo mkdir -p /var/lib/lxcfs
    sudo lxcfs /var/lib/lxcfs

A container runtime wishing to use `LXCFS` should then bind mount the
approriate files into the correct places on container startup.

### LXC
In order to use lxcfs with systemd-based containers, you can either use
LXC 1.1 in which case it should work automatically, or otherwise, copy
the `lxc.mount.hook` and `lxc.reboot.hook` files (once built) from this tree to
`/usr/share/lxcfs`, make sure it is executable, then add the
following lines to your container configuration:
```
lxc.mount.auto = cgroup:mixed
lxc.autodev = 1
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)
Commit	Line	Data
	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)