From d0c1d0e93606ac9049fc39011c692abbab14d03d Mon Sep 17 00:00:00 2001 From: David Morel Date: Fri, 4 Jul 2025 11:46:29 +0200 Subject: [PATCH] doc: Add OpenFlow plugin section Document usage of the new xapi plugin to configure OpenFlow rules manually using xe, and reference XO documentation for UI and xo-cli usage. Signed-off-by: David Morel --- docs/networking/networking.md | 104 +++++++++++++++++++++++++++++++++- 1 file changed, 102 insertions(+), 2 deletions(-) diff --git a/docs/networking/networking.md b/docs/networking/networking.md index 0f5a167e..6bc92c51 100644 --- a/docs/networking/networking.md +++ b/docs/networking/networking.md @@ -217,12 +217,112 @@ To be able to encrypt the networks, `openvswitch-ipsec` package must be installe More information available on [XO official documentation for SDN controller](https://xen-orchestra.com/docs/sdn_controller.html). -### OpenFlow rules +### OpenFlow Rules :::tip -This feature is coming very soon! +`xcp-ng-xapi-plugins` >= 0.15.0 is required. To check the version, run `yum info xcp-ng-xapi-plugins`. ::: +Using Open vSwitch OpenFlow rules, you can setup traffic rules limiting some network accesses directly at the hypervisor vswitch level. No need for an additional layer of firewalling or filtering setup or equipment. + +There are 3 ways to configure OpenFlow rules: +- Through [Xen Orchestra](https://docs.xen-orchestra.com/sdn_controller#openflow-rules)'s web UI (currently only available for per VIF rules) +- Using `xo-cli` as explained in the [Xen Orchestra documentation](https://docs.xen-orchestra.com/sdn_controller#xapi-plugin) +- Manually, by using the `xe` command on your hosts + +We recommend using Xen Orchestra or `xo-cli`, depending on your use case. This documentation will focus on how to set up rules manually. + +:::warning +The procedure below explains how to set up rules temporarily, but the rules won't persist after reboot. +::: + +Keep in mind that these steps must be performed on every host where you want the rules applied. For non-cross-pool private networks, you can run the commands from one host for each host UUID in your pool. For cross-pool private networks, repeat the process for each pool involved. + +To set rules manually, you can call the plugin using `xe`: + +``` +xe host-call-plugin host-uuid plugin=sdncontroller.py \ + fn= \ + args:="" [args:…] …` +``` + +The `` parameter can be: +- `add-rule` to add a new rule +- `del-rule` to delete an existing rule +- `dump-flows` to dump the current flow table from Open vSwitch + +#### Adding a rule + +Parameters for adding a rule: +- *bridge*: The name of the bridge to add rule to +- *priority* (optional): A number between 0 and 65535 for the rule priority +- *mac* (optional): The MAC address of the VIF to create the rule for (if not specified, a network-wide rule will be created) +- *ipRange*: An IP or range of IPs in CIDR notation (for example `192.168.1.0/24`) +- *direction*: can be **from**, **to** or **from/to** + - *to*: means the parameters for **port** and **ipRange** are to be used as destination + - *from*: means they will be use as source + - *from/to*: 2 rules will be created, one per direction +- *protocol*: IP, TCP, UDP, ICMP or ARP +- *port*: required for TCP/UDP protocol +- *allow*: If set to false, the packets are dropped. + +Example to block SSH access to/from the 192.168.1.0/24 subnet, for a VM with MAC address `6e:0b:9e:72:ab:c6` on bridge `xenbr0`: + +``` +$ xe host-call-plugin host-uuid plugin=sdncontroller.py \ + fn=add-rule \ + args:bridge="xenbr0" \ + args:mac="6e:0b:9e:72:ab:c6" \ + args:ipRange="192.168.1.0/24" \ + args:direction="from/to" \ + args:protocol="tcp" \ + args:port="22" \ + args:allow="false" +``` + + +#### Deleting a rule + +Parameters for removing a rule: +- *bridge* : The name of the bridge to delete the rule from +- *mac* (optional): The MAC address of the VIF to delete the rule for +- *ipRange*: An IP or range of IPs in CIDR notation, for example `192.168.1.0/24` +- *direction*: can be **from**, **to** or **from/to** + - *to*: means the parameters for **port** and **ipRange** are to be used as destination + - *from*: means they will be use as source + - *from/to*: 2 rules will be created, one per direction +- *protocol*: IP, TCP, UDP, ICMP or ARP +- *port*: required for TCP/UDP protocol + +Example to remove the rule created in the previous section: + +``` +$ xe host-call-plugin host-uuid plugin=sdncontroller.py \ + fn=del-rule \ + args:bridge="xenbr0" \ + args:mac="6e:0b:9e:72:ab:c6" \ + args:ipRange="192.168.1.0/24" \ + args:direction="from/to" \ + args:protocol="tcp" \ + args:port="22" +``` +#### Dumping the flow table + +This command will return all flows entries in the bridge passed as a parameter. +``` +$ xe host-call-plugin host-uuid= plugin=sdncontroller.py fn=dump-flows args:bridge=xenbr0 | jq . +{ + "returncode": 0, + "command": [ + "ovs-ofctl", + "dump-flows", + "xenbr0" + ], + "stderr": "", + "stdout": "NXST_FLOW reply (xid=0x4):\n cookie=0x0, duration=248977.339s, table=0, n_packets=24591786, n_bytes=3278442075, idle_age=0, hard_age=65534, priority=0 actions=NORMAL\n" +} +``` + ### Common errors #### TLS connection issue