From patchwork Thu May 11 01:32:19 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stephen Finucane X-Patchwork-Id: 760890 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from mail.linuxfoundation.org (mail.linuxfoundation.org [140.211.169.12]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 3wNbGF386Pz9s7y for ; Thu, 11 May 2017 11:33:09 +1000 (AEST) Authentication-Results: ozlabs.org; dkim=fail reason="key not found in DNS" (0-bit key; unprotected) header.d=that.guru header.i=@that.guru header.b="s2vrnoX7"; dkim-atps=neutral Received: from mail.linux-foundation.org (localhost [127.0.0.1]) by mail.linuxfoundation.org (Postfix) with ESMTP id D9A61B4A; Thu, 11 May 2017 01:32:35 +0000 (UTC) X-Original-To: dev@openvswitch.org Delivered-To: ovs-dev@mail.linuxfoundation.org Received: from smtp1.linuxfoundation.org (smtp1.linux-foundation.org [172.17.192.35]) by mail.linuxfoundation.org (Postfix) with ESMTPS id A8EF4B37 for ; Thu, 11 May 2017 01:32:34 +0000 (UTC) X-Greylist: from auto-whitelisted by SQLgrey-1.7.6 Received: from caracal.maple.relay.mailchannels.net (caracal.maple.relay.mailchannels.net [23.83.214.30]) by smtp1.linuxfoundation.org (Postfix) with ESMTPS id 6521FF3 for ; Thu, 11 May 2017 01:32:31 +0000 (UTC) X-Sender-Id: mxroute|x-authuser|stephen@that.guru Received: from relay.mailchannels.net (localhost [127.0.0.1]) by relay.mailchannels.net (Postfix) with ESMTP id A05585C0623 for ; Thu, 11 May 2017 01:32:30 +0000 (UTC) Received: from relay008.localdomain (unknown [100.96.129.223]) (Authenticated sender: mxroute) by relay.mailchannels.net (Postfix) with ESMTPA id D9C4D5C2BB8 for ; Thu, 11 May 2017 01:32:29 +0000 (UTC) X-Sender-Id: mxroute|x-authuser|stephen@that.guru Received: from relay008.localdomain (relay008.mxroute.com [172.20.88.133]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384) by 0.0.0.0:2500 (trex/5.9.2); Thu, 11 May 2017 01:32:30 +0000 X-MC-Relay: Neutral X-MailChannels-SenderId: mxroute|x-authuser|stephen@that.guru X-MailChannels-Auth-Id: mxroute X-Celery-Skirt: 170319ea53155898_1494466350471_2914588395 X-MC-Loop-Signature: 1494466350471:2151970771 X-MC-Ingress-Time: 1494466350470 Received: from one.mxroute.com (one-outgoing.mxroute.com [23.92.70.115]) by relay008.localdomain (Postfix) with ESMTPS id EEA0F402D0 for ; Thu, 11 May 2017 01:32:28 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=that.guru; s=default; h=References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Sender:Reply-To:MIME-Version:Content-Type:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=aYrtcfuLNLBVCbA6MoO6C3fbgfpFUVS/cm+sCQLC5dg=; b=s2vrnoX7a7kaw7lyYU3omkiQqN gROSLb5jlIGUgu2V28t97zPcLbLgZUOYFkv6/Hjbts8Blsqs9qLeEKAiXZTMjQuw8C78F/Vno645K sYMbkeTU5pIiBC5Go21/fjf8HhXgDUpKEHpIF89f+QIFTadmVfkbDLy3mG5V1IrNkEL3gB3lN/fau tmufUzghTaGPZ1fZFWwzSplJakc8CMeG+xjNQnk3dDlC9ph3vKCaDUcQY8Ann/UeC0yMI0GhOnafE wc3MTxKS/R6I+VZxz/Ux2JF3+d1tHCVfD913Dr5+UyYXnYFeD/gWscflTqpSCHjw277xWcpbVIR4v MSo34bLQ==; From: Stephen Finucane To: dev@openvswitch.org Date: Wed, 10 May 2017 21:32:19 -0400 Message-Id: <20170511013219.28254-2-stephen@that.guru> X-Mailer: git-send-email 2.9.3 In-Reply-To: <20170511013219.28254-1-stephen@that.guru> References: <20170511013219.28254-1-stephen@that.guru> X-OutGoing-Spam-Status: No, score=-9.2 X-AuthUser: stephen@that.guru X-Spam-Status: No, score=-1.8 required=5.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_NONE,T_DKIM_INVALID autolearn=no version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on smtp1.linux-foundation.org Subject: [ovs-dev] [RFC 2/2] doc: Convert ovs-vswitchd to rST X-BeenThere: ovs-dev@openvswitch.org X-Mailman-Version: 2.1.12 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Sender: ovs-dev-bounces@openvswitch.org Errors-To: ovs-dev-bounces@openvswitch.org 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. hello-world ) and nesting italics and bold (i.e. hello-world) 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 PATTERN:: Description FACILITY: Description This is necessary if we want to make best use of the Sphinx indexing. - TODO Signed-off-by: Stephen Finucane --- 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@. 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 + + 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] + 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 + + 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 , --private-key + + Specifies a PEM file containing the private key used as |program-name|'s + identity for outgoing SSL connections. + +.. option:: -c , --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 , --ca-cert + + Configure verification of certificates presented by SSL peers. + + There are two possible values: + + + + 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 + + Sets the name of the control socket on which |program-name| listens for + runtime management commands (see :ref:`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 , --verbose + + 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* 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::`` + + Sets the log pattern for *destination* to *pattern*. Refer to + ``ovs-appctl(8)`` for a description of the valid syntax for *pattern*. + + ``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 + + 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 + + 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.