doc/api-extensions.md

   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
  28 `reboot2()` will not block, if set to -1 `reboot2()` will block indefinitely.
  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.
  35
  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
  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.
  54
  55 ## network\_ipvlan
  56
  57 This introduces the `ipvlan` network type.
  58
  59 Example usage:
  60
  61 ```
  62 lxc.net[i].type=ipvlan
  63 lxc.net[i].ipvlan.mode=[l3|l3s|l2] (defaults to l3)
  64 lxc.net[i].ipvlan.isolation=[bridge|private|vepa] (defaults to bridge)
  65 lxc.net[i].link=eth0
  66 lxc.net[i].flags=up
  67 ```
  68
  69 ## network\_l2proxy
  70
  71 This introduces the `lxc.net.[i].l2proxy` that can be either `0` or `1`. Defaults to `0`.
  72 This, when used with `lxc.net.[i].link`, will add IP neighbour proxy entries on the linked device
  73 for any IPv4 and IPv6 addresses on the container's network device.
  74
  75 For IPv4 addresses it will check the following sysctl values and fail with an error if not set:
  76
  77 ```
  78 net.ipv4.conf.[link].forwarding=1
  79 ```
  80
  81 For IPv6 addresses it will check the following sysctl values and fail with an error if not set:
  82
  83 ```
  84 net.ipv6.conf.[link].proxy_ndp=1
  85 net.ipv6.conf.[link].forwarding=1
  86 ```
  87
  88 ## network\_gateway\_device\_route
  89
  90 This introduces the ability to specify `lxc.net.[i].ipv4.gateway` and/or
  91 `lxc.net.[i].ipv6.gateway` with a value of `dev` which will cause the default gateway
  92 inside the container to be created as a device route without destination gateway IP needed.
  93 This is primarily intended for use with layer 3 networking devices, such as IPVLAN.
  94
  95 ## network\_phys\_macvlan\_mtu
  96
  97 This introduces the ability to specify a custom MTU for `phys` and `macvlan` devices using the
  98 `lxc.net.[i].mtu` property.