diff --git a/Makefile.am b/Makefile.am index 1c7456d6f4..46799cb1f1 100644 --- a/Makefile.am +++ b/Makefile.am @@ -4375,6 +4375,13 @@ man_pages_autogen += \ man/nm-settings-keyfile.5 \ man/nm-settings.5 +if WITH_OPENVSWITCH +man_pages += man/nm-openvswitch.7 +else +EXTRA_DIST += man/nm-openvswitch.7 +dist_dependencies += man/nm-openvswitch.7 +endif + if CONFIG_PLUGIN_IFCFG_RH man_pages_autogen += man/nm-settings-ifcfg-rh.5 else diff --git a/configure.ac b/configure.ac index 8ff914d0e8..146f7ccd15 100644 --- a/configure.ac +++ b/configure.ac @@ -1296,6 +1296,8 @@ if test "$build_docs" != "yes" -a \ -f "$srcdir"/man/nmcli.1 -a \ -f "$srcdir"/man/nmtui.1 -a \ \ + -f "$srcdir"/man/nm-openvswitch.7 -a \ + \ -f "$srcdir"/man/nm-settings-ifcfg-rh.5 -a \ -f "$srcdir"/man/nm-settings-keyfile.5 -a \ -f "$srcdir"/man/nm-settings.5 -a \ diff --git a/contrib/fedora/rpm/NetworkManager.spec b/contrib/fedora/rpm/NetworkManager.spec index 6dcadf81f3..4778f15042 100644 --- a/contrib/fedora/rpm/NetworkManager.spec +++ b/contrib/fedora/rpm/NetworkManager.spec @@ -577,7 +577,7 @@ fi %dir %{nmlibdir}/VPN %{_mandir}/man1/* %{_mandir}/man5/* -%{_mandir}/man7/* +%{_mandir}/man7/nmcli-examples.7* %{_mandir}/man8/* %dir %{_localstatedir}/lib/NetworkManager %dir %{_sysconfdir}/NetworkManager/system-connections @@ -626,6 +626,7 @@ fi %files ovs %{_libdir}/%{name}/libnm-device-plugin-ovs.so %{systemd_dir}/NetworkManager.service.d/NetworkManager-ovs.conf +%{_mandir}/man7/nm-openvswitch.7* %endif %if %{with ppp} diff --git a/docs/api/Makefile.am b/docs/api/Makefile.am index f5def7b8b8..67f0a22691 100644 --- a/docs/api/Makefile.am +++ b/docs/api/Makefile.am @@ -88,6 +88,7 @@ content_files = \ $(top_builddir)/man/nmcli-examples.xml \ $(top_builddir)/man/nm-settings.xml \ $(top_builddir)/man/nm-settings-keyfile.xml \ + $(top_builddir)/man/nm-openvswitch.xml \ version.xml \ ../../COPYING \ $(NULL) diff --git a/docs/api/network-manager-docs.xml b/docs/api/network-manager-docs.xml index dd5f0e47f5..0002f8ee11 100644 --- a/docs/api/network-manager-docs.xml +++ b/docs/api/network-manager-docs.xml @@ -76,6 +76,7 @@ + diff --git a/man/nm-openvswitch.xml b/man/nm-openvswitch.xml new file mode 100644 index 0000000000..5573046c38 --- /dev/null +++ b/man/nm-openvswitch.xml @@ -0,0 +1,204 @@ + + + +%entities; +]> + + + + + + nm-openvswitch + NetworkManager OpenVSwitch support + + + + nm-openvswitch + 7 + NetworkManager + OpenVSwitch support overview + &NM_VERSION; + + + + nm-openvswitch + overview of NetworkManager OpenVSwitch support + + + + Overview + + NetworkManager includes basic OpenVSwitch support, good enough + to be capable of setting up simple OpenVSwitch configurations. It is not + extensive and does not expose all functionality of OpenVSwitch provides. + For large or complicated deployments users are advised to use native tools + shipped with OpenVSwitch. This document seeks to provide overview of + functionality currently provided by NetworkManager, its capabilities and + limitations. + + First and foremost: NetworkManager applies the configuration by + modifying the OVSDB directly. Its configuration model follows the OVSDB + database model closely and it does not provide the level of abstraction + ovs-vsctl provides. + + In practical terms it means the following: + + + NetworkManager only ever talks to a single OVSDB instance via an + UNIX domain socket. + + + The configuration is made up of Bridges, Ports and + Interfaces. Interfaces are always enslaved to Ports, and Ports are always + enslaved to Bridges. + + + NetworkManager only creates Bridges, Ports and Interfaces + you ask it to. Unlike ovs-vsctl, it doesn't create the + local interface nor its port automatically. + + + You can't enslave Interface directly to a Bridge. You + always need a Port, even if it has just one interface. + + + There are no VLANs. The VLAN tagging is enabled by setting a + ovs-port.tag + property on a Port. + + + There are no bonds either. The bonding is enabled by + enslaving multiple Interfaces to a Port and configured by setting + properties on a port. + + + + + + Bridges + + Bridges are represented by connections of ovs-bridge + type. + Due to the limitations of OVSDB, "empty" Bridges (with no Ports) can't exist. + NetworkManager inserts the records for Bridges into OVSDB when a Port is + enslaved. + + + + + Ports + + Ports are represented by connections of ovs-port + type. + Due to the limitations of OVSDB, "empty" Ports (with no Interfaces) can't + exist. Ports can also be configured to do VLAN tagging or Bonding. + NetworkManager inserts the records for Ports into OVSDB when an Interface is + enslaved. Ports must be enslaved to a Bridge. + + + + Interfaces + + Interfaces are represented by a connections enslaved to a Port. The + system interfaces (that have a corresponding Linux link) have a respective + connection.type + of the link (e.g. "wired", "bond", "dummy", etc.). Other interfaces ("internal" + or "patch" interfaces) are of ovs-interface type. The OVSDB entries are + inserted upon enslavement to a Port. + + + + + + Examples + + Creating a Bridge with a single internal Interface +$ nmcli conn add conn.type ovs-bridge conn.interface bridge0 +Connection 'ovs-bridge-bridge0' (d10fc64d-1d48-4394-a1b8-e1aea72f27d5) successfully added. +$ nmcli conn add conn.type ovs-port conn.interface port0 conn.master bridge0 +Connection 'ovs-port-port0' (5ae22bae-bba4-4815-9ade-7e635633e1f0) successfully added. +$ nmcli conn add conn.type ovs-interface conn.interface iface0 conn.master port0 \ + ipv4.method manual ipv4.address 192.0.2.1/24 +Connection 'ovs-interface-iface0' (3640d2a1-a2fd-4718-92f1-cffadb5b6cdc) successfully added. + + As said above, you need to create a Port even for a single interface. + Also, before you add the Interface, the Bridge and Port devices appear active, + but are not configured in OVSDB yet. You can inspect the results with + ovs-vsctl show. + + + Adding a Linux interface to a Bridge +$ nmcli conn add conn.type ovs-port conn.interface port1 conn.master bridge0 +Connection 'ovs-port-port1' (67d041eb-8e7b-4458-afee-a1d07c9c4552) successfully added. +$ nmcli conn add conn.type ethernet conn.interface eth0 conn.master port1 +Connection 'ovs-slave-eth0' (d459c45c-cf78-4c1c-b4b7-505e71379624) successfully added. + +Again, you need a port. + + + Creating a VLAN +$ nmcli conn add conn.type ovs-port conn.interface port2 conn.master bridge0 ovs-port.tag 120 +Connection 'ovs-port-port2' (3994c093-4ef7-4549-a4fd-627b831c3cb8) successfully added. +$ nmcli conn add conn.type ethernet conn.interface eth1 conn.master port2 +Connection 'ovs-slave-eth1' (099be06e-71ad-484d-8d5a-fcadc5f207f5) successfully added. + + It's just a port with a tag. + + + Creating a Bond +$ nmcli conn add conn.type ovs-port conn.interface bond0 conn.master bridge0 +Connection 'ovs-port-bond0' (d154ebf9-e999-4e1b-a084-a3de53d25d8a) successfully added. +$ nmcli conn add conn.type ethernet conn.interface eth2 conn.master bond0 +Connection 'ovs-slave-eth2' (475ac1bf-30b2-4534-a877-27f33f58b082) successfully added. +$ nmcli conn add conn.type ethernet conn.interface eth3 conn.master bond0 +Connection 'ovs-slave-eth3' (8dedeecb-ed12-482b-b77a-24a4fb835136) successfully added. + + It's just a Port with multiple interfaces. See nm-settings manual for + Bonding options you can use with "nmcli c add" or "nmcli c modify". You could + even set a VLAN tag on the same Port to do VLAN tagging and bonding at the same + time. + + + + + Bugs + + + + Not all OpenVSwitch capabilities are supported. + + + OpenVSwitch devices don't expose many useful properties on D-Bus. + + + Probably many more. + + + + See Also + + RFC 7047: The Open vSwitch Database Management Protocol, + ovs-vsctl8, + ovs-vswitchd.conf.db5, + nm-settings5, + nmcli1 + + +