[mirror_lxc.git] / doc / api-extensions.md

# API extensions

The changes below were introduced to the LXC API after the 3.0 API was finalized.

They are all backward compatible and can be detected by client tools by
called the `lxc_has_api_extension` function.

## lxc\_log

This introduces a way to initialize a logging instance from the API for a given
container.

## lxc\_config\_item\_is\_supported

This introduces the `lxc_config_item_is_supported` function. It allows users to
check whether their LXC instance supports a given configuration key.

## console\_log

This adds support to container's console log. The console log is implemented as
an efficient ringbuffer.

## reboot2

This adds `reboot2()` as a new API extension. This function properly waits
until a reboot succeeded. It takes a timeout argument. When set to `> 0`
`reboot2()` will block until the timeout is reached, if timeout is set to zero
`reboot2()` will not block, if set to -1 `reboot2()` will block indefinitely.

## mount\_injection

This adds support for injecting and removing mounts into/from a running
containers. Two new API functions `mount()` and `umount()` are added. They
mirror the current mount and umount API of the kernel.

## seccomp\_allow\_nesting

This adds support for seccomp filters to be stacked regardless of whether a seccomp profile is
already loaded. This allows nested containers to load their own seccomp profile.

## seccomp\_notify

This adds "notify" as seccomp action that will cause LXC to register a seccomp listener and retrieve
a listener file descriptor from the kernel. When a syscall is made that is registered as "notify"
the kernel will generate a poll event and send a message over the file descriptor.

The caller can read this message, inspect the syscalls including its arguments. Based on this information the caller is expected to send back a message informing the kernel which action to take. Until that message is sent the kernel will block the calling process. The format of the messages to read and sent is documented in seccomp itself.

## network\_veth\_routes

This introduces the `lxc.net.[i].veth.ipv4.route` and `lxc.net.[i].veth.ipv6.route` properties
on `veth` type network interfaces. This allows adding static routes on host to the container's
network interface.
Commit	Line	Data
aafa5f96 CB	1	# API extensions
	2
	3	The changes below were introduced to the LXC API after the 3.0 API was finalized.
	4
	5	They are all backward compatible and can be detected by client tools by
	6	called the `lxc_has_api_extension` function.
	7
	8	## lxc\_log
	9
	10	This introduces a way to initialize a logging instance from the API for a given
	11	container.
	12
	13	## lxc\_config\_item\_is\_supported
	14
	15	This introduces the `lxc_config_item_is_supported` function. It allows users to
	16	check whether their LXC instance supports a given configuration key.
	17
	18	## console\_log
	19
	20	This adds support to container's console log. The console log is implemented as
	21	an efficient ringbuffer.
	22
	23	## reboot2
	24
	25	This adds `reboot2()` as a new API extension. This function properly waits
	26	until a reboot succeeded. It takes a timeout argument. When set to `> 0`
	27	`reboot2()` will block until the timeout is reached, if timeout is set to zero
a8b46a6b	28	`reboot2()` will not block, if set to -1 `reboot2()` will block indefinitely.
aafa5f96 CB	29
	30	## mount\_injection
	31
	32	This adds support for injecting and removing mounts into/from a running
	33	containers. Two new API functions `mount()` and `umount()` are added. They
	34	mirror the current mount and umount API of the kernel.
d4a7da46	35
7b766ddc	36	## seccomp\_allow\_nesting
	37
	38	This adds support for seccomp filters to be stacked regardless of whether a seccomp profile is
	39	already loaded. This allows nested containers to load their own seccomp profile.
	40
	41	## seccomp\_notify
	42
	43	This adds "notify" as seccomp action that will cause LXC to register a seccomp listener and retrieve
	44	a listener file descriptor from the kernel. When a syscall is made that is registered as "notify"
	45	the kernel will generate a poll event and send a message over the file descriptor.
	46
	47	The caller can read this message, inspect the syscalls including its arguments. Based on this information the caller is expected to send back a message informing the kernel which action to take. Until that message is sent the kernel will block the calling process. The format of the messages to read and sent is documented in seccomp itself.
	48
d4a7da46	49	## network\_veth\_routes
	50
	51	This introduces the `lxc.net.[i].veth.ipv4.route` and `lxc.net.[i].veth.ipv6.route` properties
	52	on `veth` type network interfaces. This allows adding static routes on host to the container's
	53	network interface.