diff --git a/README.md b/README.md index ec15f7982..1790e1b45 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ [![Build Status](https://travis-ci.org/containernetworking/plugins.svg?branch=master)](https://travis-ci.org/containernetworking/plugins) # plugins -Some CNI network plugins, maintained by the containernetworking team. For more information, see the individual READMEs. +Some CNI network plugins, maintained by the containernetworking team. For more information, see the [CNI website](https://www.cni.dev). Read [CONTRIBUTING](CONTRIBUTING.md) for build and test instructions. diff --git a/plugins/ipam/dhcp/README.md b/plugins/ipam/dhcp/README.md index 8b46180fd..677cbc098 100644 --- a/plugins/ipam/dhcp/README.md +++ b/plugins/ipam/dhcp/README.md @@ -1,39 +1,4 @@ -# dhcp plugin -## Overview +This document has moved to the [containernetworking/cni.dev](https://github.com/containernetworking/cni.dev) repo. -With dhcp plugin the containers can get an IP allocated by a DHCP server already running on your network. -This can be especially useful with plugin types such as [macvlan](../../main/macvlan/README.md). -Because a DHCP lease must be periodically renewed for the duration of container lifetime, a separate daemon is required to be running. -The same plugin binary can also be run in the daemon mode. - -## Operation -To use the dhcp IPAM plugin, first launch the dhcp daemon: - -``` -# Make sure the unix socket has been removed -$ rm -f /run/cni/dhcp.sock -$ ./dhcp daemon -``` - -If given `-pidfile ` arguments after 'daemon', the dhcp plugin will write -its PID to the given file. -If given `-hostprefix ` arguments after 'daemon', the dhcp plugin will use this prefix for DHCP socket as `/run/cni/dhcp.sock`. You can use this prefix for references to the host filesystem, e.g. to access netns and the unix socket. - -Alternatively, you can use systemd socket activation protocol. -Be sure that the .socket file uses /run/cni/dhcp.sock as the socket path. - -With the daemon running, containers using the dhcp plugin can be launched. - -## Example configuration - -``` -{ - "ipam": { - "type": "dhcp", - } -} - -## Network configuration reference - -* `type` (string, required): "dhcp" +You can find it online here: https://cni.dev/plugins/ipam/dhcp/ diff --git a/plugins/ipam/host-local/README.md b/plugins/ipam/host-local/README.md index ee81c8641..0f720a96f 100644 --- a/plugins/ipam/host-local/README.md +++ b/plugins/ipam/host-local/README.md @@ -1,142 +1,4 @@ -# host-local IP address management plugin -host-local IPAM allocates IPv4 and IPv6 addresses out of a specified address range. Optionally, -it can include a DNS configuration from a `resolv.conf` file on the host. +This document has moved to the [containernetworking/cni.dev](https://github.com/containernetworking/cni.dev) repo. -## Overview - -host-local IPAM plugin allocates ip addresses out of a set of address ranges. -It stores the state locally on the host filesystem, therefore ensuring uniqueness of IP addresses on a single host. - -The allocator can allocate multiple ranges, and supports sets of multiple (disjoint) -subnets. The allocation strategy is loosely round-robin within each range set. - -## Example configurations - -Note that the key `ranges` is a list of range sets. That is to say, the length -of the top-level array is the number of addresses returned. The second-level -array is a set of subnets to use as a pool of possible addresses. - -This example configuration returns 2 IP addresses. - -```json -{ - "ipam": { - "type": "host-local", - "ranges": [ - [ - { - "subnet": "10.10.0.0/16", - "rangeStart": "10.10.1.20", - "rangeEnd": "10.10.3.50", - "gateway": "10.10.0.254" - }, - { - "subnet": "172.16.5.0/24" - } - ], - [ - { - "subnet": "3ffe:ffff:0:01ff::/64", - "rangeStart": "3ffe:ffff:0:01ff::0010", - "rangeEnd": "3ffe:ffff:0:01ff::0020" - } - ] - ], - "routes": [ - { "dst": "0.0.0.0/0" }, - { "dst": "192.168.0.0/16", "gw": "10.10.5.1" }, - { "dst": "3ffe:ffff:0:01ff::1/64" } - ], - "dataDir": "/run/my-orchestrator/container-ipam-state" - } -} -``` - -Previous versions of the `host-local` allocator did not support the `ranges` -property, and instead expected a single range on the top level. This is -deprecated but still supported. -```json -{ - "ipam": { - "type": "host-local", - "subnet": "3ffe:ffff:0:01ff::/64", - "rangeStart": "3ffe:ffff:0:01ff::0010", - "rangeEnd": "3ffe:ffff:0:01ff::0020", - "routes": [ - { "dst": "3ffe:ffff:0:01ff::1/64" } - ], - "resolvConf": "/etc/resolv.conf" - } -} -``` - -We can test it out on the command-line: - -```bash -$ echo '{ "cniVersion": "0.3.1", "name": "examplenet", "ipam": { "type": "host-local", "ranges": [ [{"subnet": "203.0.113.0/24"}], [{"subnet": "2001:db8:1::/64"}]], "dataDir": "/tmp/cni-example" } }' | CNI_COMMAND=ADD CNI_CONTAINERID=example CNI_NETNS=/dev/null CNI_IFNAME=dummy0 CNI_PATH=. ./host-local - -``` - -```json -{ - "ips": [ - { - "version": "4", - "address": "203.0.113.2/24", - "gateway": "203.0.113.1" - }, - { - "version": "6", - "address": "2001:db8:1::2/64", - "gateway": "2001:db8:1::1" - } - ], - "dns": {} -} -``` - -## Network configuration reference - -* `type` (string, required): "host-local". -* `routes` (string, optional): list of routes to add to the container namespace. Each route is a dictionary with "dst" and optional "gw" fields. If "gw" is omitted, value of "gateway" will be used. -* `resolvConf` (string, optional): Path to a `resolv.conf` on the host to parse and return as the DNS configuration -* `dataDir` (string, optional): Path to a directory to use for maintaining state, e.g. which IPs have been allocated to which containers -* `ranges`, (array, required, nonempty) an array of arrays of range objects: - * `subnet` (string, required): CIDR block to allocate out of. - * `rangeStart` (string, optional): IP inside of "subnet" from which to start allocating addresses. Defaults to ".2" IP inside of the "subnet" block. - * `rangeEnd` (string, optional): IP inside of "subnet" with which to end allocating addresses. Defaults to ".254" IP inside of the "subnet" block for ipv4, ".255" for IPv6 - * `gateway` (string, optional): IP inside of "subnet" to designate as the gateway. Defaults to ".1" IP inside of the "subnet" block. - -Older versions of the `host-local` plugin did not support the `ranges` array. Instead, -all the properties in the `range` object were top-level. This is still supported but deprecated. - -## Supported arguments -The following [CNI_ARGS](https://github.com/containernetworking/cni/blob/master/SPEC.md#parameters) are supported: - -* `ip`: request a specific IP address from a subnet. - -The following [args conventions](https://github.com/containernetworking/cni/blob/master/CONVENTIONS.md) are supported: - -* `ips` (array of strings): A list of custom IPs to attempt to allocate - -The following [Capability Args](https://github.com/containernetworking/cni/blob/master/CONVENTIONS.md) are supported: - -* `ipRanges`: The exact same as the `ranges` array - a list of address pools - -### Custom IP allocation -For every requested custom IP, the `host-local` allocator will request that IP -if it falls within one of the `range` objects. Thus it is possible to specify -multiple custom IPs and multiple ranges. - -If any requested IPs cannot be reserved, either because they are already in use -or are not part of a specified range, the plugin will return an error. - - -## Files - -Allocated IP addresses are stored as files in `/var/lib/cni/networks/$NETWORK_NAME`. -The path can be customized with the `dataDir` option listed above. Environments -where IPs are released automatically on reboot (e.g. running containers are not -restored) may wish to specify `/var/run/cni` or another tmpfs mounted directory -instead. +You can find it online here: https://cni.dev/plugins/ipam/host-local/ diff --git a/plugins/ipam/static/README.md b/plugins/ipam/static/README.md index 1dfd029d7..cd54d006a 100644 --- a/plugins/ipam/static/README.md +++ b/plugins/ipam/static/README.md @@ -1,68 +1,4 @@ -# static IP address management plugin -## Overview +This document has moved to the [containernetworking/cni.dev](https://github.com/containernetworking/cni.dev) repo. -static IPAM is very simple IPAM plugin that assigns IPv4 and IPv6 addresses statically to container. This will be useful in debugging purpose and in case of assign same IP address in different vlan/vxlan to containers. - - -## Example configuration - -``` -{ - "ipam": { - "type": "static", - "addresses": [ - { - "address": "10.10.0.1/24", - "gateway": "10.10.0.254" - }, - { - "address": "3ffe:ffff:0:01ff::1/64", - "gateway": "3ffe:ffff:0::1" - } - ], - "routes": [ - { "dst": "0.0.0.0/0" }, - { "dst": "192.168.0.0/16", "gw": "10.10.5.1" }, - { "dst": "3ffe:ffff:0:01ff::1/64" } - ], - "dns": { - "nameservers" : ["8.8.8.8"], - "domain": "example.com", - "search": [ "example.com" ] - } - } -} -``` - -## Network configuration reference - -* `type` (string, required): "static" -* `addresses` (array, optional): an array of ip address objects: - * `address` (string, required): CIDR notation IP address. - * `gateway` (string, optional): IP inside of "subnet" to designate as the gateway. -* `routes` (string, optional): list of routes add to the container namespace. Each route is a dictionary with "dst" and optional "gw" fields. If "gw" is omitted, value of "gateway" will be used. -* `dns` (string, optional): the dictionary with "nameservers", "domain" and "search". - -## Supported arguments - -The following [CNI_ARGS](https://github.com/containernetworking/cni/blob/master/SPEC.md#parameters) are supported: - -* `IP`: request a specific CIDR notation IP addresses, comma separated -* `GATEWAY`: request a specific gateway address - - (example: CNI_ARGS="IP=10.10.0.1/24;GATEWAY=10.10.0.254") - -The plugin also support following [capability argument](https://github.com/containernetworking/cni/blob/master/CONVENTIONS.md). - -* `ips`: Pass IP addresses for CNI interface - -The following [args conventions](https://github.com/containernetworking/cni/blob/master/CONVENTIONS.md#args-in-network-config) are supported: - -* `ips` (array of strings): A list of custom IPs to attempt to allocate, with prefix (e.g. '10.10.0.1/24') - -Notice: If some of above are used at same time, only one will work according to the priorities below - -1. [capability argument](https://github.com/containernetworking/cni/blob/master/CONVENTIONS.md) -1. [args conventions](https://github.com/containernetworking/cni/blob/master/CONVENTIONS.md#args-in-network-config) -1. [CNI_ARGS](https://github.com/containernetworking/cni/blob/master/SPEC.md#parameters) +You can find it online here: https://cni.dev/plugins/ipam/static/ diff --git a/plugins/main/bridge/README.md b/plugins/main/bridge/README.md index 130dd140a..68a6bf844 100644 --- a/plugins/main/bridge/README.md +++ b/plugins/main/bridge/README.md @@ -1,60 +1,5 @@ -# bridge plugin -## Overview +This document has moved to the [containernetworking/cni.dev](https://github.com/containernetworking/cni.dev) repo. -With bridge plugin, all containers (on the same host) are plugged into a bridge (virtual switch) that resides in the host network namespace. -The containers receive one end of the veth pair with the other end connected to the bridge. -An IP address is only assigned to one end of the veth pair -- one residing in the container. -The bridge itself can also be assigned an IP address, turning it into a gateway for the containers. -Alternatively, the bridge can function purely in L2 mode and would need to be bridged to the host network interface (if other than container-to-container communication on the same host is desired). +You can find it online here: https://cni.dev/plugins/main/bridge/ -The network configuration specifies the name of the bridge to be used. -If the bridge is missing, the plugin will create one on first use and, if gateway mode is used, assign it an IP that was returned by IPAM plugin via the gateway field. - -## Example configuration -``` -{ - "cniVersion": "0.3.1", - "name": "mynet", - "type": "bridge", - "bridge": "mynet0", - "isDefaultGateway": true, - "forceAddress": false, - "ipMasq": true, - "hairpinMode": true, - "ipam": { - "type": "host-local", - "subnet": "10.10.0.0/16" - } -} -``` - -## Example L2-only configuration -``` -{ - "cniVersion": "0.3.1", - "name": "mynet", - "type": "bridge", - "bridge": "mynet0", - "ipam": {} -} -``` - -## Network configuration reference - -* `name` (string, required): the name of the network. -* `type` (string, required): "bridge". -* `bridge` (string, optional): name of the bridge to use/create. Defaults to "cni0". -* `isGateway` (boolean, optional): assign an IP address to the bridge. Defaults to false. -* `isDefaultGateway` (boolean, optional): Sets isGateway to true and makes the assigned IP the default route. Defaults to false. -* `forceAddress` (boolean, optional): Indicates if a new IP address should be set if the previous value has been changed. Defaults to false. -* `ipMasq` (boolean, optional): set up IP Masquerade on the host for traffic originating from this network and destined outside of it. Defaults to false. -* `mtu` (integer, optional): explicitly set MTU to the specified value. Defaults to the value chosen by the kernel. -* `hairpinMode` (boolean, optional): set hairpin mode for interfaces on the bridge. Defaults to false. -* `ipam` (dictionary, required): IPAM configuration to be used for this network. For L2-only network, create empty dictionary. -* `promiscMode` (boolean, optional): set promiscuous mode on the bridge. Defaults to false. -* `vlan` (int, optional): assign VLAN tag. Defaults to none. - -*Note:* The VLAN parameter configures the VLAN tag on the host end of the veth and also enables the vlan_filtering feature on the bridge interface. - -*Note:* To configure uplink for L2 network you need to allow the vlan on the uplink interface by using the following command ``` bridge vlan add vid VLAN_ID dev DEV```. diff --git a/plugins/main/host-device/README.md b/plugins/main/host-device/README.md index 323088006..59e842a18 100644 --- a/plugins/main/host-device/README.md +++ b/plugins/main/host-device/README.md @@ -1,66 +1,5 @@ -# host-device -Move an already-existing device into a container. +This document has moved to the [containernetworking/cni.dev](https://github.com/containernetworking/cni.dev) repo. -## Overview +You can find it online here: https://cni.dev/plugins/main/host-device/ -This simple plugin will move the requested device from the host's network namespace -to the container's. IPAM configuration can be used for this plugin. - -## Network configuration reference - -The device can be specified with any one of four properties: -* `device`: The device name, e.g. `eth0`, `can0` -* `hwaddr`: A MAC address -* `kernelpath`: The kernel device kobj, e.g. `/sys/devices/pci0000:00/0000:00:1f.6` -* `pciBusID`: A PCI address of network device, e.g `0000:00:1f.6` - -For this plugin, `CNI_IFNAME` will be ignored. Upon DEL, the device will be moved back. - -The plugin also supports the following [capability argument](https://github.com/containernetworking/cni/blob/master/CONVENTIONS.md): -* `deviceID`: A PCI address of the network device, e.g `0000:00:1f.6` - -## Example configuration - -A sample configuration with `device` property looks like: - -```json -{ - "cniVersion": "0.3.1", - "type": "host-device", - "device": "enp0s1" -} -``` - -A sample configuration with `pciBusID` property looks like: - -```json -{ - "cniVersion": "0.3.1", - "type": "host-device", - "pciBusID": "0000:3d:00.1" -} -``` - -A sample configuration utilizing `deviceID` runtime configuration looks like: - -1. From operator perspective: - ```json - { - "cniVersion": "0.3.1", - "type": "host-device", - "capabilities": { - "deviceID": true - } - } - ``` -2. From plugin perspective: - ```json - { - "cniVersion": "0.3.1", - "type": "host-device", - "runtimeConfig": { - "deviceID": "0000:3d:00.1" - } - } - ``` diff --git a/plugins/main/ipvlan/README.md b/plugins/main/ipvlan/README.md index aa87469a4..dd717dd05f 100644 --- a/plugins/main/ipvlan/README.md +++ b/plugins/main/ipvlan/README.md @@ -1,45 +1,5 @@ -# ipvlan plugin -## Overview +This document has moved to the [containernetworking/cni.dev](https://github.com/containernetworking/cni.dev) repo. -ipvlan is a new [addition](https://lwn.net/Articles/620087/) to the Linux kernel. -Like its cousin macvlan, it virtualizes the host interface. -However unlike macvlan which generates a new MAC address for each interface, ipvlan devices all share the same MAC. -The kernel driver inspects the IP address of each packet when making a decision about which virtual interface should process the packet. +You can find it online here: https://cni.dev/plugins/main/ipvlan/ -Because all ipvlan interfaces share the MAC address with the host interface, DHCP can only be used in conjunction with ClientID (currently not supported by DHCP plugin). - -## Example configuration - -``` -{ - "name": "mynet", - "type": "ipvlan", - "master": "eth0", - "ipam": { - "type": "host-local", - "subnet": "10.1.2.0/24" - } -} -``` - -## Network configuration reference - -* `name` (string, required): the name of the network. -* `type` (string, required): "ipvlan". -* `master` (string, optional): name of the host interface to enslave. Defaults to default route interface. -* `mode` (string, optional): one of "l2", "l3", "l3s". Defaults to "l2". -* `mtu` (integer, optional): explicitly set MTU to the specified value. Defaults to the value chosen by the kernel. -* `ipam` (dictionary, required unless chained): IPAM configuration to be used for this network. - -## Notes - -* `ipvlan` does not allow virtual interfaces to communicate with the master interface. -Therefore the container will not be able to reach the host via `ipvlan` interface. -Be sure to also have container join a network that provides connectivity to the host (e.g. `ptp`). -* A single master interface can not be enslaved by both `macvlan` and `ipvlan`. -* For IP allocation schemes that cannot be interface agnostic, the ipvlan plugin -can be chained with an earlier plugin that handles this logic. If `master` is -omitted, then the previous Result must contain a single interface name for the -ipvlan plugin to enslave. If `ipam` is omitted, then the previous Result is used -to configure the ipvlan interface. diff --git a/plugins/main/macvlan/README.md b/plugins/main/macvlan/README.md index 6a1437247..f3a81dfb7 100644 --- a/plugins/main/macvlan/README.md +++ b/plugins/main/macvlan/README.md @@ -1,34 +1,5 @@ -# macvlan plugin -## Overview +This document has moved to the [containernetworking/cni.dev](https://github.com/containernetworking/cni.dev) repo. -[macvlan](http://backreference.org/2014/03/20/some-notes-on-macvlanmacvtap/) functions like a switch that is already connected to the host interface. -A host interface gets "enslaved" with the virtual interfaces sharing the physical device but having distinct MAC addresses. -Since each macvlan interface has its own MAC address, it makes it easy to use with existing DHCP servers already present on the network. +You can find it online here: https://cni.dev/plugins/main/macvlan/ -## Example configuration - -``` -{ - "name": "mynet", - "type": "macvlan", - "master": "eth0", - "ipam": { - "type": "dhcp" - } -} -``` - -## Network configuration reference - -* `name` (string, required): the name of the network -* `type` (string, required): "macvlan" -* `master` (string, optional): name of the host interface to enslave. Defaults to default route interface. -* `mode` (string, optional): one of "bridge", "private", "vepa", "passthru". Defaults to "bridge". -* `mtu` (integer, optional): explicitly set MTU to the specified value. Defaults to the value chosen by the kernel. The value must be \[0, master's MTU\]. -* `ipam` (dictionary, required): IPAM configuration to be used for this network. For interface only without ip address, create empty dictionary. - -## Notes - -* If you are testing on a laptop, please remember that most wireless cards do not support being enslaved by macvlan. -* A single master interface can not be enslaved by both `macvlan` and `ipvlan`. diff --git a/plugins/main/ptp/README.md b/plugins/main/ptp/README.md index 190476e3c..88e327772 100644 --- a/plugins/main/ptp/README.md +++ b/plugins/main/ptp/README.md @@ -1,32 +1,5 @@ -# ptp plugin -## Overview -The ptp plugin creates a point-to-point link between a container and the host by using a veth device. -One end of the veth pair is placed inside a container and the other end resides on the host. -The host-local IPAM plugin can be used to allocate an IP address to the container. -The traffic of the container interface will be routed through the interface of the host. +This document has moved to the [containernetworking/cni.dev](https://github.com/containernetworking/cni.dev) repo. -## Example network configuration +You can find it online here: https://cni.dev/plugins/main/ptp/ -``` -{ - "name": "mynet", - "type": "ptp", - "ipam": { - "type": "host-local", - "subnet": "10.1.1.0/24" - }, - "dns": { - "nameservers": [ "10.1.1.1", "8.8.8.8" ] - } -} -``` - -## Network configuration reference - -* `name` (string, required): the name of the network -* `type` (string, required): "ptp" -* `ipMasq` (boolean, optional): set up IP Masquerade on the host for traffic originating from ip of this network and destined outside of this network. Defaults to false. -* `mtu` (integer, optional): explicitly set MTU to the specified value. Defaults to value chosen by the kernel. -* `ipam` (dictionary, required): IPAM configuration to be used for this network. -* `dns` (dictionary, optional): DNS information to return as described in the [Result](https://github.com/containernetworking/cni/blob/master/SPEC.md#result). diff --git a/plugins/main/windows/win-bridge/README.md b/plugins/main/windows/win-bridge/README.md index 1ffd5f41f..7fc7d82fe 100644 --- a/plugins/main/windows/win-bridge/README.md +++ b/plugins/main/windows/win-bridge/README.md @@ -1,59 +1,5 @@ -# win-bridge plugin -## Overview +This document has moved to the [containernetworking/cni.dev](https://github.com/containernetworking/cni.dev) repo. -With win-bridge plugin, all containers (on the same host) are plugged into an L2Bridge network that has one endpoint in the host namespace. +You can find it online here: https://cni.dev/plugins/main/win-bridge/ -## Example configuration -``` -{ - "name": "mynet", - "type": "win-bridge", - "ipMasqNetwork": "10.244.0.0/16", - "ipam": { - "type": "host-local", - "subnet": "10.10.0.0/16" - }, - "policies":[ - { - "name":"EndpointPolicy", - "value":{ - "Type":"ROUTE", - "DestinationPrefix":"10.137.198.27/32", - "NeedEncap":true - } - } - ], - "HcnPolicyArgs": [ - { - "Type": "SDNRoute" - "Settings": { - "DestinationPrefix": "11.0.0.0/8", - "NeedEncap": true - } - } - ], - "loopbackDSR": true, - "capabilities": { - "dns": true, - "portMappings": true - } -} -``` - -## Network configuration reference - -* `ApiVersion` (integer, optional): ApiVersion to use, will default to hns. If set to "2" will try to use hcn APIs. -* `name` (string, required): the name of the network. -* `type` (string, required): "win-bridge". -* `ipMasqNetwork` (string, optional): setup NAT if not empty. -* `dns` (dictionary, optional): dns config to be used. - * `Nameservers` (list, optional): list of strings to be used for dns nameservers. - * `Search` (list, optional): list of stings to be used for dns search. -* `ipam` (dictionary, optional): IPAM configuration to be used for this network. -* `Policies` (list, optional): List of hns policies to be used (only used when ApiVersion is < 2). -* `HcnPolicyArgs` (list, optional): List of hcn policies to be used (only used when ApiVersion is 2). -* `loopbackDSR` (bool, optional): If true, will add a policy to allow the interface to support loopback direct server return. -* `capabilities` (dictionary, optional): Runtime capabilities to enable. - * `dns` (boolean, optional): If true, will take the dns config supplied by the runtime and override other settings. - * `portMappings` (boolean, optional): If true, will handle HostPort<>ContainerPort mapping using NAT HNS Policies \ No newline at end of file diff --git a/plugins/main/windows/win-overlay/README.md b/plugins/main/windows/win-overlay/README.md index c2ee9f4b8..7c7d6f5a3 100644 --- a/plugins/main/windows/win-overlay/README.md +++ b/plugins/main/windows/win-overlay/README.md @@ -1,38 +1,5 @@ -# win-overlay plugin -## Overview +This document has moved to the [containernetworking/cni.dev](https://github.com/containernetworking/cni.dev) repo. -With win-overlay plugin, all containers (on the same host) are plugged into an Overlay network based on VXLAN encapsulation. +You can find it online here: https://cni.dev/plugins/main/win-overlay/ -## Example configuration -``` -{ - "name": "mynet", - "type": "win-overlay", - "ipMasq": true, - "endpointMacPrefix": "0E-2A", - "ipam": { - "type": "host-local", - "subnet": "10.10.0.0/16" - }, - "loopbackDSR": true, - "capabilites": { - "dns": true - } -} -``` - -## Network configuration reference - -* `name` (string, required): the name of the network. -* `type` (string, required): "win-overlay". -* `ipMasq` (bool, optional): the inverse of `$FLANNEL_IPMASQ`, setup NAT for the hnsNetwork subnet. -* `dns` (dictionary, optional): dns config to be used. - * `Nameservers` (list, optional): list of strings to be used for dns nameservers. - * `Search` (list, optional): list of stings to be used for dns search. -* `endpointMacPrefix` (string, optional): set to the MAC prefix configured for Flannel. -* `Policies` (list, optional): List of hns policies to be used. -* `ipam` (dictionary, required): IPAM configuration to be used for this network. -* `loopbackDSR` (bool, optional): If true, will add a policy to allow the interface to support loopback direct server return. -* `capabilities` (dictionary, optional): runtime capabilities to be parsed and injected by runtime. - * `dns` (boolean, optional): If true, will take the dns config supplied by the runtime and override other settings. \ No newline at end of file diff --git a/plugins/meta/bandwidth/README.md b/plugins/meta/bandwidth/README.md index 3fa49acbe..a9c2dbde1 100644 --- a/plugins/meta/bandwidth/README.md +++ b/plugins/meta/bandwidth/README.md @@ -1,64 +1,5 @@ -# bandwidth plugin -## Overview +This document has moved to the [containernetworking/cni.dev](https://github.com/containernetworking/cni.dev) repo. -This plugin provides a way to use and configure Linux's Traffic control (tc) subystem. tc encompasses the sets of mechanisms and operations by which packets are queued for transmission/reception on a network interface. +You can find it online here: https://cni.dev/plugins/meta/bandwidth/ -This plugin configures a token bucket filter (tbf) queuing discipline (qdisc) on both ingress and egress traffic. Resulting in traffic being shaped when reading / writing. - -Due to limitations on tc shaping rules for ingress, this plugin creates an Intermediate Functional Block device (ifb) to redirect packets from the host interface. tc tbf is then applied to the ifb device. The packets that were redirected to the ifb devices, are written OUT (and shaped) to the host interface. - -This plugin is only useful when used in addition to other plugins. - -## Chaining - -The bandwidth plugin applies traffic shaping to interfaces (as described above) created by previously applied plugins. - -The following is an example [json configuration list](https://github.com/containernetworking/cni/blob/master/SPEC.md#network-configuration-list-runtime-examples) for creating a `ptp` between the host -> container via veth interfaces, whereby traffic is shaped by the `bandwidth` plugin: - -```json -{ - "cniVersion": "0.3.1", - "name": "mynet", - "plugins": [ - { - "type": "ptp", - "ipMasq": true, - "mtu": 512, - "ipam": { - "type": "host-local", - "subnet": "10.0.0.0/24" - }, - "dns": { - "nameservers": [ "10.1.0.1" ] - } - }, - { - "name": "slowdown", - "type": "bandwidth", - "ingressRate": 123, - "ingressBurst": 456, - "egressRate": 123, - "egressBurst": 456 - } - ] -} -``` - -The result is an `ifb` device in the host namespace redirecting to the `host-interface`, with `tc tbf` applied on the `ifb` device and the `container-interface` - -## Network configuration reference -* ingressRate: is the rate in bps at which traffic can enter an interface. (See http://man7.org/linux/man-pages/man8/tbf.8.html) -* ingressBurst: is the maximum amount in bits that tokens can be made available for instantaneously. (See http://man7.org/linux/man-pages/man8/tbf.8.html) -* egressRate: is the rate in bps at which traffic can leave an interface. (See http://man7.org/linux/man-pages/man8/tbf.8.html) -* egressBurst: is the maximum amount in bits that tokens can be made available for instantaneously. (See http://man7.org/linux/man-pages/man8/tbf.8.html) - -Both ingressRate and ingressBurst must be set in order to limit ingress bandwidth. If neither one is set, then ingress bandwidth is not limited. -Both egressRate and egressBurst must be set in order to limit egress bandwidth. If neither one is set, then egress bandwidth is not limited. - - -## tc tbf documentation - -- [tldp traffic control](http://tldp.org/HOWTO/Traffic-Control-HOWTO/components.html) -- [man tbf](http://man7.org/linux/man-pages/man8/tbf.8.html) -- [tc ingress and ifb mirroring](https://serverfault.com/questions/350023/tc-ingress-policing-and-ifb-mirroring) diff --git a/plugins/meta/firewall/README.md b/plugins/meta/firewall/README.md index 86552f615..ef8de4495 100644 --- a/plugins/meta/firewall/README.md +++ b/plugins/meta/firewall/README.md @@ -1,149 +1,5 @@ -# firewall plugin -## Overview +This document has moved to the [containernetworking/cni.dev](https://github.com/containernetworking/cni.dev) repo. -This plugin creates firewall rules to allow traffic to/from container IP address via the host network . -It does not create any network interfaces and therefore does not set up connectivity by itself. -It is intended to be used as a chained plugins. +You can find it online here: https://cni.dev/plugins/meta/firewall/ -## Operation -The following network configuration file - -```json -{ - "cniVersion": "0.3.1", - "name": "bridge-firewalld", - "plugins": [ - { - "type": "bridge", - "bridge": "cni0", - "isGateway": true, - "ipMasq": true, - "ipam": { - "type": "host-local", - "subnet": "10.88.0.0/16", - "routes": [ - { "dst": "0.0.0.0/0" } - ] - } - }, - { - "type": "firewall" - } - ] -} -``` - -will allow any IP addresses configured by earlier plugins to send/receive traffic via the host. - -A successful result would simply be an empty result, unless a previous plugin passed a previous result, in which case this plugin will return that previous result. - -## Backends - -This plugin supports multiple firewall backends that implement the desired functionality. -Available backends include `iptables` and `firewalld` and may be selected with the `backend` key. -If no `backend` key is given, the plugin will use firewalld if the service exists on the D-Bus system bus. -If no firewalld service is found, it will fall back to iptables. - -## firewalld backend rule structure -When the `firewalld` backend is used, this example will place the IPAM allocated address for the container (e.g. 10.88.0.2) into firewalld's `trusted` zone, allowing it to send/receive traffic. - - -A sample standalone config list (with the file extension .conflist) using firewalld backend might -look like: - -```json -{ - "cniVersion": "0.3.1", - "name": "bridge-firewalld", - "plugins": [ - { - "type": "bridge", - "bridge": "cni0", - "isGateway": true, - "ipMasq": true, - "ipam": { - "type": "host-local", - "subnet": "10.88.0.0/16", - "routes": [ - { "dst": "0.0.0.0/0" } - ] - } - }, - { - "type": "firewall", - "backend": "firewalld" - } - ] -} -``` - - -`FORWARD_IN_ZONES_SOURCE` chain: -- `-d 10.88.0.2 -j FWDI_trusted` - -`CNI_FORWARD_OUT_ZONES_SOURCE` chain: -- `-s 10.88.0.2 -j FWDO_trusted` - - -## iptables backend rule structure - -A sample standalone config list (with the file extension .conflist) using iptables backend might -look like: - -```json -{ - "cniVersion": "0.3.1", - "name": "bridge-firewalld", - "plugins": [ - { - "type": "bridge", - "bridge": "cni0", - "isGateway": true, - "ipMasq": true, - "ipam": { - "type": "host-local", - "subnet": "10.88.0.0/16", - "routes": [ - { "dst": "0.0.0.0/0" } - ] - } - }, - { - "type": "firewall", - "backend": "iptables" - } - ] -} -``` - -When the `iptables` backend is used, the above example will create two new iptables chains in the `filter` table and add rules that allow the given interface to send/receive traffic. - -### FORWARD -A new chain, CNI-FORWARD is added to the FORWARD chain. CNI-FORWARD is the chain where rules will be added -when containers are created and from where rules will be removed when containers terminate. - -`FORWARD` chain: -- `-j CNI-FORWARD` - -CNI-FORWARD will have a pair of rules added, one for each direction, using the IPAM assigned IP address -of the container as shown: - -`CNI-FORWARD` chain: -- `-s 10.88.0.2 -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT` -- `-d 10.88.0.2 -j ACCEPT` - -The `CNI-FORWARD` chain first sends all traffic to `CNI-ADMIN` chain, which is intended as an user-controlled chain for custom rules that run prior to rules managed by the `firewall` plugin. The `firewall` plugin does not add, delete or modify rules in the `CNI-ADMIN` chain. - -`CNI-FORWARD` chain: -- `-j CNI-ADMIN` - -The chain name `CNI-ADMIN` can be overridden by specifying `iptablesAdminChainName` in the plugin configuration - -``` - { - "type": "firewall", - "backend": "iptables", - "iptablesAdminChainName": "SOME-OTHER-CHAIN-NAME", - } -``` diff --git a/plugins/meta/flannel/README.md b/plugins/meta/flannel/README.md index a74f92471..18f9d5520 100644 --- a/plugins/meta/flannel/README.md +++ b/plugins/meta/flannel/README.md @@ -1,140 +1,5 @@ -# flannel plugin -## Overview -This plugin is designed to work in conjunction with [flannel](https://github.com/coreos/flannel), a network fabric for containers. -When flannel daemon is started, it outputs a `/run/flannel/subnet.env` file that looks like this: -``` -FLANNEL_NETWORK=10.1.0.0/16 -FLANNEL_SUBNET=10.1.17.1/24 -FLANNEL_MTU=1472 -FLANNEL_IPMASQ=true -``` +This document has moved to the [containernetworking/cni.dev](https://github.com/containernetworking/cni.dev) repo. -This information reflects the attributes of flannel network on the host. -The flannel CNI plugin uses this information to configure another CNI plugin, such as bridge plugin. +You can find it online here: https://cni.dev/plugins/meta/flannel/ -## Operation -Given the following network configuration file and the contents of `/run/flannel/subnet.env` above, -``` -{ - "name": "mynet", - "type": "flannel" -} -``` -the flannel plugin will generate another network configuration file: -``` -{ - "name": "mynet", - "type": "bridge", - "mtu": 1472, - "ipMasq": false, - "isGateway": true, - "ipam": { - "type": "host-local", - "subnet": "10.1.17.0/24" - } -} -``` - -It will then invoke the bridge plugin, passing it the generated configuration. - -As can be seen from above, the flannel plugin, by default, will delegate to the bridge plugin. -If additional configuration values need to be passed to the bridge plugin, it can be done so via the `delegate` field: -``` -{ - "name": "mynet", - "type": "flannel", - "delegate": { - "bridge": "mynet0", - "mtu": 1400 - } -} -``` - -This supplies a configuration parameter to the bridge plugin -- the created bridge will now be named `mynet0`. -Notice that `mtu` has also been specified and this value will not be overwritten by flannel plugin. - -Additionally, the `delegate` field can be used to select a different kind of plugin altogether. -To use `ipvlan` instead of `bridge`, the following configuration can be specified: - -``` -{ - "name": "mynet", - "type": "flannel", - "delegate": { - "type": "ipvlan", - "master": "eth0" - } -} -``` - -The `ipam` part of the network configuration generated for the delegated plugin, can also be customized by adding a base `ipam` section to the input flannel network configuration. This `ipam` element is then updated with the flannel subnet, a route to the flannel network and, unless provided, an `ipam` `type` set to `host-local` before being provided to the delegated plugin. - -## Network configuration reference - -* `name` (string, required): the name of the network -* `type` (string, required): "flannel" -* `subnetFile` (string, optional): full path to the subnet file written out by flanneld. Defaults to /run/flannel/subnet.env -* `dataDir` (string, optional): path to directory where plugin will store generated network configuration files. Defaults to `/var/lib/cni/flannel` -* `delegate` (dictionary, optional): specifies configuration options for the delegated plugin. -* `ipam` (dictionary, optional, Linux only): when specified, is used as basis to construct the `ipam` section of the delegated plugin configuration. - -flannel plugin will always set the following fields in the delegated plugin configuration: - -* `name`: value of its "name" field. -* `ipam`: based on the received `ipam` section if present, with a `type` defaulting to `host-local`, a `subnet` set to `$FLANNEL_SUBNET` and (Linux only) a `routes` element assembled from the routes listed in the received `ipam` element and a route to the flannel network. Other fields present in the input `ipam` section will be transparently provided to the delegate. - -flannel plugin will set the following fields in the delegated plugin configuration if they are not present: -* `ipMasq`: the inverse of `$FLANNEL_IPMASQ` -* `mtu`: `$FLANNEL_MTU` - -Additionally, for the bridge plugin, `isGateway` will be set to `true`, if not present. - -One use case of the `ipam` configuration is to allow adding back the routes to the cluster services and/or to the hosts when using `isDefaultGateway=false`. In that case, the bridge plugin does not install a default route and, as a result, only pod-to-pod connectivity would be available. - -## Windows Support (Experimental) -This plugin supports delegating to the windows CNI plugins (overlay.exe, l2bridge.exe) to work in conjunction with [Flannel on Windows](https://github.com/coreos/flannel/issues/833). -Flannel sets up an [HNS Network](https://docs.microsoft.com/en-us/virtualization/windowscontainers/container-networking/architecture) in L2Bridge mode for host-gw and in Overlay mode for vxlan. - -The following fields must be set in the delegated plugin configuration: -* `name` (string, required): the name of the network (must match the name in Flannel config / name of the HNS network) -* `type` (string, optional): set to `win-l2bridge` by default. Can be set to `win-overlay` or other custom windows CNI -* `ipMasq`: the inverse of `$FLANNEL_IPMASQ` -* `endpointMacPrefix` (string, optional): required for `win-overlay` mode, set to the MAC prefix configured for Flannel -* `clusterNetworkPrefix` (string, optional): required for `win-l2bridge` mode, setup NAT if `ipMasq` is set to true - -For `win-l2bridge`, the Flannel CNI plugin will set: -* `ipam`: "host-local" type will be used with "subnet" set to `$FLANNEL_SUBNET` and gateway as the .2 address in `$FLANNEL_NETWORK` - -For `win-overlay`, the Flannel CNI plugin will set: -* `ipam`: "host-local" type will be used with "subnet" set to `$FLANNEL_SUBNET` and gateway as the .1 address in `$FLANNEL_NETWORK` - -If IPMASQ is true, the Flannel CNI plugin will setup an OutBoundNAT policy and add FLANNEL_SUBNET to any existing exclusions. - -All other delegate config e.g. other HNS endpoint policies in AdditionalArgs will be passed to WINCNI as-is. - -Example VXLAN Flannel CNI config -``` -{ - "name": "mynet", - "type": "flannel", - "delegate": { - "type": "win-overlay", - "endpointMacPrefix": "0E-2A" - } -} -``` - -For this example, Flannel CNI would generate the following config to delegate to the windows CNI when FLANNEL_NETWORK=10.244.0.0/16, FLANNEL_SUBNET=10.244.1.0/24 and IPMASQ=true -``` -{ - "name": "mynet", - "type": "win-overlay", - "endpointMacPrefix": "0E-2A", - "ipMasq": true, - "ipam": { - "subnet": "10.244.1.0/24", - "type": "host-local" - } -} -``` diff --git a/plugins/meta/portmap/README.md b/plugins/meta/portmap/README.md index c879b18bc..ff21962f8 100644 --- a/plugins/meta/portmap/README.md +++ b/plugins/meta/portmap/README.md @@ -1,133 +1,5 @@ -## Port-mapping plugin -This plugin will forward traffic from one or more ports on the host to the -container. It expects to be run as a chained plugin. +This document has moved to the [containernetworking/cni.dev](https://github.com/containernetworking/cni.dev) repo. -## Usage -You should use this plugin as part of a network configuration list. It accepts -the following configuration options: +You can find it online here: https://cni.dev/plugins/meta/portmap/ -* `snat` - boolean, default true. If true or omitted, set up the SNAT chains -* `markMasqBit` - int, (0-31), default 13. The mark bit to use for masquerading (see section SNAT). Cannot be set when `externalSetMarkChain` is used. -* `externalSetMarkChain` - string, default nil. If you already have a Masquerade mark chain (e.g. Kubernetes), specify it here. This will use that instead of creating a separate chain. When this is set, `markMasqBit` must be unspecified. -* `conditionsV4`, `conditionsV6` - array of strings. A list of arbitrary `iptables` -matches to add to the per-container rule. This may be useful if you wish to -exclude specific IPs from port-mapping - -The plugin expects to receive the actual list of port mappings via the -`portMappings` [capability argument](https://github.com/containernetworking/cni/blob/master/CONVENTIONS.md) - -A sample standalone config list for Kubernetes (with the file extension .conflist) might -look like: - -```json -{ - "cniVersion": "0.3.1", - "name": "mynet", - "plugins": [ - { - "type": "ptp", - "ipMasq": true, - "ipam": { - "type": "host-local", - "subnet": "172.16.30.0/24", - "routes": [ - { - "dst": "0.0.0.0/0" - } - ] - } - }, - { - "type": "portmap", - "capabilities": {"portMappings": true}, - "externalSetMarkChain": "KUBE-MARK-MASQ" - } - ] -} -``` - -A configuration file with all options set: -```json -{ - "type": "portmap", - "capabilities": {"portMappings": true}, - "snat": true, - "markMasqBit": 13, - "externalSetMarkChain": "CNI-HOSTPORT-SETMARK", - "conditionsV4": ["!", "-d", "192.0.2.0/24"], - "conditionsV6": ["!", "-d", "fc00::/7"] -} -``` - - - -## Rule structure -The plugin sets up two sequences of chains and rules - one "primary" DNAT -sequence to rewrite the destination, and one additional SNAT sequence that -will masquerade traffic as needed. - - -### DNAT -The DNAT rule rewrites the destination port and address of new connections. -There is a top-level chain, `CNI-HOSTPORT-DNAT` which is always created and -never deleted. Each plugin execution creates an additional chain for ease -of cleanup. So, if a single container exists on IP 172.16.30.2/24 with ports -8080 and 8043 on the host forwarded to ports 80 and 443 in the container, the -rules look like this: - -`PREROUTING`, `OUTPUT` chains: -- `--dst-type LOCAL -j CNI-HOSTPORT-DNAT` - -`CNI-HOSTPORT-DNAT` chain: -- `${ConditionsV4/6} -p tcp --destination-ports 8080,8043 -j CNI-DN-xxxxxx` (where xxxxxx is a function of the ContainerID and network name) - -`CNI-HOSTPORT-SETMARK` chain: -- `-j MARK --set-xmark 0x2000/0x2000` - -`CNI-DN-xxxxxx` chain: -- `-p tcp -s 172.16.30.0/24 --dport 8080 -j CNI-HOSTPORT-SETMARK` (masquerade hairpin traffic) -- `-p tcp -s 127.0.0.1 --dport 8080 -j CNI-HOSTPORT-SETMARK` (masquerade localhost traffic) -- `-p tcp --dport 8080 -j DNAT --to-destination 172.16.30.2:80` (rewrite destination) -- `-p tcp -s 172.16.30.0/24 --dport 8043 -j CNI-HOSTPORT-SETMARK` -- `-p tcp -s 127.0.0.1 --dport 8043 -j CNI-HOSTPORT-SETMARK` -- `-p tcp --dport 8043 -j DNAT --to-destination 172.16.30.2:443` - -New connections to the host will have to traverse every rule, so large numbers -of port forwards may have a performance impact. This won't affect established -connections, just the first packet. - -### SNAT (Masquerade) -Some packets also need to have the source address rewritten: -* connections from localhost -* Hairpin traffic back to the container. - -In the DNAT chain, a bit is set on the mark for packets that need snat. This -chain performs that masquerading. By default, bit 13 is set, but this is -configurable. If you are using other tools that also use the iptables mark, -you should make sure this doesn't conflict. - -Some container runtimes, most notably Kubernetes, already have a set of rules -for masquerading when a specific mark bit is set. If so enabled, the plugin -will use that chain instead. - -`POSTROUTING`: -- `-j CNI-HOSTPORT-MASQ` - -`CNI-HOSTPORT-MASQ`: -- `--mark 0x2000 -j MASQUERADE` - -Because MASQUERADE happens in POSTROUTING, it means that packets with source ip -127.0.0.1 need to first pass a routing boundary before being masqueraded. By -default, that is not allowed in Linux. So, the plugin needs to enable the sysctl -`net.ipv4.conf.IFNAME.route_localnet`, where IFNAME is the name of the host-side -interface that routes traffic to the container. - -There is no equivalent to `route_localnet` for ipv6, so connections to ::1 -will not be portmapped for ipv6. If you need port forwarding from localhost, -your container must have an ipv4 address. - - -## Known issues -- ipsets could improve efficiency -- forwarding from localhost does not work with ipv6. diff --git a/plugins/meta/sbr/README.md b/plugins/meta/sbr/README.md index 622b7ff58..43d136447 100644 --- a/plugins/meta/sbr/README.md +++ b/plugins/meta/sbr/README.md @@ -1,127 +1,5 @@ -# Source based routing plugin -## Introduction +This document has moved to the [containernetworking/cni.dev](https://github.com/containernetworking/cni.dev) repo. -This plugin performs Source Based Routing (SBR). The most common and standard way to -perform routing is to base it purely on the destination. However, in some -applications which are using network separation for traffic management and -security, there is no way to tell *a priori* which interface should be used, -but the application is capable of making the decision. +You can find it online here: https://cni.dev/plugins/meta/sbr/ -As an example, a Telco application might have two networks, a management -network and a SIP (telephony) network for traffic, with rules which state that: - -- SIP traffic (only) must be routed over the SIP network; - -- all other traffic (but no SIP traffic) must be routed over the management - network. - -There is no way of configuring this based on destination IP, since there is no -way of telling whether a destination IP on the internet is (say) an address -used for downloading updated software packages or a remote SIP endpoint. - -Hence Source Based Routing is used. - -- The application explicitly listens on the correct interface for incoming - traffic. - -- When the application wishes to send to an address via the SIP network, it - explicitly binds to the IP of the device on that network. - -- Routes for the SIP interface are configured in a separate routing table, and - a rule is configured to use that table based on the source IP address. - -Note that in most cases there is a management device (the first one) and that -the SBR plugin is called once for each device after the first, leaving the -default routing table applied to the management device. However, this not -mandatory, and source based routing may be configured on any or all of the -devices as appropriate. - -## Usage - -This plugin runs as a chained plugin, and requires the following information -passed in from the previous plugin (which has just set up the network device): - -- What is the network interface in question? - -- What is the IP address (or addresses) of that network interface? - -- What is the default gateway for that interface (if any)? - -It then reads all routes to the network interface in use. - -Here is an example of what the plugin would do. (The `ip` based commands are -implemented in go, but easier to describe via the command line.) Suppose that -it reads that: - -- The interface is `net1`. - -- The IP address on that interface is `192.168.1.209`. - -- The default gateway on that interface is `192.168.1.1`. - -- There is one route configured on that network interface, which is - `192.168.1.0/24`. - -Then the actions it takes are the following. - -- It creates a new routing table, and sets a rule to use it for the IP address in question. - - ip rule add from 192.168.1.209/32 table 100 - -- It adds a route to the default gateway for the relevant table. - - ip route add default via 192.168.1.1 dev net1 table 100 - -- It moves every existing route on the device to the new table. - - ip route del 192.168.1.0/24 dev net1 src 192.168.1.209 - ip route add 192.168.1.0/24 dev net1 src 192.168.1.209 table 100 - -On deletion it: - -- deletes the rule (`ip rule del from 192.168.1.209/32 table 100`), which it - finds by deleting rules relating to IPs on the device which is about to be - deleted. - -- does nothing with routes (since the kernel automatically removes routes when - the device with which they are associated is deleted). - -## Future enhancements and known limitations - -The following are possible future enhancements. - -- The table number is currently selected by starting at 100, then incrementing - the value until an unused table number is found. It might be nice to have an - option to pass the table number as an input. - -- There is no log severity, and there is no logging to file (pending changes to - CNI logging generally). - -- This plugin sets up Source Based Routing, as described above. In future, - there may be a need for a VRF plugin (that uses - [VRF routing](https://www.kernel.org/doc/Documentation/networking/vrf.txt) - instead of source based routing). If and when this happens, it is likely that - the logic would be virtually identical for the plugin, and so the same plugin - might offer either SBR or VRF routing depending on configuration. - -## Configuration - -This plugin must be used as a chained plugin. There are no specific configuration parameters. - -A sample configuration for this plugin acting as a chained plugin after flannel -is the following. - -~~~json -{ - "name": "flannel-sbr", - "cniVersion": "0.3.0", - "plugins": - [ - { "type": "flannel" }, - { - "type": "sbr", - } - ] -} -~~~ diff --git a/plugins/meta/tuning/README.md b/plugins/meta/tuning/README.md index 631194d8f..4b275e3a4 100644 --- a/plugins/meta/tuning/README.md +++ b/plugins/meta/tuning/README.md @@ -1,73 +1,5 @@ -# tuning plugin -## Overview +This document has moved to the [containernetworking/cni.dev](https://github.com/containernetworking/cni.dev) repo. -This plugin can change some system controls (sysctls) and several interface attributes (promiscuous mode, MTU and MAC address) in the network namespace. -It does not create any network interfaces and therefore does not bring connectivity by itself. -It is only useful when used in addition to other plugins. +You can find it online here: https://cni.dev/plugins/meta/tuning/ -## System Controls Operation -The following network configuration file -``` -{ - "name": "mytuning", - "type": "tuning", - "sysctl": { - "net.core.somaxconn": "500" - } -} -``` -will set /proc/sys/net/core/somaxconn to 500. -Other sysctls can be modified as long as they belong to the network namespace (`/proc/sys/net/*`). - -A successful result would simply be: -``` -{ } -``` - -## Network sysctls documentation - -Some network sysctls are documented in the Linux sources: - -- [Documentation/sysctl/net.txt](https://www.kernel.org/doc/Documentation/sysctl/net.txt) -- [Documentation/networking/ip-sysctl.txt](https://www.kernel.org/doc/Documentation/networking/ip-sysctl.txt) -- [Documentation/networking/](https://www.kernel.org/doc/Documentation/networking/) - -## Interface Attribute Operation -The parameters, "mac", "mtu" and "promisc", changes the interface attributes as followings: - -``` -{ - "name": "mytuning", - "type": "tuning", - "promisc": true, - "mac": "c2:b0:57:49:47:f1", - "mtu": 1454 -} -``` - -## Interface attribute configuration reference - -* `mac` (string, optional): MAC address (i.e. hardware address) of interface -* `mtu` (integer, optional): MTU of interface -* `promisc` (bool, optional): Change the promiscuous mode of interface - -## Supported arguments -The following [CNI_ARGS](https://github.com/containernetworking/cni/blob/master/SPEC.md#parameters) are supported: - -* `MAC`: request a specific MAC address for the interface - - (example: CNI_ARGS="IgnoreUnknown=true;MAC=c2:11:22:33:44:55") - -Note: You may add `IgnoreUnknown=true` to allow loose CNI argument verification (see CNI's issue[#560](https://github.com/containernetworking/cni/issues/560)). - -The plugin also support following [capability argument](https://github.com/containernetworking/cni/blob/master/CONVENTIONS.md). - -* `mac`: Pass MAC addresses for CNI interface - -The following [args conventions](https://github.com/containernetworking/cni/blob/master/CONVENTIONS.md#args-in-network-config) are supported: - -* `mac` (string, optional): MAC address (i.e. hardware address) of interface -* `mtu` (integer, optional): MTU of interface -* `promisc` (bool, optional): Change the promiscuous mode of interface -* `sysctl` (object, optional): Change system controls diff --git a/plugins/meta/vrf/README.md b/plugins/meta/vrf/README.md index d2dc64cc1..6201ed032 100644 --- a/plugins/meta/vrf/README.md +++ b/plugins/meta/vrf/README.md @@ -1,53 +1,5 @@ -# vrf plugin -## Overview +This document has moved to the [containernetworking/cni.dev](https://github.com/containernetworking/cni.dev) repo. -This plugin creates a [VRF](https://www.kernel.org/doc/Documentation/networking/vrf.txt) in the network namespace and assigns it the interface passed in the arguments. If the VRF is already present in the namespace, it only adds the interface to it. +You can find it online here: https://cni.dev/plugins/meta/vrf/ -As a table id is mandatory, the plugin generates a new one for each different VRF that is added to the namespace. - -It does not create any network interfaces and therefore does not bring connectivity by itself. -It is only useful when used in addition to other plugins. - -## Operation - -The following network configuration file - -```json -{ - "cniVersion": "0.3.1", - "name": "macvlan-vrf", - "plugins": [ - { - "type": "macvlan", - "master": "eth0", - "ipam": { - "type": "dhcp" - } - }, - { - "type": "vrf", - "vrfname": "blue", - } - ] -} -``` - -will create a VRF named blue inside the target namespace (if not existing), and set it as master of the interface created by the previous plugin. - -## Configuration - -The only configuration is the name of the VRF, as per the following example: - -```json -{ - "type": "vrf", - "vrfname": "blue" -} -``` - -## Supported arguments - -The following [args conventions](https://github.com/containernetworking/cni/blob/master/CONVENTIONS.md#args-in-network-config) are supported: - -* `vrfname` (string, optional): The name of the VRF to be created and to be set as master of the interface