New upstream version 1.9.90 upstream/1.9.90

1 files changed, 236 insertions, 0 deletions

diff --git a/man/nm-openvswitch.7 b/man/nm-openvswitch.7
new file mode 100644
index 00000000..24dde44f
--- /dev/null
+++ b/man/nm-openvswitch.7
@@ -0,0 +1,236 @@
+'\" t
+.\"     Title: nm-openvswitch
+.\"    Author: 
+.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
+.\"      Date: 11/03/2017
+.\"    Manual: OpenVSwitch support overview
+.\"    Source: NetworkManager 1.9.90
+.\"  Language: English
+.\"
+.TH "NM\-OPENVSWITCH" "7" "" "NetworkManager 1\&.9\&.90" "OpenVSwitch support overview"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+nm-openvswitch \- overview of NetworkManager OpenVSwitch support
+.SH "OVERVIEW"
+.PP
+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\&.
+.PP
+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
+\fBovs\-vsctl\fR
+provides\&.
+.PP
+In practical terms it means the following:
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+NetworkManager only ever talks to a single OVSDB instance via an UNIX domain socket\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+The configuration is made up of Bridges, Ports and Interfaces\&. Interfaces are always enslaved to Ports, and Ports are always enslaved to Bridges\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+NetworkManager only creates Bridges, Ports and Interfaces you ask it to\&. Unlike
+\fBovs\-vsctl\fR, it doesn\*(Aqt create the local interface nor its port automatically\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+You can\*(Aqt enslave Interface directly to a Bridge\&. You always need a Port, even if it has just one interface\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+There are no VLANs\&. The VLAN tagging is enabled by setting a
+ovs\-port\&.tag
+property on a Port\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+There are no bonds either\&. The bonding is enabled by enslaving multiple Interfaces to a Port and configured by setting properties on a port\&.
+.RE
+.sp
+.SS "Bridges"
+.PP
+Bridges are represented by connections of ovs\-bridge
+type\&. Due to the limitations of OVSDB, "empty" Bridges (with no Ports) can\*(Aqt exist\&. NetworkManager inserts the records for Bridges into OVSDB when a Port is enslaved\&.
+.SS "Ports"
+.PP
+Ports are represented by connections of ovs\-port
+type\&. Due to the limitations of OVSDB, "empty" Ports (with no Interfaces) can\*(Aqt 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\&.
+.SS "Interfaces"
+.PP
+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\&.
+.SH "EXAMPLES"
+.PP
+\fBExample\ \&1.\ \&Creating a Bridge with a single internal Interface\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ \fBnmcli conn add conn\&.type ovs\-bridge conn\&.interface bridge0\fR
+Connection \*(Aqovs\-bridge\-bridge0\*(Aq (d10fc64d\-1d48\-4394\-a1b8\-e1aea72f27d5) successfully added\&.
+$ \fBnmcli conn add conn\&.type ovs\-port conn\&.interface port0 conn\&.master bridge0\fR
+Connection \*(Aqovs\-port\-port0\*(Aq (5ae22bae\-bba4\-4815\-9ade\-7e635633e1f0) successfully added\&.
+$ \fBnmcli conn add conn\&.type ovs\-interface conn\&.interface iface0 conn\&.master port0 \e
+  ipv4\&.method manual ipv4\&.address 192\&.0\&.2\&.1/24\fR
+Connection \*(Aqovs\-interface\-iface0\*(Aq (3640d2a1\-a2fd\-4718\-92f1\-cffadb5b6cdc) successfully added\&.
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+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
+\fBovs\-vsctl show\fR\&.
+.PP
+\fBExample\ \&2.\ \&Adding a Linux interface to a Bridge\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ \fBnmcli conn add conn\&.type ovs\-port conn\&.interface port1 conn\&.master bridge0\fR
+Connection \*(Aqovs\-port\-port1\*(Aq (67d041eb\-8e7b\-4458\-afee\-a1d07c9c4552) successfully added\&.
+$ \fBnmcli conn add conn\&.type ethernet conn\&.interface eth0 conn\&.master port1\fR
+Connection \*(Aqovs\-slave\-eth0\*(Aq (d459c45c\-cf78\-4c1c\-b4b7\-505e71379624) successfully added\&.
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+Again, you need a port\&.
+.PP
+\fBExample\ \&3.\ \&Creating a VLAN\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ \fBnmcli conn add conn\&.type ovs\-port conn\&.interface port2 conn\&.master bridge0 ovs\-port\&.tag 120\fR
+Connection \*(Aqovs\-port\-port2\*(Aq (3994c093\-4ef7\-4549\-a4fd\-627b831c3cb8) successfully added\&.
+$ \fBnmcli conn add conn\&.type ethernet conn\&.interface eth1 conn\&.master port2\fR
+Connection \*(Aqovs\-slave\-eth1\*(Aq (099be06e\-71ad\-484d\-8d5a\-fcadc5f207f5) successfully added\&.
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+It\*(Aqs just a port with a tag\&.
+.PP
+\fBExample\ \&4.\ \&Creating a Bond\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ \fBnmcli conn add conn\&.type ovs\-port conn\&.interface bond0 conn\&.master bridge0\fR
+Connection \*(Aqovs\-port\-bond0\*(Aq (d154ebf9\-e999\-4e1b\-a084\-a3de53d25d8a) successfully added\&.
+$ \fBnmcli conn add conn\&.type ethernet conn\&.interface eth2 conn\&.master bond0\fR
+Connection \*(Aqovs\-slave\-eth2\*(Aq (475ac1bf\-30b2\-4534\-a877\-27f33f58b082) successfully added\&.
+$ \fBnmcli conn add conn\&.type ethernet conn\&.interface eth3 conn\&.master bond0\fR
+Connection \*(Aqovs\-slave\-eth3\*(Aq (8dedeecb\-ed12\-482b\-b77a\-24a4fb835136) successfully added\&.
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+It\*(Aqs 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\&.
+.SH "BUGS"
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Not all OpenVSwitch capabilities are supported\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+OpenVSwitch devices don\*(Aqt expose many useful properties on D\-Bus\&.
+.RE
+.PP
+Probably many more\&.
+.SH "SEE ALSO"
+.PP
+\m[blue]\fBRFC 7047: The Open vSwitch Database Management Protocol\fR\m[]\&\s-2\u[1]\d\s+2,
+\fBovs-vsctl\fR(8),
+\fBovs-vswitchd.conf.db\fR(5),
+\fBnm-settings\fR(5),
+\fBnmcli\fR(1)
+.SH "NOTES"
+.IP " 1." 4
+RFC 7047: The Open vSwitch Database Management Protocol
+.RS 4
+\%https://www.rfc-editor.org/rfc/rfc7047.txt
+.RE