[ovs-dev] [RFC 2/2] doc: Convert ovs-vswitchd to rST
Stephen Finucane
stephen at that.guru
Thu May 11 01:32:19 UTC 2017
This is the largest man page by some distance. There are a couple of
changes needed to make this work:
- Combining italics and bold without spaces (i.e. <b>hello</b>-<i>world
</i>) and nesting italics and bold (i.e. <b><i>hello-world</i></b>)
is not supported by rST. Where present, this has been removed.
- Duplicated opts are not possible. Where before we would have had a
list like so:
-vPATTERN:destination:pattern
Description
-vFACILITY:facility
Description
We now have:
-v <verbosity>
PATTERN:<destination>:<pattern>
Description
FACILITY:<facility>
Description
This is necessary if we want to make best use of the Sphinx indexing.
- TODO
Signed-off-by: Stephen Finucane <stephen at that.guru>
---
This patch isn't complete, but I wanted to see what people thought of
the formatting for more complex commands. There are a couple of issues
with this that I still need to work through:
- There's a big loss of formatting for subcommands. While I don't think
the bit of loss in the option descriptions is _that_ big a deal, the
subcommands are longer and could benefit from the formatting more. I
could probably fix it in Sphinx internally for Sphinx 1.6, but that'd
take a year or two to propagate to distros.
- I'm not sure if there's a way to use this kind of macro:
\*(DX\fBadd\-dp \fIdp\fR [\fInetdev\fR[\fB,\fIoption\fR]...]
which is called like so:
.ds DX \fBdpctl/\fR
.de DO
\\$2 \\$1 \\$3
and yields:
dpctl/add-dp dp [netdev[,option]...]
This will probably result in some duplication, else a _lot_ of 'inc'
files
- I'm not sure how we should pass in autoconf (?) variables like
@RUNDIR at . Could we do this in Python or something?
- Some other stuff that I've forgotten
In any case though, it should go folks a rough idea of what a larger man
page in rST/Sphinx will actually look like.
---
Documentation/conf.py | 2 +
Documentation/ref/common.inc | 7 +
Documentation/ref/coverage-unixctl.inc | 16 ++
Documentation/ref/daemon.inc | 85 ++++++
Documentation/ref/dpctl.inc | 199 ++++++++++++++
Documentation/ref/index.rst | 1 +
Documentation/ref/memory-unixctl.inc | 10 +
Documentation/ref/ofproto-dpif-unixctl.inc | 38 +++
Documentation/ref/ofproto-tnl-unixctl.inc | 40 +++
Documentation/ref/ofproto-unixctl.inc | 162 +++++++++++
Documentation/ref/ovs-vswitchd.8.rst | 414 +++++++++++++++++++++++++++++
Documentation/ref/remote-active.inc | 22 ++
Documentation/ref/remote-passive.inc | 28 ++
Documentation/ref/service.inc | 14 +
Documentation/ref/ssl-bootstrap.inc | 22 ++
Documentation/ref/ssl.inc | 33 +++
Documentation/ref/unixctl.inc | 16 ++
Documentation/ref/vlog-unixctl.inc | 79 ++++++
Documentation/ref/vlog.inc | 88 ++++++
19 files changed, 1276 insertions(+)
create mode 100644 Documentation/ref/common.inc
create mode 100644 Documentation/ref/coverage-unixctl.inc
create mode 100644 Documentation/ref/daemon.inc
create mode 100644 Documentation/ref/dpctl.inc
create mode 100644 Documentation/ref/memory-unixctl.inc
create mode 100644 Documentation/ref/ofproto-dpif-unixctl.inc
create mode 100644 Documentation/ref/ofproto-tnl-unixctl.inc
create mode 100644 Documentation/ref/ofproto-unixctl.inc
create mode 100644 Documentation/ref/ovs-vswitchd.8.rst
create mode 100644 Documentation/ref/remote-active.inc
create mode 100644 Documentation/ref/remote-passive.inc
create mode 100644 Documentation/ref/service.inc
create mode 100644 Documentation/ref/ssl-bootstrap.inc
create mode 100644 Documentation/ref/ssl.inc
create mode 100644 Documentation/ref/unixctl.inc
create mode 100644 Documentation/ref/vlog-unixctl.inc
create mode 100644 Documentation/ref/vlog.inc
diff --git a/Documentation/conf.py b/Documentation/conf.py
index d70ee6b..174cc7e 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -113,6 +113,8 @@ html_static_path = ['_static']
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
_man_pages = [
+ ('ovs-vswitchd.8',
+ u'Open vSwitch daemon'),
('ovs-test.8',
u'Check Linux drivers for performance, vlan and L3 tunneling problems'),
('ovs-vlan-test.8',
diff --git a/Documentation/ref/common.inc b/Documentation/ref/common.inc
new file mode 100644
index 0000000..321b331
--- /dev/null
+++ b/Documentation/ref/common.inc
@@ -0,0 +1,7 @@
+.. option:: -h, --help
+
+ Prints a brief help message to the console.
+
+.. option:: -V, --version
+
+ Prints version information to the console.
diff --git a/Documentation/ref/coverage-unixctl.inc b/Documentation/ref/coverage-unixctl.inc
new file mode 100644
index 0000000..90563e9
--- /dev/null
+++ b/Documentation/ref/coverage-unixctl.inc
@@ -0,0 +1,16 @@
+Coverage Commands
+-----------------
+
+These commands manage |program-name|'s *coverage counters*, which count the
+number of times particular events occur during a daemon's runtime. In addition
+to these commands, |program-name| automatically logs coverage counter values,
+at ``INFO`` level, when it detects that the daemon's main loop takes unusually
+long to run.
+
+Coverage counters are useful mainly for performance analysis and debugging.
+
+.. object:: coverage/show
+
+ Displays the averaged per-second rates for the last few seconds, the last
+ minute and the last hour, and the total counts of all of the coverage
+ counters.
diff --git a/Documentation/ref/daemon.inc b/Documentation/ref/daemon.inc
new file mode 100644
index 0000000..2c8ae0a
--- /dev/null
+++ b/Documentation/ref/daemon.inc
@@ -0,0 +1,85 @@
+.. -*- rst -*-
+
+The following options are valid on POSIX based platforms.
+
+.. option:: --pidfile <pidfile>
+
+ Causes a file (by default, |program-name|.pid) to be created indicating the
+ PID of the running process. If the *pidfile* argument is not specified, or
+ if it does not begin with ``/``, then it is created in ``@RUNDIR@``.
+
+ If :option:`--pidfile` is not specified, no pidfile is created.
+
+.. option:: --overwrite-pidfile
+
+ By default, when :option:`--pidfile` is specified and the specified pidfile
+ already exists and is locked by a running process, |program-name| refuses
+ to start. Specify :option:`--overwrite-pidfile` to cause it to instead
+ overwrite the pidfile.
+
+ When :option:`--pidfile` is not specified, this option has no effect.
+
+.. option:: --detach
+
+ Runs |program-name| as a background process. The process forks, and in the
+ child it starts a new session, closes the standard file descriptors (which
+ has the side effect of disabling logging to the console), and changes its
+ current directory to the root (unless :option:`--no-chdir` is specified).
+ After the child completes its initialization, the parent exits.
+ |detach-msg|
+
+.. option:: --monitor
+
+ Creates an additional process to monitor the |program-name| daemon. If the
+ daemon dies due to a signal that indicates a programming error
+ (``SIGABRT``, ``SIGALRM``, ``SIGBUS``, ``SIGFPE``, ``SIGILL``, ``SIGPIPE``,
+ ``SIGSEGV``, ``SIGXCPU``, or ``SIGXFSZ``) then the monitor process starts a
+ new copy of it. If the daemon dies or exits for another reason, the
+ monitor process exits.
+
+ This option is normally used with :option:`--detach`, but it also functions
+ without it.
+
+.. option:: --no-chdir
+
+ By default, when :option:`--detach` is specified, |program-name| changes
+ its current working directory to the root directory after it detaches.
+ Otherwise, invoking |program-name| from a carelessly chosen directory would
+ prevent the administrator from unmounting the file system that holds that
+ directory.
+
+ Specifying :option:`--no-chdir` suppresses this behavior, preventing
+ |program-name| from changing its current working directory. This may be
+ useful for collecting core files, since it is common behavior to write core
+ dumps into the current working directory and the root directory is not a
+ good directory to use.
+
+ This option has no effect when :option:`--detach` is not specified.
+
+.. option:: --no-self-confinement
+
+ By default daemon will try to self-confine itself to work with files under
+ well-know, at build-time whitelisted directories. It is better to stick
+ with this default behavior and not to use this flag unless some other
+ Access Control is used to confine daemon. Note that in contrast to other
+ access control implementations that are typically enforced from
+ kernel-space (e.g. DAC or MAC), self-confinement is imposed from the
+ user-space daemon itself and hence should not be considered as a full
+ confinement strategy, but instead should be viewed as an additional layer
+ of security.
+
+.. option:: --user
+
+ Causes |program-name| to run as a different user specified in "user:group",
+ thus dropping most of the root privileges. Short forms "user" and ":group"
+ are also allowed, with current user or group are assumed respectively. Only
+ daemons started by the root user accepts this argument.
+
+ On Linux, daemons will be granted ``CAP_IPC_LOCK`` and
+ ``CAP_NET_BIND_SERVICES`` before dropping root privileges. Daemons that
+ interact with a datapath, such as `ovs-vswitchd` will be granted two
+ additional capabilities, namely ``CAP_NET_ADMIN`` and ``CAP_NET_RAW``. The
+ capability change will apply even if new user is "root".
+
+ On Windows, this option is not currently supported. For security reasons,
+ specifying this option will cause the daemon process not to start.
diff --git a/Documentation/ref/dpctl.inc b/Documentation/ref/dpctl.inc
new file mode 100644
index 0000000..03eb6df
--- /dev/null
+++ b/Documentation/ref/dpctl.inc
@@ -0,0 +1,199 @@
+.. object:: dpctl/add-dp dp [netdev[,option]...]
+
+ Creates datapath *dp*, with a local port also named *dp*. This will fail
+ if a network device *dp* already exists.
+
+ If *netdev* are specified, |program-name| adds them to the new datapath,
+ just as if ``add-if`` was specified.
+
+.. object:: dpctl/del-dp dp
+
+ Deletes datapath *dp*. If *dp* is associated with any network devices,
+ they are automatically removed.
+
+.. object:: dpctl/add-if dp netdev[,option]...
+
+ Adds each *netdev* to the set of network devices datapath *dp* monitors,
+ where *dp* is the name of an existing datapath, and *netdev* is the name of
+ one of the host's network devices, e.g. ``eth0``. Once a network device
+ has been added to a datapath, the datapath has complete ownership of the
+ network device's traffic and the network device appears silent to the rest
+ of the system.
+
+ A *netdev* may be followed by a comma-separated list of options. The
+ following options are currently supported:
+
+ ``type=type``
+
+ Specifies the type of port to add. The default type is ``system``.
+
+ ``port_no=port``
+
+ Requests a specific port number within the datapath. If this option is
+ not specified then one will be automatically assigned.
+
+ ``key=value``
+
+ Adds an arbitrary key-value option to the port's configuration.
+
+ `ovs-vswitchd.conf.db(5)` documents the available port types and options.
+
+.. object:: dpctl/set-if dp port[,option]...
+
+ Reconfigures each *port* in *dp* as specified. An *option* of the form
+ ``key=value`` adds the specified key-value option to the port or overrides
+ an existing key's value. An *option* of the form ``key=``, that is,
+ without a value, deletes the key-value named *key*. The type and port
+ number of a port cannot be changed, so ``type`` and ``port_no`` are only
+ allowed if they match the existing configuration.
+
+.. object:: dpctl/del-if dp netdev...
+
+ Removes each *netdev* from the list of network devices datapath *dp*
+ monitors.
+
+.. object:: dpctl/dump-dps
+
+ Prints the name of each configured datapath on a separate line.
+
+.. object:: dpctl/show [-s | --statistics] [dp...]
+
+ Prints a summary of configured datapaths, including their datapath numbers
+ and a list of ports connected to each datapath. (The local port is
+ identified as port 0.) If ``-s`` or ``--statistics`` is specified, then
+ packet and byte counters are also printed for each port.
+
+ The datapath numbers consists of flow stats and mega flow mask stats.
+
+ The *lookups* row displays three stats related to flow lookup triggered by
+ processing incoming packets in the datapath. "hit" displays number of
+ packets matches existing flows. "missed" displays the number of packets not
+ matching any existing flow and require user space processing. "lost"
+ displays number of packets destined for user space process but subsequently
+ dropped before reaching userspace. The sum of "hit" and "miss" equals to
+ the total number of packets datapath processed.
+
+ The *flows* row displays the number of flows in datapath.
+
+ The *masks* row displays the mega flow mask stats. This row is omitted for
+ datapath not implementing mega flow. "hit" displays the total number of
+ masks visited for matching incoming packets. "total" displays number of
+ masks in the datapath. "hit/pkt" displays the average number of masks
+ visited per packet; the ratio between "hit" and total number of packets
+ processed by the datapath".
+
+ If one or more datapaths are specified, information on only those datapaths
+ are displayed. Otherwise, |program-name| displays information about all
+ configured datapaths.
+
+Datapath Flow Table Debugging Commands
+--------------------------------------
+
+The following commands are primarily useful for debugging Open vSwitch. The
+flow table entries (both matches and actions) that they work with are not
+OpenFlow flow entries. Instead, they are different and considerably simpler
+flows maintained by the Open vSwitch kernel module. Use `ovs-ofctl(8)`,
+instead, to work with OpenFlow flow entries.
+
+The *dp* argument to each of these commands is optional when exactly one
+datapath exists, in which case that datapath is the default. When multiple
+datapaths exist, then a datapath name is required.
+
+.. object:: dump-flows [-m | --more] [dp] [filter=filter]
+
+ Prints to the console all flow entries in datapath *dp*'s flow table.
+ Without ``-m`` or ``--more``, output omits match fields that a flow
+ wildcards entirely; with ``-m`` or ``--more``, output includes all
+ wildcarded fields.
+
+ If ``filter=filter`` is specified, only displays the flows that match the
+ *filter*. *filter* is a flow in the form similiar to that accepted by the
+ `ovs-ofctl(8)` ``add-flow`` command. (This is not an OpenFlow flow: besides
+ other differences, it never contains wildcards.) The *filter* is also
+ useful to match wildcarded fields in the datapath flow. As an example,
+ ``filter='tcp,tp_src=100'`` will match the datapath flow containing
+ ``tcp(src=80/0xff00,dst=8080/0xff)``.
+
+.. object:: dpctl/add-flow [dp] <flow actions>
+ dpctl/mod-flow [--clear] [--may-create] [-s | --statistics] [dp] flow actions...
+
+ Adds or modifies a flow in *dp*'s flow table that, when a packet matching
+ *flow* arrives, causes *actions* to be executed.
+
+ The ``add-flow`` command succeeds only if *flow* does not already exist in
+ *dp*. Contrariwise, ``mod-flow`` without ``--may-create`` only modifies
+ the actions for an existing flow. With ``--may-create``, ``mod-flow`` will
+ add a new flow or modify an existing one.
+
+ If ``-s`` or ``--statistics`` is specified, then ``mod-flow`` prints the
+ modified flow's statistics. A flow's statistics are the number of packets
+ and bytes that have passed through the flow, the elapsed time since the
+ flow last processed a packet (if ever), and (for TCP flows) the union of
+ the TCP flags processed through the flow.
+
+ With ``--clear``, ``mod-flow`` zeros out the flow's statistics. The
+ statistics printed if ``-s`` or ``--statistics`` is also specified are
+ those from just before clearing the statistics.
+
+ .. note::
+
+ *flow* and *actions* do not match the syntax used with `ovs-ofctl`
+ ``add-flow`` command.
+
+ .. rubric:: Usage Examples
+
+ Forward ARP between ports 1 and 2 on datapath myDP::
+
+ ovs-dpctl add-flow myDP "in_port(1),eth(),eth_type(0x0806),arp()" 2
+ ovs-dpctl add-flow myDP "in_port(2),eth(),eth_type(0x0806),arp()" 1
+
+ Forward all IPv4 traffic between two addresses on ports 1 and 2::
+
+ ovs-dpctl add-flow myDP "in_port(1),eth(),eth_type(0x800),ipv4(src=172.31.110.4,dst=172.31.110.5)" 2
+ ovs-dpctl add-flow myDP "in_port(2),eth(),eth_type(0x800),ipv4(src=172.31.110.5,dst=172.31.110.4)" 1
+
+.. object:: dpctl/del-flow [-s | --statistics] [dp] flow
+
+ Deletes the flow from *dp*'s flow table that matches *flow*. If ``-s`` or
+ ``--statistics`` is specified, then ``del-flow`` prints the deleted flow's
+ statistics.
+
+.. object:: dpctl/get-flow [dp] ufid:ufid
+
+ Fetches the flow from *dp*'s flow table with unique identifier *ufid*.
+ *ufid* must be specified as a string of 32 hexadecimal characters.
+
+.. object:: dpctl/del-flows [dp]
+
+ Deletes all flow entries from datapath *dp*'s flow table.
+
+Connection Tracking Table Debugging Commands
+--------------------------------------------
+
+The following commands are primarily useful for debugging the connection
+tracking entries in the datapath.
+
+The *dp* argument to each of these commands is optional when exactly one
+datapath exists, in which case that datapath is the default. When multiple
+datapaths exist, then a datapath name is required.
+
+.. important::
+
+ (Linux specific): the *system* datapaths (i.e. the Linux kernel module Open
+ vSwitch datapaths) share a single connection tracking table (which is also
+ used by other kernel subsystems, such as iptables, nftables and the regular
+ host stack). Therefore, the following commands do not apply specifically
+ to one datapath.
+
+.. object:: dpctl/dump-conntrack [-m | --more] [-s | --statistics] [dp] [zone=zone]
+
+ Prints to the console all the connection entries in the tracker used by
+ *dp*. If ``zone=zone`` is specified, only shows the connections in
+ ``zone``. With ``--more``, some implementation specific details are
+ included. With ``--statistics`` timeouts and timestamps are added to the
+ output.
+
+.. object:: dpctl/flush-conntrack [dp] [zone=zone]
+
+ Flushes all the connection entries in the tracker used by *dp*. If
+ ``zone=zone`` is specified, only flushes the connections in ``zone``.
diff --git a/Documentation/ref/index.rst b/Documentation/ref/index.rst
index 3e2f8d5..e2a7900 100644
--- a/Documentation/ref/index.rst
+++ b/Documentation/ref/index.rst
@@ -39,6 +39,7 @@ time:
.. toctree::
:maxdepth: 3
+ ovs-vswitchd.8
ovs-test.8
ovs-vlan-test.8
diff --git a/Documentation/ref/memory-unixctl.inc b/Documentation/ref/memory-unixctl.inc
new file mode 100644
index 0000000..8e2646e
--- /dev/null
+++ b/Documentation/ref/memory-unixctl.inc
@@ -0,0 +1,10 @@
+Memory Commands
+---------------
+
+These commands report memory usage.
+
+.. object:: memory/show
+
+ Displays some basic statistics about |program-name|'s memory usage.
+ |program-name| also logs this information soon after startup and
+ periodically as its memory consumption grows.
diff --git a/Documentation/ref/ofproto-dpif-unixctl.inc b/Documentation/ref/ofproto-dpif-unixctl.inc
new file mode 100644
index 0000000..215f092
--- /dev/null
+++ b/Documentation/ref/ofproto-dpif-unixctl.inc
@@ -0,0 +1,38 @@
+Datapath Debugging Commands
+---------------------------
+
+These commands query and modify datapaths. They are are similar to `ovs-dpctl`
+commands. ``dpif/show`` has the additional functionality, beyond ``dpctl/show``
+of printing OpenFlow port numbers. The other commands are redundant and will
+be removed in a future release.
+
+.. object:: dpif/dump-dps
+
+ Prints the name of each configured datapath on a separate line.
+
+.. object:: dpif/show
+
+ Prints a summary of configured datapaths, including statistics and a list
+ of connected ports. The port information includes the OpenFlow port
+ number, datapath port number, and the type. (The local port is identified
+ as OpenFlow port 65534.)
+
+.. object:: dpif/dump-flows [-m] dp
+
+ Prints to the console all flow entries in datapath *dp* flow table. Without
+ ``-m``, output omits match fields that a flow wildcards entirely; with
+ ``-m`` output includes all wildcarded fields.
+
+ This command is primarily useful for debugging Open vSwitch. The flow
+ table entries that it displays are not OpenFlow flow entries. Instead,
+ they are different and considerably simpler flows maintained by the
+ datapath module. If you wish to see the OpenFlow flow entries, use
+ ``ovs-ofctl dump-flows``.
+
+.. object:: dpif/del-flows dp
+
+ Deletes all flow entries from datapath *dp* flow table and underlying
+ datapath implementation (e.g., kernel datapath module).
+
+ This command is primarily useful for debugging Open vSwitch. As discussed
+ in ``dpif/dump-flows``, these entries are not OpenFlow flow entries.
diff --git a/Documentation/ref/ofproto-tnl-unixctl.inc b/Documentation/ref/ofproto-tnl-unixctl.inc
new file mode 100644
index 0000000..73ff454
--- /dev/null
+++ b/Documentation/ref/ofproto-tnl-unixctl.inc
@@ -0,0 +1,40 @@
+Open vSwitch Tunneling Commands
+-------------------------------
+
+These commands query and modify OVS tunnel components.
+
+.. object:: ovs/route/add ipv4_address/plen output_bridge [GW]
+
+ Adds ipv4_address/plen route to vswitchd routing table. output_bridge needs
+ to be OVS bridge name. This command is useful if OVS cached routes does
+ not look right.
+
+.. object:: ovs/route/show
+
+ Print all routes in OVS routing table, This includes routes cached from
+ system routing table and user configured routes.
+
+.. object:: ovs/route/del ipv4_address/plen
+
+ Delete ipv4_address/plen route from OVS routing table.
+
+.. object:: tnl/neigh/show
+.. object:: tnl/arp/show
+
+ OVS builds ARP cache by snooping are messages. This command shows ARP cache
+ table.
+
+.. object:: tnl/neigh/set Ibridge ip mac
+.. object:: tnl/arp/set bridge ip mac
+
+ Adds or modifies an ARP cache entry in *bridge*, mapping *ip* to *mac*.
+
+.. object:: tnl/neigh/flush
+.. object:: tnl/arp/flush
+
+ Flush ARP table.
+
+.. object:: tnl/egress_port_range [num1] [num2]
+
+ Set range for UDP source port used for UDP based Tunnels. For example
+ VxLAN. If case of zero arguments this command prints current range in use.
diff --git a/Documentation/ref/ofproto-unixctl.inc b/Documentation/ref/ofproto-unixctl.inc
new file mode 100644
index 0000000..eb694ff
--- /dev/null
+++ b/Documentation/ref/ofproto-unixctl.inc
@@ -0,0 +1,162 @@
+ofproto Commands
+----------------
+
+These commands manage the core OpenFlow switch implementation (called
+``ofproto``).
+
+.. object:: ofproto/list
+
+ Lists the names of the running ofproto instances. These are the names that
+ may be used on ``ofproto/trace``
+
+.. object:: ofproto/trace [dpname] odp_flow [-generate | packet]
+ ofproto/trace bridge br_flow [-generate | packet]
+ ofproto/trace-packet-out [-consistent] [dpname] odp_flow [--generate| packet] actions
+ ofproto/trace-packet-out [-consistent] bridge br_flow [-generate | packet] actions
+
+ Traces the path of an imaginary packet through *switch* and reports the
+ path that it took. The initial treatment of the packet varies based on the
+ command:
+
+ - ``ofproto/trace`` looks the packet up in the OpenFlow flow table, as if
+ the packet had arrived on an OpenFlow port.
+
+ - ``ofproto/trace-packet-out`` applies the specified OpenFlow *actions*, as
+ if the packet, flow, and actions had been specified in an OpenFlow
+ ``packet-out`` request.
+
+ The packet's headers (e.g. source and destination) and metadata (e.g. input
+ port), together called its ``flow,`` are usually all that matter for the
+ purpose of tracing a packet. You can specify the flow in the following
+ ways:
+
+ ``dpname odp_flow``
+
+ ``odp_flow`` is a flow in the form printed by `ovs-dpctl(8)`
+ ``dump-flows`` command. If all of your bridges have the same type,
+ which is the common case, then you can omit *dpname*, but if you have
+ bridges of different types (say, both ``ovs-netdev`` and
+ ``ovs-system``), then you need to specify a *dpname* to disambiguate.
+
+ ``bridge br_flow``
+
+ *br_flow* is a flow in the form similar to that accepted by
+ `ovs-ofctl(8)` ``add-flow`` command. (This is not an OpenFlow flow:
+ besides other differences, it never contains wildcards.) *bridge* names
+ of the bridge through which *br_flow* should be traced.
+
+ Most commonly, one specifies only a flow, using one of the forms above, but
+ sometimes one might need to specify an actual packet instead of just a
+ flow:
+
+ .. rubric:: Side effects
+
+ Some actions have side effects. For example, the ``normal`` action can
+ update the MAC learning table, and the ``learn`` action can change OpenFlow
+ tables. The trace commands only perform side effects when a packet is
+ specified. If you want side effects to take place, then you must supply a
+ packet.
+
+ (Output actions are obviously side effects too, but the trace commands
+ never execute them, even when one specifies a packet.)
+
+ .. rubric:: Incomplete information.
+
+ Most of the time, Open vSwitch can figure out everything about the path of
+ a packet using just the flow, but in some special circumstances it needs to
+ look at parts of the packet that are not included in the flow. When this
+ is the case, and you do not supply a packet, then a trace command will tell
+ you it needs a packet.
+
+ If you wish to include a packet as part of a trace operation, there are two
+ ways to do it:
+
+ ``-generate``
+
+ This option, added to one of the ways to specify a flow already
+ described, causes Open vSwitch to internally generate a packet with the
+ flow described and then to use that packet. If your goal is to execute
+ side effects, then ``-generate`` is the easiest way to do it, but
+ ``-generate`` is not a good way to fill in incomplete information,
+ because it generates packets based on only the flow information, which
+ means that the packets really do not have any more information than the
+ flow.
+
+ ``packet``
+
+ This form supplies an explicit *packet* as a sequence of hex digits.
+ An Ethernet frame is at least 14 bytes long, so there must be at least
+ 28 hex digits. Obviously, it is inconvenient to type in the hex digits
+ by hand, so the `ovs-pcap` and `ovs-tcpundump` utilities provide easier
+ ways.
+
+ With this form, packet headers are extracted directly from *packet*, so
+ the *odp_flow* or *br_flow* should specify only metadata. The metadata
+ can be:
+
+ ``skb_priority``
+
+ Packet QoS priority.
+
+ ``pkt_mark``
+
+ Mark of the packet.
+
+ ``ct_state``
+
+ Connection state of the packet.
+
+ ``ct_zone``
+
+ Connection tracking zone for packet.
+
+ ``ct_mark``
+
+ Connection mark of the packet.
+
+ ``ct_label``
+
+ Connection label of the packet.
+
+ ``tun_id``
+
+ The tunnel ID on which the packet arrived.
+
+ ``in_port``
+
+ The port on which the packet arrived.
+
+ The ``in_port`` value is kernel datapath port number for the first format
+ and OpenFlow port number for the second format. The numbering of these two
+ types of port usually differs and there is no relationship.
+
+ ``ofproto-trace-packet-out`` accepts an additional ``-consistent`` option.
+ With this option specified, the command rejects *actions* that are
+ inconsistent with the specified packet. (An example of an inconsistency is
+ attempting to strip the VLAN tag from a packet that does not have a VLAN
+ tag.) Open vSwitch ignores most forms of inconsistency in OpenFlow 1.0 and
+ rejects inconsistencies in later versions of OpenFlow. The option is
+ necessary because the command does not ordinarily imply a particular
+ OpenFlow version. One exception is that, when *actions* includes an action
+ that only OpenFlow 1.1 and later supports (such as ``push_vlan``),
+ ``-consistent`` is automatically enabled.
+
+ .. rubric:: Usage examples:
+
+ Trace an unicast ICMP echo request on ingress port ``1`` to destination MAC
+ ``00:00:5E:00:53:01``::
+
+ ofproto/trace br in_port=1,icmp,icmp_type=8,dl_dst=00:00:5E:00:53:01
+
+ Trace an unicast ICMP echo reply on ingress port 1 to destination MAC
+ ``00:00:5E:00:53:01``::
+
+ ofproto/trace br in_port=1,icmp,icmp_type=0,dl_dst=00:00:5E:00:53:01
+
+ Trace an ARP request on ingress port 1::
+
+ ofproto/trace br in_port=1,arp,arp_op=1
+
+ Trace an ARP reply on ingress port 1::
+
+ ofproto/trace br in_port=1,arp,arp_op=2
diff --git a/Documentation/ref/ovs-vswitchd.8.rst b/Documentation/ref/ovs-vswitchd.8.rst
new file mode 100644
index 0000000..9edc4a3
--- /dev/null
+++ b/Documentation/ref/ovs-vswitchd.8.rst
@@ -0,0 +1,414 @@
+============
+ovs-vswitchd
+============
+
+Synopsis
+========
+
+**ovs-vswitchd** [*database*]
+
+Description
+===========
+
+A daemon that manages and controls any number of Open vSwitch switches on the
+local machine.
+
+The *database* argument specifies how `ovs-vswitchd` connects to
+`ovsdb-server`. The default is ``unix:@RUNDIR@/db.sock``. The following forms
+are accepted:
+
+.. include:: remote-active.inc
+.. include:: remote-passive.inc
+
+`ovs-vswitchd` retrieves its configuration from *database* at startup. It sets
+up Open vSwitch datapaths and then operates switching across each bridge
+described in its configuration files. As the database changes, `ovs-vswitchd`
+automatically updates its configuration to match.
+
+`ovs-vswitchd` switches may be configured with any of the following features:
+
+- L2 switching with MAC learning.
+
+- NIC bonding with automatic fail-over and source MAC-based TX load balancing
+ ("SLB").
+
+- 802.1Q VLAN support.
+
+- Port mirroring, with optional VLAN tagging.
+
+- NetFlow v5 flow logging.
+
+- sFlow(R) monitoring.
+
+- Connectivity to an external OpenFlow controller, such as NOX.
+
+Only a single instance of `ovs-vswitchd` is intended to run at a time. A
+single `ovs-vswitchd` can manage any number of switch instances, up to the
+maximum number of supported Open vSwitch datapaths.
+
+`ovs-vswitchd` does all the necessary management of Open vSwitch datapaths
+itself. Thus, external tools, such `ovs-dpctl(8)`, are not needed for managing
+datapaths in conjunction with `ovs-vswitchd`, and their use to modify datapaths
+when `ovs-vswitchd` is running can interfere with its operation. (`ovs-dpctl`
+may still be useful for diagnostics.)
+
+An Open vSwitch datapath kernel module must be loaded for `ovs-vswitchd` to be
+useful. Refer to the documentation for instructions on how to build and load
+the Open vSwitch kernel module.
+
+Options
+=======
+
+.. program:: ovs-vswitchd
+
+.. option:: --mlockall
+
+ Causes `ovs-vswitchd` to call the ``mlockall()`` function, to attempt to
+ lock all of its process memory into physical RAM, preventing the kernel
+ from paging any of its memory to disk. This helps to avoid networking
+ interruptions due to system memory pressure
+
+ Some systems do not support ``mlockall()`` at all, and other systems only
+ allow privileged users, such as the superuser, to use it. `ovs-vswitchd`
+ emits a log message if ``mlockall()`` is unavailable or unsuccessful.
+
+DPDK Options
+------------
+
+For details on initializing the `ovs-vswitchd` DPDK datapath, refer to the
+documentation or `ovs-vswitchd.conf.db(5)` for details.
+
+Daemon Options
+--------------
+
+.. include:: daemon.inc
+
+.. |detach-msg| replace:: `ovs-vswitchd` detaches only after it has connected
+ to the database, retrieved the initial configuration, and set up that
+ configuration.
+
+Service Options
+---------------
+
+.. include:: service.inc
+
+Public Key Infrastructure Options
+---------------------------------
+
+.. include:: ssl.inc
+
+.. include:: ssl-bootstrap.inc
+
+Logging Options
+---------------
+
+.. include:: vlog.inc
+
+Other Options
+-------------
+
+.. include:: unixctl.inc
+.. include:: common.inc
+
+.. _runtime-management-commands:
+
+Runtime Management Commands
+===========================
+
+`ovs-appctl(8)` can send commands to a running `ovs-vswitchd` process. The
+currently supported commands are described below. The command descriptions
+assume an understanding of how to configure Open vSwitch.
+
+General Commands
+----------------
+
+.. object:: exit --cleanup
+
+ Causes `ovs-vswitchd` to gracefully terminate. If *--cleanup* is specified,
+ release datapath resources configured by `ovs-vswitchd`. Otherwise,
+ datapath flows and other resources remains undeleted.
+
+.. object:: qos/show-types interface
+
+ Queries the interface for a list of Quality of Service types that are
+ configurable via Open vSwitch for the given *interface*.
+
+.. object:: qos/show interface
+
+ Queries the kernel for Quality of Service configuration and statistics
+ associated with the given *interface*.
+
+.. object:: bfd/show [interface]
+
+ Displays detailed information about Bidirectional Forwarding Detection
+ configured on *interface*. If *interface* is not specified, then displays
+ detailed information about all interfaces with BFD enabled.
+
+.. object:: bfd/set-forwarding [interface] status
+
+ Force the fault status of the BFD module on *interface* (or all interfaces
+ if none is given) to be *status*. *status* can be "true", "false", or
+ "normal" which reverts to the standard behavior.
+
+.. object:: cfm/show [interface]
+
+ Displays detailed information about Connectivity Fault Management
+ configured on *interface*. If *interface* is not specified, then displays
+ detailed information about all interfaces with CFM enabled.
+
+.. object:: cfm/set-fault [interface] status
+
+ Force the fault status of the CFM module on *interface* (or all interfaces
+ if none is given) to be *status*. *status* can be "true", "false", or
+ "normal" which reverts to the standard behavior.
+
+.. object:: stp/tcn [bridge]
+
+ Forces a topology change event on *bridge* if it's running STP. This may
+ cause it to send Topology Change Notifications to its peers and flush its
+ MAC table.. If no *bridge* is given, forces a topology change event on all
+ bridges.
+
+.. object:: stp/show [bridge]
+
+ Displays detailed information about spanning tree on the *bridge*. If
+ *bridge* is not specified, then displays detailed information about all
+ bridges with STP enabled.
+
+Bridge Commands
+---------------
+
+These commands manage bridges.
+
+.. object:: fdb/flush [bridge]
+
+ Flushes *bridge* MAC address learning table, or all learning tables if no
+ *bridge* is given.
+
+.. object:: fdb/show bridge
+
+ Lists each MAC address/VLAN pair learned by the specified *bridge*, along
+ with the port on which it was learned and the age of the entry, in seconds.
+
+.. object:: mdb/flush [bridge]
+
+ Flushes *bridge* multicast snooping table, or all snooping tables if no
+ *bridge* is given.
+
+.. object:: mdb/show bridge
+
+ Lists each multicast group/VLAN pair learned by the specified *bridge*,
+ along with the port on which it was learned and the age of the entry, in
+ seconds.
+
+.. object:: bridge/reconnect [bridge]
+
+ Makes *bridge* drop all of its OpenFlow controller connections and
+ reconnect. If *bridge* is not specified, then all bridges drop their
+ controller connections and reconnect
+
+ This command might be useful for debugging OpenFlow controller issues.
+
+.. object:: bridge/dump-flows bridge
+
+ Lists all flows in *bridge*, including those normally hidden to commands
+ such as `ovs-ofctl dump-flows`. Flows set up by mechanisms such as in-band
+ control and fail-open are hidden from the controller since it is not
+ allowed to modify or override them.
+
+Bond Commands
+-------------
+
+These commands manage bonded ports on an Open vSwitch's bridges. To understand
+some of these commands, it is important to understand a detail of the bonding
+implementation called ``source load balancing`` (SLB). Instead of directly
+assigning Ethernet source addresses to slaves, the bonding implementation
+computes a function that maps an 48-bit Ethernet source addresses into an 8-bit
+value (a ``MAC hash`` value). All of the Ethernet addresses that map to a
+single 8-bit value are then assigned to a single slave.
+
+.. object:: bond/list
+
+ Lists all of the bonds, and their slaves, on each bridge.
+
+.. object:: bond/show [port]
+
+ Lists all of the bond-specific information (updelay, downdelay, time until
+ the next rebalance) about the given bonded *port*, or all bonded ports if
+ no *port* is given. Also lists information about each slave: whether it is
+ enabled or disabled, the time to completion of an updelay or downdelay if
+ one is in progress, whether it is the active slave, the hashes assigned to
+ the slave. Any LACP information related to this bond may be found using
+ the ``lacp/show`` command.
+
+.. object:: bond/migrate port hash slave
+
+ Only valid for SLB bonds. Assigns a given MAC hash to a new slave. *port*
+ specifies the bond port, *hash* the MAC hash to be migrated (as a decimal
+ number between 0 and 255), and *slave* the new slave to be assigned
+
+ The reassignment is not permanent: rebalancing or fail-over will cause the
+ MAC hash to be shifted to a new slave in the usual manner
+
+ A MAC hash cannot be migrated to a disabled slave.
+
+.. object:: bond/set-active-slave port slave
+
+ Sets *slave* as the active slave on *port*. *slave* must currently be
+ enabled
+
+ The setting is not permanent: a new active slave will be selected if
+ *slave* becomes disabled.
+
+.. object:: bond/enable-slave port slave
+.. object:: bond/disable-slave port slave
+
+ Enables (or disables) *slave* on the given bond *port*, skipping any
+ updelay (or downdelay)
+
+ This setting is not permanent: it persists only until the carrier status of
+ *slave* changes.
+
+.. object:: bond/hash mac [vlan] [basis]
+
+ Returns the hash value which would be used for *mac* with *vlan* and
+ *basis* if specified.
+
+.. object:: lacp/show [port]
+
+ Lists all of the LACP related information about the given *port*: active or
+ passive, aggregation key, system id, and system priority. Also lists
+ information about each slave: whether it is enabled or disabled, whether it
+ is attached or detached, port id and priority, actor information, and
+ partner information. If *port* is not specified, then displays detailed
+ information about all interfaces with CFM enabled.
+
+dpctl Datapath Debugging Commands
+---------------------------------
+
+The primary way to configure `ovs-vswitchd` is through the Open vSwitch
+database, e.g. using `ovs-vsctl(8)`. These commands provide a debugging
+interface for managing datapaths. They implement the same features (and
+syntax) as `ovs-dpctl(8)`. Unlike `ovs-dpctl(8)`, these commands work with
+datapaths that are integrated into `ovs-vswitchd` (e.g. the ``netdev`` datapath
+type).
+
+.. TODO(stephenfin): Figure out how to do this substitution for 'object'
+.. directives
+.. .
+.. .ds DX ``dpctl/``
+.. .de DO
+.. \\$2 \\$1 \\$3
+
+.. include:: dpctl.inc
+
+dpif-netdev Commands
+--------------------
+
+These commands are used to expose internal information (mostly statistics)
+about the ``dpif-netdev`` userspace datapath. If there is only one datapath (as
+is often the case, unless ``dpctl/`` commands are used), the *dp* argument can
+be omitted.
+
+.. object:: dpif-netdev/pmd-stats-show [dp]
+
+ Shows performance statistics for each pmd thread of the datapath *dp*. The
+ special thread ``main`` sums up the statistics of every non pmd thread.
+ The sum of ``emc hits``, ``masked hits`` and ``miss`` is the number of
+ packets received by the datapath. Cycles are counted using the TSC or
+ similar facilities (when available on the platform). To reset these
+ counters use ``dpif-netdev/pmd-stats-clear``. The duration of one cycle
+ depends on the measuring infrastructure.
+
+.. object:: dpif-netdev/pmd-stats-clear [dp]
+
+ Resets to zero the per pmd thread performance numbers shown by the
+ ``dpif-netdev/pmd-stats-show`` command. It will NOT reset datapath or
+ bridge statistics, only the values shown by the above command.
+
+.. object:: dpif-netdev/pmd-rxq-show [dp]
+
+ For each pmd thread of the datapath *dp* shows list of queue-ids with port
+ names, which this thread polls.
+
+.. include:: ofproto-dpif-unixctl.inc
+.. include:: ofproto-unixctl.inc
+.. include:: vlog-unixctl.inc
+.. include:: memory-unixctl.inc
+.. include:: coverage-unixctl.inc
+.. include:: ofproto-tnl-unixctl.inc
+
+Openflow Implementation
+=======================
+
+This section documents aspects of OpenFlow for which the OpenFlow specification
+requires documentation.
+
+Packet buffering
+----------------
+
+The OpenFlow specification, version 1.2, says:
+
+ Switches that implement buffering are expected to expose, through
+ documentation, both the amount of available buffering, and the length of
+ time before buffers may be reused.
+
+Open vSwitch does not maintains any packet buffers.
+
+Bundle lifetime
+---------------
+
+The OpenFlow specification, version 1.4, says:
+
+ If the switch does not receive any ``OFPT_BUNDLE_CONTROL`` or
+ ``OFPT_BUNDLE_ADD_MESSAGE`` message for an opened bundle_id for a switch
+ defined time greater than 1s, it may send an ``ofp_error_msg`` with
+ ``OFPET_BUNDLE_FAILED`` type and ``OFPBFC_TIMEOUT`` code. If the switch
+ does not receive any new message in a bundle apart from echo request and
+ replies for a switch defined time greater than 1s, it may send an
+ ``ofp_error_msg`` with ``OFPET_BUNDLE_FAILED`` type and ``OFPBFC_TIMEOUT``
+ code.
+
+Open vSwitch implements idle bundle lifetime of 10 seconds.
+
+Limits
+======
+
+We believe these limits to be accurate as of this writing. These limits assume
+the use of the Linux kernel datapath.
+
+- `ovs-vswitchd` started through `ovs-ctl(8)` provides a limit of 65535 file
+ descriptors. The limits on the number of bridges and ports is decided by the
+ availability of file descriptors. With the Linux kernel datapath, creation
+ of a single bridge consumes three file descriptors and adding a port consumes
+ "n-handler-threads" file descriptors per bridge port. Performance will
+ degrade beyond 1,024 ports per bridge due to fixed hash table sizing. Other
+ platforms may have different limitations.
+
+- 2,048 MAC learning entries per bridge, by default. (This is configurable via
+ `other-config:mac-table-size` in the ``Bridge`` table. See
+ `ovs-vswitchd.conf.db(5)` for details.)
+
+- Kernel flows are limited only by memory available to the kernel. Performance
+ will degrade beyond 1,048,576 kernel flows per bridge with a 32-bit kernel,
+ beyond 262,144 with a 64-bit kernel. (`ovs-vswitchd` should never install
+ anywhere near that many flows.)
+
+- OpenFlow flows are limited only by available memory. Performance is linear
+ in the number of unique wildcard patterns. That is, an OpenFlow table that
+ contains many flows that all match on the same fields in the same way has a
+ constant-time lookup, but a table that contains many flows that match on
+ different fields requires lookup time linear in the number of flows.
+
+- 255 ports per bridge participating in 802.1D Spanning Tree Protocol.
+
+- 32 mirrors per bridge.
+
+- 15 bytes for the name of a port. (This is a Linux kernel limitation.)
+
+See Also
+========
+
+`ovs-appctl(8)`, `ovsdb-server(1)`
+
+.. |program-name| replace:: ovs-vswitchd
diff --git a/Documentation/ref/remote-active.inc b/Documentation/ref/remote-active.inc
new file mode 100644
index 0000000..e5c6cfb
--- /dev/null
+++ b/Documentation/ref/remote-active.inc
@@ -0,0 +1,22 @@
+.. -*- rst -*-
+
+**ssl:ip:port**
+
+ The specified SSL *port* on the host at the given *ip*, which must be
+ expressed as an IP address (not a DNS name) in IPv4 or IPv6 address format.
+ If *ip* is an IPv6 address, then wrap *ip* with square brackets, e.g.:
+ ``ssl:[::1]:6640``. The ``--private-key``, ``--certificate``, and
+ ``--ca-cert`` options are mandatory when this form is used.
+
+**tcp:ip:port**
+
+ Connect to the given TCP *port* on *ip*, where *ip* can be IPv4 or IPv6
+ address. If *ip* is an IPv6 address, then wrap *ip* with square brackets,
+ e.g.: ``tcp:[::1]:6640``.
+
+**unix:file**
+
+ On POSIX, connect to the Unix domain server socket named *file*.
+
+ On Windows, connect to a local named pipe that is represented by a file
+ created in the path *file* to mimic the behavior of a Unix domain socket.
diff --git a/Documentation/ref/remote-passive.inc b/Documentation/ref/remote-passive.inc
new file mode 100644
index 0000000..215bc23
--- /dev/null
+++ b/Documentation/ref/remote-passive.inc
@@ -0,0 +1,28 @@
+.. -*- rst -*-
+
+**pssl:port[:ip]**
+
+ Listen on the given SSL *port* for a connection. By default, connections
+ are not bound to a particular local IP address and it listens only on IPv4
+ (but not IPv6) addresses, but specifying *ip* limits connections to those
+ from the given *ip*, either IPv4 or IPv6 address. If *ip* is an IPv6
+ address, then wrap *ip* with square brackets, e.g.: ``ssl:6640:[::1]``. The
+ ``--private-key``, ``--certificate``, and ``--ca-cert`` options are
+ mandatory when this form is used.
+
+**ptcp:port[:ip]**
+
+ Listen on the given TCP *port* for a connection. By default, connections
+ are not bound to a particular local IP address and it listens only on IPv4
+ (but not IPv6) addresses, but *ip* may be specified to listen only for
+ connections to the given *ip*, either IPv4 or IPv6 address. If *ip* is an
+ IPv6 address, then wrap *ip* with square brackets, e.g.:
+ ``tcp:6640:[::1]``.
+
+**punix:file**
+
+ On POSIX, listen on the Unix domain server socket named *file* for a
+ connection.
+
+ On Windows, listen on a local named pipe. A file is created in the path
+ *file* to mimic the behavior of a Unix domain socket.
diff --git a/Documentation/ref/service.inc b/Documentation/ref/service.inc
new file mode 100644
index 0000000..20bf338
--- /dev/null
+++ b/Documentation/ref/service.inc
@@ -0,0 +1,14 @@
+The following options are valid only on Windows platform.
+
+.. option:: --service
+
+ Causes |program-name| to run as a service in the background. The service
+ should already have been created through external tools like ``SC.exe``.
+
+.. option:: --service-monitor
+
+ Causes the |program-name| service to be automatically restarted by the
+ Windows services manager if the service dies or exits for unexpected
+ reasons.
+
+ When :option:`--service` is not specified, this option has no effect.
diff --git a/Documentation/ref/ssl-bootstrap.inc b/Documentation/ref/ssl-bootstrap.inc
new file mode 100644
index 0000000..e190008
--- /dev/null
+++ b/Documentation/ref/ssl-bootstrap.inc
@@ -0,0 +1,22 @@
+.. -*- rst -*-
+
+.. option:: --bootstrap-ca-cert <cacert.pem>
+
+ When *cacert.pem* exists, this option has the same effect as :option:`-C`
+ or :option:`--ca-cert`. If it does not exist, then |program-name| will
+ attempt to obtain the CA certificate from the SSL peer on its first SSL
+ connection and save it to the named PEM file. If it is successful, it will
+ immediately drop the connection and reconnect, and from then on all SSL
+ connections must be authenticated by a certificate signed by the CA
+ certificate thus obtained.
+
+ **This option exposes the SSL connection to a man-in-the-middle attack
+ obtaining the initial CA certificate**, but it may be useful for
+ bootstrapping.
+
+ This option is only useful if the SSL peer sends its CA certificate as part
+ of the SSL certificate chain. The SSL protocol does not require the server
+ to send the CA certificate.
+
+ This option is mutually exclusive with :option:`-C` and
+ :option:`--ca-cert`.
diff --git a/Documentation/ref/ssl.inc b/Documentation/ref/ssl.inc
new file mode 100644
index 0000000..12eeb4f
--- /dev/null
+++ b/Documentation/ref/ssl.inc
@@ -0,0 +1,33 @@
+.. -*- rst -*-
+
+.. option:: -p <privkey>, --private-key <privkey>
+
+ Specifies a PEM file containing the private key used as |program-name|'s
+ identity for outgoing SSL connections.
+
+.. option:: -c <certificate>, --certificate <certificate>
+
+ Specifies a PEM file containing a certificate that certifies the private
+ key specified on :option:`-p` or :option:`--private-key` to be
+ trustworthy. The certificate must be signed by the certificate authority
+ (CA) that the peer in SSL connections will use to verify it.
+
+.. option:: -C <cacert>, --ca-cert <cacert>
+
+ Configure verification of certificates presented by SSL peers.
+
+ There are two possible values:
+
+ <cacert>
+
+ Specifies a PEM file containing the CA certificate that |program-name|
+ should use to verify certificates presented to it by SSL peers. (This
+ may be the same certificate that SSL peers use to verify the
+ certificate specified on :option:`-c` or :option:`--certificate`, or it
+ may be a different one, depending on the PKI design in use.)
+
+ none
+
+ Disables verification of certificates presented by SSL peers. This
+ introduces a security risk, because it means that certificates cannot
+ be verified to be those of known trusted hosts.
diff --git a/Documentation/ref/unixctl.inc b/Documentation/ref/unixctl.inc
new file mode 100644
index 0000000..c850aee
--- /dev/null
+++ b/Documentation/ref/unixctl.inc
@@ -0,0 +1,16 @@
+.. option:: --unixctl <socket>
+
+ Sets the name of the control socket on which |program-name| listens for
+ runtime management commands (see :ref:`Runtime Management Commands
+ <runtime-management-commands>`). If *socket* does not begin with ``/``, it
+ is interpreted as relative to ``@RUNDIR@``. If :option:`--unixctl` is not
+ used at all, the default socket is `@RUNDIR@/|program-name|.pid.ctl`, where
+ ``pid`` is |program-name|'s process ID.
+
+ On Windows a local named pipe is used to listen for runtime management
+ commands. A file is created in the absolute path as pointed by *socket* or
+ if :option:`--unixctl` is not used at all, a file is created as
+ `|program-name|.ctl` in the configured *OVS_RUNDIR* directory. The file
+ exists just to mimic the behavior of a Unix domain socket.
+
+ Specifying ``none`` for *socket* disables the control socket feature.
diff --git a/Documentation/ref/vlog-unixctl.inc b/Documentation/ref/vlog-unixctl.inc
new file mode 100644
index 0000000..418d3c6
--- /dev/null
+++ b/Documentation/ref/vlog-unixctl.inc
@@ -0,0 +1,79 @@
+vlog Commands
+-------------
+
+These commands manage |program-name|'s logging settings.
+
+.. object:: vlog/set [spec]
+
+ Sets logging levels. Without any *spec*, sets the log level for every
+ module and destination to ``dbg``. Otherwise, *spec* is a list of words
+ separated by spaces or commas or colons, up to one from each category
+ below:
+
+ - A valid module name, as displayed by the ``vlog/list`` command on
+ `ovs-appctl`, limits the log level change to the specified module.
+
+ - ``syslog``, ``console``, or ``file``, to limit the log level change to
+ only to the system log, to the console, or to a file, respectively.
+
+ On Windows platform, ``syslog`` is accepted as a word and is only useful
+ along with the ``--syslog-target`` option (the word has no effect
+ otherwise).
+
+ - ``off``, ``emer``, ``err``, ``warn``, ``info``, or ``dbg``, to control
+ the log level. Messages of the given severity or higher will be logged,
+ and messages of lower severity will be filtered out. ``off`` filters out
+ all messages. See `ovs-appctl` for a definition of each log level.
+
+ Case is not significant within *spec*.
+
+ Regardless of the log levels set for ``file``, logging to a file will not
+ take place unless |program-name| was invoked with the :option:`--log-file`
+ option.
+
+ For compatibility with older versions of OVS, ``any`` is accepted as a word
+ but has no effect.
+
+.. object:: vlog/set PATTERN:destination:pattern
+
+ Sets the log pattern for *destination* to *pattern*. Refer to
+ `ovs-appctl` for a description of the valid syntax for *pattern*.
+
+.. object:: vlog/list
+
+ Lists the supported logging modules and their current levels.
+
+.. object:: vlog/list-pattern
+
+ Lists logging patterns used for each destination.
+
+.. object:: vlog/close
+
+ Causes |program-name| to close its log file, if it is open. (Use
+ ``vlog/reopen`` to reopen it later.)
+
+.. object:: vlog/reopen
+
+ Causes |program-name| to close its log file, if it is open, and then reopen
+ it. (This is useful after rotating log files, to cause a new log file to
+ be used.)
+
+ This has no effect unless |program-name| was invoked with the
+ :option:`--log-file` option.
+
+.. object:: vlog/disable-rate-limit [module]
+.. object:: vlog/enable-rate-limit [module]...
+
+ By default, |program-name| limits the rate at which certain messages can be
+ logged. When a message would appear more frequently than the limit, it is
+ suppressed. This saves disk space, makes logs easier to read, and speeds
+ up execution, but occasionally troubleshooting requires more detail.
+ Therefore, ``vlog/disable-rate-limit`` allows rate limits to be disabled at
+ the level of an individual log module. Specify one or more module names,
+ as displayed by the ``vlog/list`` command. Specifying either no module
+ names at all or the keyword ``any`` disables rate limits for every log
+ module.
+
+ The ``vlog/enable-rate-limit`` command, whose syntax is the same as
+ ``vlog/disable-rate-limit``, can be used to re-enable a rate limit that was
+ previously disabled.
diff --git a/Documentation/ref/vlog.inc b/Documentation/ref/vlog.inc
new file mode 100644
index 0000000..3d8493b
--- /dev/null
+++ b/Documentation/ref/vlog.inc
@@ -0,0 +1,88 @@
+.. option:: -v <verbosity>, --verbose <verbosity>
+
+ Sets logging levels. Without any argument, sets the log level for every
+ module and destination to ``dbg``. Otherwise, the argument must be one of
+ the following:
+
+ ``<spec>``
+
+ *spec* is a list of words separated by spaces or commas or colons, up to
+ one from each category below:
+
+ - A valid module name, as displayed by the ``vlog/list`` command on
+ `ovs-appctl(8)`, limits the log level change to the specified module.
+
+ - ``syslog``, ``console``, or ``file``, to limit the log level change to
+ only to the system log, to the console, or to a file, respectively. (If
+ :option:`--detach` is specified, |program-name| closes its standard
+ file descriptors, so logging to the console will have no effect.)
+
+ On Windows platform, ``syslog`` is accepted as a word and is only
+ useful along with the :option:`--syslog-target` option (the word has no
+ effect otherwise).
+
+ - ``off``, ``emer``, ``err``, ``warn``, ``info``, or ``dbg``, to control
+ the log level. Messages of the given severity or higher will be
+ logged, and messages of lower severity will be filtered out. ``off``
+ filters out all messages. See `ovs-appctl(8)` for a definition of each
+ log level.
+
+ Case is not significant within *spec*.
+
+ Regardless of the log levels set for ``file``, logging to a file will not
+ take place unless :option:`--log-file` is also specified (see below).
+
+ For compatibility with older versions of OVS, ``any`` is accepted as a word
+ but has no effect.
+
+ ``PATTERN:<destination>:<pattern>``
+
+ Sets the log pattern for *destination* to *pattern*. Refer to
+ ``ovs-appctl(8)`` for a description of the valid syntax for *pattern*.
+
+ ``FACILITY:<facility>``
+
+ Sets the RFC5424 facility of the log message. *facility* can be one of
+ ``kern``, ``user``, ``mail``, ``daemon``, ``auth``, ``syslog``, ``lpr``,
+ ``news``, ``uucp``, ``clock``, ``ftp``, ``ntp``, ``audit``, ``alert``,
+ ``clock2``, ``local0``, ``local1``, ``local2``, ``local3``, ``local4``,
+ ``local5``, ``local6`` or ``local7``. If this option is not specified,
+ ``daemon`` is used as the default for the local system syslog and
+ ``local0`` is used while sending a message to the target provided via the
+ :option:`--syslog-target` option.
+
+.. option:: --log-file <file>
+
+ Enables logging to a file. If *file* is specified, then it is used as the
+ exact name for the log file. The default log file name used if *file* is
+ omitted is `@LOGDIR@/|program-name|.log`.
+
+.. option:: --syslog-target <host:port>
+
+ Send syslog messages to UDP *port* on *host*, in addition to the system
+ syslog. The *host* must be a numerical IP address, not a hostname.
+
+.. option:: --syslog-method=method
+
+ Specify *method* how syslog messages should be sent to syslog daemon.
+ Following forms are supported:
+
+ - ``libc``, use libc ``syslog()`` function. This is the default behavior.
+ Downside of using this options is that libc adds fixed prefix to every
+ message before it is actually sent to the syslog daemon over ``/dev/log``
+ UNIX domain socket.
+
+ - ``unix:file``, use UNIX domain socket directly. It is possible to specify
+ arbitrary message format with this option. However, ``rsyslogd 8.9`` and
+ older versions use hard coded parser function anyway that limits UNIX
+ domain socket use. If you want to use arbitrary message format with
+ older ``rsyslogd`` versions, then use UDP socket to localhost IP address
+ instead.
+
+ - ``udp:ip:port``, use UDP socket. With this method it is possible to use
+ arbitrary message format also with older ``rsyslogd``. When sending
+ syslog messages over UDP socket extra precaution needs to be taken into
+ account, for example, syslog daemon needs to be configured to listen on
+ the specified UDP port, accidental iptables rules could be interfering
+ with local syslog traffic and there are some security considerations that
+ apply to UDP sockets, but do not apply to UNIX domain sockets.
--
2.9.3
More information about the dev
mailing list