diff options
author | Ben Pfaff <blp@ovn.org> | 2019-10-10 14:29:42 -0700 |
---|---|---|
committer | Ben Pfaff <blp@ovn.org> | 2019-12-02 12:35:42 -0800 |
commit | 39b5e46312b946ab594057c7ae854734b2f65110 (patch) | |
tree | 0a6afa975f928b5440f0c03902b817c3ecd8f5f1 | |
parent | aa34a87e7ee319d106bea59f2580d771642140ad (diff) | |
download | openvswitch-39b5e46312b946ab594057c7ae854734b2f65110.tar.gz |
Documentation: Convert multiple manpages to ReST.
Tested-by: Numan Siddique <numans@ovn.org>
Acked-by: Numan Siddique <numans@ovn.org>
Signed-off-by: Ben Pfaff <blp@ovn.org>
-rw-r--r-- | Documentation/automake.mk | 7 | ||||
-rw-r--r-- | Documentation/conf.py | 14 | ||||
-rw-r--r-- | Documentation/ref/index.rst | 35 | ||||
-rw-r--r-- | Documentation/ref/ovs-appctl.8.rst | 332 | ||||
-rw-r--r-- | Documentation/ref/ovs-ctl.8.rst | 491 | ||||
-rw-r--r-- | Documentation/ref/ovs-l3ping.8.rst | 129 | ||||
-rw-r--r-- | Documentation/ref/ovs-parse-backtrace.8.rst | 34 | ||||
-rw-r--r-- | Documentation/ref/ovs-pki.8.rst | 251 | ||||
-rw-r--r-- | Documentation/ref/ovs-tcpdump.8.rst | 68 | ||||
-rw-r--r-- | Documentation/ref/ovs-tcpundump.1.rst | 39 | ||||
-rw-r--r-- | manpages.mk | 59 | ||||
-rw-r--r-- | utilities/automake.mk | 19 | ||||
-rw-r--r-- | utilities/ovs-appctl.8.in | 293 | ||||
-rw-r--r-- | utilities/ovs-ctl.8 | 518 | ||||
-rw-r--r-- | utilities/ovs-l3ping.8.in | 110 | ||||
-rw-r--r-- | utilities/ovs-parse-backtrace.8 | 28 | ||||
-rw-r--r-- | utilities/ovs-pki.8.in | 243 | ||||
-rw-r--r-- | utilities/ovs-tcpdump.8.in | 55 | ||||
-rw-r--r-- | utilities/ovs-tcpundump.1.in | 32 |
19 files changed, 1376 insertions, 1381 deletions
diff --git a/Documentation/automake.mk b/Documentation/automake.mk index 5f7c3e07b..f2ca17bad 100644 --- a/Documentation/automake.mk +++ b/Documentation/automake.mk @@ -153,6 +153,13 @@ endif # rST formatted manpages under Documentation/ref. RST_MANPAGES = \ + ovs-appctl.8.rst \ + ovs-ctl.8.rst \ + ovs-l3ping.8.rst \ + ovs-parse-backtrace.8.rst \ + ovs-pki.8.rst \ + ovs-tcpdump.8.rst \ + ovs-tcpundump.1.rst \ ovs-test.8.rst \ ovs-vlan-test.8.rst \ ovsdb-server.7.rst \ diff --git a/Documentation/conf.py b/Documentation/conf.py index 0a61dc3f3..6bbfc02bd 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -114,8 +114,22 @@ html_static_path = ['_static'] # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). _man_pages = [ + ('ovs-appctl.8', + u'utility for configuring running Open vSwitch daemons'), + ('ovs-ctl.8', + u'OVS startup helper script'), + ('ovs-l3ping.8', + u'check network deployment for L3 tunneling problems'), + ('ovs-parse-backtrace.8', + u'parses ovs-appctl backtrace output'), + ('ovs-pki.8', + u'OpenFlow public key infrastructure management utility'), ('ovs-sim.1', u'Open vSwitch simulator environment'), + ('ovs-tcpdump.8', + u'Dump traffic from an Open vSwitch port using tcpdump'), + ('ovs-tcpundump.1', + u'convert "tcpdump -xx" output to hex strings'), ('ovs-test.8', u'Check Linux drivers for performance, vlan and L3 tunneling problems'), ('ovs-vlan-test.8', diff --git a/Documentation/ref/index.rst b/Documentation/ref/index.rst index 83f031c4f..274dacbeb 100644 --- a/Documentation/ref/index.rst +++ b/Documentation/ref/index.rst @@ -39,7 +39,14 @@ time: .. toctree:: :maxdepth: 3 + ovs-appctl.8 + ovs-ctl.8 + ovs-l3ping.8 + ovs-pki.8 ovs-sim.1 + ovs-parse-backtrace.8 + ovs-tcpdump.8 + ovs-tcpundump.1 ovs-test.8 ovs-vlan-test.8 ovsdb-server.7 @@ -54,18 +61,10 @@ The remainder are still in roff format can be found below: - `(pdf) <http://www.openvswitch.org/support/dist-docs/ovs-actions.7.pdf>`__ - `(html) <http://www.openvswitch.org/support/dist-docs/ovs-actions.7.html>`__ - `(plain text) <http://www.openvswitch.org/support/dist-docs/ovs-actions.7.txt>`__ - * - ovs-appctl(8) - - `(pdf) <http://www.openvswitch.org/support/dist-docs/ovs-appctl.8.pdf>`__ - - `(html) <http://www.openvswitch.org/support/dist-docs/ovs-appctl.8.html>`__ - - `(plain text) <http://www.openvswitch.org/support/dist-docs/ovs-appctl.8.txt>`__ * - ovs-bugtool(8) - `(pdf) <http://www.openvswitch.org/support/dist-docs/ovs-bugtool.8.pdf>`__ - `(html) <http://www.openvswitch.org/support/dist-docs/ovs-bugtool.8.html>`__ - `(plain text) <http://www.openvswitch.org/support/dist-docs/ovs-bugtool.8.txt>`__ - * - ovs-ctl(8) - - `(pdf) <http://www.openvswitch.org/support/dist-docs/ovs-ctl.8.pdf>`__ - - `(html) <http://www.openvswitch.org/support/dist-docs/ovs-ctl.8.html>`__ - - `(plain text) <http://www.openvswitch.org/support/dist-docs/ovs-ctl.8.txt>`__ * - ovsdb-client(1) - `(pdf) <http://www.openvswitch.org/support/dist-docs/ovsdb-client.1.pdf>`__ - `(html) <http://www.openvswitch.org/support/dist-docs/ovsdb-client.1.html>`__ @@ -90,34 +89,14 @@ The remainder are still in roff format can be found below: - `(pdf) <http://www.openvswitch.org/support/dist-docs/ovs-fields.7.pdf>`__ - `(html) <http://www.openvswitch.org/support/dist-docs/ovs-fields.7.html>`__ - `(plain text) <http://www.openvswitch.org/support/dist-docs/ovs-fields.7.txt>`__ - * - ovs-l3ping(8) - - `(pdf) <http://www.openvswitch.org/support/dist-docs/ovs-l3ping.8.pdf>`__ - - `(html) <http://www.openvswitch.org/support/dist-docs/ovs-l3ping.8.html>`__ - - `(plain text) <http://www.openvswitch.org/support/dist-docs/ovs-l3ping.8.txt>`__ * - ovs-ofctl(8) - `(pdf) <http://www.openvswitch.org/support/dist-docs/ovs-ofctl.8.pdf>`__ - `(html) <http://www.openvswitch.org/support/dist-docs/ovs-ofctl.8.html>`__ - `(plain text) <http://www.openvswitch.org/support/dist-docs/ovs-ofctl.8.txt>`__ - * - ovs-parse-backtrace(8) - - `(pdf) <http://www.openvswitch.org/support/dist-docs/ovs-parse-backtrace.8.pdf>`__ - - `(html) <http://www.openvswitch.org/support/dist-docs/ovs-parse-backtrace.8.html>`__ - - `(plain text) <http://www.openvswitch.org/support/dist-docs/ovs-parse-backtrace.8.txt>`__ * - ovs-pcap(1) - `(pdf) <http://www.openvswitch.org/support/dist-docs/ovs-pcap.1.pdf>`__ - `(html) <http://www.openvswitch.org/support/dist-docs/ovs-pcap.1.html>`__ - `(plain text) <http://www.openvswitch.org/support/dist-docs/ovs-pcap.1.txt>`__ - * - ovs-pki(8) - - `(pdf) <http://www.openvswitch.org/support/dist-docs/ovs-pki.8.pdf>`__ - - `(html) <http://www.openvswitch.org/support/dist-docs/ovs-pki.8.html>`__ - - `(plain text) <http://www.openvswitch.org/support/dist-docs/ovs-pki.8.txt>`__ - * - ovs-tcpdump(8) - - `(pdf) <http://www.openvswitch.org/support/dist-docs/ovs-tcpdump.8.pdf>`__ - - `(html) <http://www.openvswitch.org/support/dist-docs/ovs-tcpdump.8.html>`__ - - `(plain text) <http://www.openvswitch.org/support/dist-docs/ovs-tcpdump.8.txt>`__ - * - ovs-tcpundump(1) - - `(pdf) <http://www.openvswitch.org/support/dist-docs/ovs-tcpundump.1.pdf>`__ - - `(html) <http://www.openvswitch.org/support/dist-docs/ovs-tcpundump.1.html>`__ - - `(plain text) <http://www.openvswitch.org/support/dist-docs/ovs-tcpundump.1.txt>`__ * - ovs-test(8) - `(pdf) <http://www.openvswitch.org/support/dist-docs/ovs-test.8.pdf>`__ - `(html) <http://www.openvswitch.org/support/dist-docs/ovs-test.8.html>`__ diff --git a/Documentation/ref/ovs-appctl.8.rst b/Documentation/ref/ovs-appctl.8.rst new file mode 100644 index 000000000..a488d9f48 --- /dev/null +++ b/Documentation/ref/ovs-appctl.8.rst @@ -0,0 +1,332 @@ +========== +ovs-appctl +========== + +Synopsis +======== + +``ovs-appctl`` +[``--target=``<target> | ``-t`` <target>] +[``--timeout=``<secs> | ``-T`` <secs>] +<command> [<arg>...] + +``ovs-appctl --help`` + +``ovs-appctl --version`` + +Description +=========== + +Open vSwitch daemons accept certain commands at runtime to control +their behavior and query their settings. Every daemon accepts a +common set of commands documented under `Common Commands`_ below. +Some daemons support additional commands documented in their own +manpages. ``ovs-vswitchd`` in particular accepts a number of +additional commands documented in ``ovs-vswitchd(8)``. + +The ``ovs-appctl`` program provides a simple way to invoke these +commands. The command to be sent is specified on ``ovs-appctl``'s +command line as non-option arguments. ``ovs-appctl`` sends the +command and prints the daemon's response on standard output. + +In normal use only a single option is accepted: + +* ``-t`` <target> or ``--target`` <target> + + Tells ``ovs-appctl`` which daemon to contact. + + If <target> begins with ``/`` it must name a Unix domain socket on + which an Open vSwitch daemon is listening for control channel + connections. By default, each daemon listens on a Unix domain socket + in the rundir (e.g. ``/run``) named ``<program>.<pid>.ctl``, where + <program> is the program's name and <pid> is its process ID. For + example, if ``ovs-vswitchd`` has PID 123, it would listen on + ``ovs-vswitchd.123.ctl``. + + Otherwise, ``ovs-appctl`` looks in the rundir for a pidfile, that is, + a file whose contents are the process ID of a running process as a + decimal number, named ``<target>.pid``. (The ``--pidfile`` option + makes an Open vSwitch daemon create a pidfile.) ``ovs-appctl`` reads + the pidfile, then looks in the rundir for a Unix socket named + ``<target>.<pid>.ctl``, where <pid> is replaced by the process ID read + from the pidfile, and uses that file as if it had been specified + directly as the target. + + On Windows, <target> can be an absolute path to a file that contains a + localhost TCP port on which an Open vSwitch daemon is listening for + control channel connections. By default, each daemon writes the TCP + port on which it is listening for control connection into the file + ``<program>.ctl`` located inside the rundir. If <target> is not an + absolute path, ``ovs-appctl`` looks in the rundir for a file named + ``<target>.ctl``. The default target is ``ovs-vswitchd``. + +* ``-T <secs>`` or ``--timeout=<secs>`` + + By default, or with a <secs> of ``0``, ``ovs-appctl`` waits forever to + connect to the daemon and receive a response. This option limits + runtime to approximately <secs> seconds. If the timeout expires, + ``ovs-appctl`` exits with a ``SIGALRM`` signal. + +Common Commands +=============== + +Every Open vSwitch daemon supports a common set of commands, which are +documented in this section. + +General Commands +---------------- + +These commands display daemon-specific commands and the running version. +Note that these commands are different from the ``--help`` and +``--version`` options that return information about the +``ovs-appctl`` utility itself. + +* ``list-commands`` + + Lists the commands supported by the target. + +* ``version`` + + Displays the version and compilation date of the target. + +Logging Commands +---------------- + +Open vSwitch has several log levels. The highest-severity log level is: + +* ``off`` + + No message is ever logged at this level, so setting a logging + destination's log level to ``off`` disables logging to that destination. + +The following log levels, in order of descending severity, are +available: + +* ``emer`` + + A major failure forced a process to abort. + +* ``err`` + + A high-level operation or a subsystem failed. Attention is + warranted. + +* ``warn`` + + A low-level operation failed, but higher-level subsystems may be able + to recover. + +* ``info`` + + Information that may be useful in retrospect when investigating + a problem. + +* ``dbg`` + + Information useful only to someone with intricate knowledge of the + system, or that would commonly cause too-voluminous log output. Log + messages at this level are not logged by default. + +Every Open vSwitch daemon supports the following commands for examining +and adjusting log levels: + +* ``vlog/list`` + + Lists the known logging modules and their current levels. + +* ``vlog/list-pattern`` + + Lists logging pattern used for each destination. + +* ``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(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. + + On Windows platform, ``syslog`` is only useful if <target> was + started with the ``--syslog-target`` option (it 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. + + Case is not significant within <spec>. + + Regardless of the log levels set for ``file``, logging to a file + will not take place unless the target application was invoked with the + ``--log-file`` option. + + For compatibility with older versions of OVS, ``any`` is accepted + within <spec> but it has no effect. + +* ``vlog/set PATTERN:<destination>:<pattern>`` + + Sets the log pattern for <destination> to <pattern>. Each time a + message is logged to <destination>, <pattern> determines the + message's formatting. Most characters in <pattern> are copied + literally to the log, but special escapes beginning with ``%`` are + expanded as follows: + + * ``%A`` + + The name of the application logging the message, e.g. ``ovs-vswitchd``. + + * ``%B`` + + The RFC5424 syslog PRI of the message. + + * ``%c`` + + The name of the module (as shown by ``ovs-appctl --list``) logging + the message. + + * ``%d`` + + The current date and time in ISO 8601 format (YYYY-MM-DD HH:MM:SS). + + * ``%d{<format>}`` + + The current date and time in the specified <format>, which takes + the same format as the <template> argument to ``strftime(3)``. As + an extension, any ``#`` characters in <format> will be replaced by + fractional seconds, e.g. use ``%H:%M:%S.###`` for the time to the + nearest millisecond. Sub-second times are only approximate and + currently decimal places after the third will always be reported + as zero. + + * ``%D`` + + The current UTC date and time in ISO 8601 format (YYYY-MM-DD + HH:MM:SS). + + * ``%D{<format>}`` + + The current UTC date and time in the specified <format>, which + takes the same format as the <template> argument to + ``strftime``(3). Supports the same extension for sub-second + resolution as ``%d{...}``. + + * ``%E`` + + The hostname of the node running the application. + + * ``%m`` + + The message being logged. + + * ``%N`` + + A serial number for this message within this run of the program, + as a decimal number. The first message a program logs has serial + number 1, the second one has serial number 2, and so on. + + * ``%n`` + + A new-line. + + * ``%p`` + + The level at which the message is logged, e.g. ``DBG``. + + * ``%P`` + + The program's process ID (pid), as a decimal number. + + * ``%r`` + + The number of milliseconds elapsed from the start of the + application to the time the message was logged. + + * ``%t`` + + The subprogram name, that is, an identifying name for the process + or thread that emitted the log message, such as ``monitor`` for + the process used for ``--monitor`` or ``main`` for the primary + process or thread in a program. + + * ``%T`` + + The subprogram name enclosed in parentheses, e.g. ``(monitor)``, + or the empty string for the primary process or thread in a + program. + + * ``%%`` + + A literal ``%``. + + A few options may appear between the ``%`` and the format specifier + character, in this order: + + * ``-`` + + Left justify the escape's expansion within its field width. Right + justification is the default. + + * ``0`` + + Pad the field to the field width with ``0`` characters. Padding + with spaces is the default. + + * <width> + + A number specifies the minimum field width. If the escape expands + to fewer characters than <width> then it is padded to fill the + field width. (A field wider than <width> is not truncated to + fit.) + + The default pattern for console and file output is ``%D{%Y-%m-%dT + %H:%M:%SZ}|%05N|%c|%p|%m``; for syslog output, ``%05N|%c|%p|%m``. + + Daemons written in Python (e.g. ``ovs-xapi-sync``) do not allow + control over the log pattern. + +* ``vlog/set 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``. + +* ``vlog/close`` + + Causes the daemon to close its log file, if it is open. (Use + ``vlog/reopen`` to reopen it later.) + +* ``vlog/reopen`` + + Causes the daemon 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 if the target application was not invoked with + the ``--log-file`` option. + +Options +======= + +.. option:: -h, --help + + Prints a brief help message to the console. + +.. option:: -V, --version + + Prints version information to the console. + +See Also +======== + +``ovs-appctl`` can control all Open vSwitch daemons, including +``ovs-vswitchd(8)`` and ``ovsdb-server(1)``. diff --git a/Documentation/ref/ovs-ctl.8.rst b/Documentation/ref/ovs-ctl.8.rst new file mode 100644 index 000000000..7cfc41322 --- /dev/null +++ b/Documentation/ref/ovs-ctl.8.rst @@ -0,0 +1,491 @@ +======= +ovs-ctl +======= + +Synopsis +======== + +``ovs-ctl --system-id=random|<uuid> [<options>] start`` + +``ovs-ctl stop`` + +``ovs-ctl --system-id=random|<uuid> [<options>] restart`` + +``ovs-ctl status`` + +``ovs-ctl version`` + +``ovs-ctl [<options>] load-kmod`` + +``ovs-ctl --system-id=random|<uuid> [<options>] force-reload-kmod`` + +``ovs-ctl [--protocol=<protocol>] [--sport=<sport>] [--dport=<dport>] +enable-protocol`` + +``ovs-ctl delete-transient-ports`` + +``ovs-ctl help | -h | --help`` + +``ovs-ctl --version`` + +Description +=========== + +The ``ovs-ctl`` program starts, stops, and checks the status of +Open vSwitch daemons. It is not meant to be invoked directly by +system administrators but to be called internally by system startup +scripts. + + +Each ``ovs-ctl`` command is described separately below. + +The ``start`` command +--------------------- + +The ``start`` command starts Open vSwitch. It performs the +following tasks: + +1. Loads the Open vSwitch kernel module. If this fails, and the Linux + bridge module is loaded but no bridges exist, it tries to unload + the bridge module and tries loading the Open vSwitch kernel module + again. (This is because the Open vSwitch kernel module cannot + coexist with the Linux bridge module before 2.6.37.) + +The ``start`` command skips the following steps if ``ovsdb-server`` is +already running: + +2. If the Open vSwitch database file does not exist, it creates it. + If the database does exist, but it has an obsolete version, it + upgrades it to the latest schema. + +3. Starts ``ovsdb-server``, unless the ``--no-ovsdb-server`` command + option is given. + +4. Initializes a few values inside the database. + +5. If the ``--delete-bridges`` option was used, deletes all of the + bridges from the database. + +6. If the ``--delete-transient-ports`` option was used, deletes all + ports that have ``other_config:transient`` set to true. + +The ``start`` command skips the following step if ``ovs-vswitchd`` is +already running, or if the ``--no-ovs-vswitchd`` command option is +given: + +7. Starts ``ovs-vswitchd``. + +Options +~~~~~~~ + +Several command-line options influence the ``start`` command's +behavior. Some form of the following option should ordinarily be +specified: + +* ``--system-id=<uuid>`` or ``--system-id=random`` + + This specifies a unique system identifier to store into + ``external-ids:system-id`` in the database's ``Open_vSwitch`` table. + Remote managers that talk to the Open vSwitch database server over + network protocols use this value to identify and distinguish Open + vSwitch instances, so it should be unique (at least) within OVS + instances that will connect to a single controller. + + When ``random`` is specified, ``ovs-ctl`` will generate a random ID + that persists from one run to another (stored in a file). When + another string is specified ``ovs-ctl`` uses it literally. + +The following options should be specified if the defaults are not +suitable: + +* ``--system-type=<type>`` or ``--system-version=<version>`` + + Sets the value to store in the ``system-type`` and + ``system-version`` columns, respectively, in the database's + ``Open_vSwitch`` table. Remote managers may use these values too + determine the kind of system to which they are connected (primarily + for display to human administrators). + + When not specified, ``ovs-ctl`` uses values from the optional + ``system-type.conf`` and ``system-version.conf`` files (see + `Files`_) or it uses the ``lsb_release`` program, if present, to + provide reasonable defaults. + +The following options are also likely to be useful: + +* ``--external-id="<name>=<value>"`` + + Sets ``external-ids:<name>`` to <value> in the database's + ``Open_vSwitch`` table. Specifying this option multiple times adds + multiple key-value pairs. + +* ``--delete-bridges`` + + Ordinarily Open vSwitch bridges persist from one system boot to the + next, as long as the database is preserved. Some environments + instead expect to re-create all of the bridges and other + configuration state on every boot. This option supports that, by + deleting all Open vSwitch bridges after starting ``ovsdb-server`` + but before starting ``ovs-vswitchd``. + +* ``--delete-transient-ports`` + + Deletes all ports that have ``other_config:transient`` set to + ``true``. This is important on certain environments where some + ports are going to be recreated after reboot, but other ports need + to be persisted in the database. + +* ``--ovs-user=user[:group]`` + + Ordinarily Open vSwitch daemons are started as the user invoking the + ovs-ctl command. Some system administrators would prefer to have + the various daemons spawn as different users in their environments. + This option allows passing the ``--user`` option to the + ``ovsdb-server`` and ``ovs-vswitchd`` daemons, allowing them to + change their privilege levels. + +The following options are less important: + +* ``--no-monitor`` + + By default ``ovs-ctl`` passes ``--monitor`` to ``ovs-vswitchd`` and + ``ovsdb-server``, requesting that it spawn a process monitor which + will restart the daemon if it crashes. This option suppresses that + behavior. + +* ``--daemon-cwd=<directory>`` + + Specifies the current working directory that the OVS daemons should + run from. The default is ``/`` (the root directory) if this option + is not specified. (This option is useful because most systems + create core files in a process's current working directory and + because a file system that is in use as a process's current working + directory cannot be unmounted.) + +* ``--no-force-corefiles`` + + By default, ``ovs-ctl`` enables core dumps for the OVS daemons. + This option disables that behavior. + +* ``--no-mlockall`` + + By default ``ovs-ctl`` passes ``--mlockall`` to ``ovs-vswitchd``, + requesting that it lock all of its virtual memory, preventing it + from being paged to disk. This option suppresses that behavior. + +* ``--no-self-confinement`` + + Disable self-confinement for ``ovs-vswitchd`` and ``ovsdb-server`` + daemons. This flag may be used when, for example, OpenFlow + controller creates its Unix Domain Socket outside OVS run directory + and OVS needs to connect to it. It is better to stick with the + default behavior and not to use this flag, unless: + + - You have Open vSwitch running under SELinux or AppArmor Mandatory + Access Control that would prevent OVS from messing with sockets + outside ordinary OVS directories. + + - You believe that relying on protocol handshakes (e.g. OpenFlow) is + enough to prevent OVS to adversely interact with other daemons + running on your system. + + - You don't have much worries of remote OVSDB exploits in the first + place, because, perhaps, OVSDB manager is running on the same host + as OVS and share similar attack vectors. + +* ``--ovsdb-server-priority=<niceness>`` or + ``--ovs-vswitchd-priority=<niceness>`` + + Sets the ``nice(1)`` level used for each daemon. All of them + default to ``-10``. + +* ``--ovsdb-server-wrapper=<wrapper>`` or + ``--ovs-vswitchd-wrapper=<wrapper>`` + + Configures the specified daemon to run under <wrapper>, which is one + of the following: + + * ``valgrind``: Run the daemon under ``valgrind(1)``, if it is + installed, logging to ``<daemon>.valgrind.log.<pid>`` in the log + directory. + + * ``strace``: Run the daemon under ``strace(1)``, if it is + installed, logging to ``<daemon>.strace.log.<pid>`` in the log + directory. + + * ``glibc``: Enable GNU C library features designed to find memory + errors. + + By default, no wrapper is used. + + Each of the wrappers can expose bugs in Open vSwitch that lead to + incorrect operation, including crashes. The ``valgrind`` and + ``strace`` wrappers greatly slow daemon operations so they should + not be used in production. They also produce voluminous logs that + can quickly fill small disk partitions. The ``glibc`` wrapper is + less resource-intensive but still somewhat slows the daemons. + +The following options control file locations. They should only be +used if the default locations cannot be used. See ``FILES``, below, +for more information. + +* ``--db-file=<file>`` + + Overrides the file name for the OVS database. + +* ``--db-sock=<socket>`` + + Overrides the file name for the Unix domain socket used to connect + to ``ovsdb-server``. + +* ``--db-schema=<schema>`` + + Overrides the file name for the OVS database schema. + +* ``--extra-dbs=<file>`` + + Adds <file> as an extra database for ``ovsdb-server`` to serve out. + Multiple space-separated file names may also be specified. <file> + should begin with ``/``; if it does not, then it will be taken as + relative to <dbdir>. + +The ``stop`` command +-------------------- + +The ``stop`` command stops the ``ovs-vswitchd`` and ``ovsdb-server`` +daemons. It does not unload the Open vSwitch kernel modules. It can +take the same ``--no-ovsdb-server`` and ``--no-ovs-vswitchd`` options +as that of the ``start`` command. + +This command does nothing and finishes successfully if the OVS daemons +aren't running. + +The ``restart`` command +----------------------- + +The ``restart`` command performs a ``stop`` followed by a ``start`` +command. The command can take the same options as that of the +``start`` command. In addition, it saves and restores OpenFlow flows +for each individual bridge. + +The ``status`` command +---------------------- + +The ``status`` command checks whether the OVS daemons +``ovs-vswitchd`` and ``ovsdb-server`` are running and prints +messages with that information. It exits with status 0 if +the daemons are running, 1 otherwise. + +The ``version`` command +----------------------- + +The ``version`` command runs ``ovsdb-server --version`` and +``ovs-vswitchd --version``. + +The ``force-reload-kmod`` command +--------------------------------- + +The ``force-reload-kmod`` command allows upgrading the Open vSwitch +kernel module without rebooting. It performs the following tasks: + +1. Gets a list of OVS "internal" interfaces, that is, network + devices implemented by Open vSwitch. The most common examples of + these are bridge "local ports". + +2. Saves the OpenFlow flows of each bridge. + +3. Stops the Open vSwitch daemons, as if by a call to ``ovs-ctl + stop``. + +4. Saves the kernel configuration state of the OVS internal interfaces + listed in step 1, including IP and IPv6 addresses and routing table + entries. + +5. Unloads the Open vSwitch kernel module (including the bridge + compatibility module if it is loaded). + +6. Starts OVS back up, as if by a call to ``ovs-ctl start``. This + reloads the kernel module, restarts the OVS daemons and finally + restores the saved OpenFlow flows. + +7. Restores the kernel configuration state that was saved in step 4. + +8. Checks for daemons that may need to be restarted because they have + packet sockets that are listening on old instances of Open vSwitch + kernel interfaces and, if it finds any, prints a warning on stdout. + DHCP is a common example: if the ISC DHCP client is running on an + OVS internal interface, then it will have to be restarted after + completing the above procedure. (It would be nice if ``ovs-ctl`` + could restart daemons automatically, but the details are far too + specific to a particular distribution and installation.) + +``force-kmod-reload`` internally stops and starts OVS, so it accepts +all of the options accepted by the ``start`` command except for the +``--no-ovs-vswitchd`` option. + +The ``load-kmod`` command +------------------------- + +The ``load-kmod`` command loads the openvswitch kernel modules if they +are not already loaded. This operation also occurs as part of the +``start`` command. The motivation for providing the ``load-kmod`` +command is to allow errors when loading modules to be handled +separately from other errors that may occur when running the +``start`` command. + +By default the ``load-kmod`` command attempts to load the +``openvswitch`` kernel module. + +The ``enable-protocol`` command +------------------------------- + +The ``enable-protocol`` command checks for rules related to a +specified protocol in the system's ``iptables(8)`` configuration. If +there are no rules specifically related to that protocol, then it +inserts a rule to accept the specified protocol. + +More specifically: + +* If ``iptables`` is not installed or not enabled, this command does + nothing, assuming that lack of filtering means that the protocol is + enabled. + +* If the ``INPUT`` chain has a rule that matches the specified + protocol, then this command does nothing, assuming that whatever + rule is installed reflects the system administrator's decisions. + +* Otherwise, this command installs a rule that accepts traffic of the + specified protocol. + +This command normally completes successfully, even if it does nothing. +Only the failure of an attempt to insert a rule normally causes it to +return an exit code other than 0. + +The following options control the protocol to be enabled: + +* ``--protocol=<protocol>`` + + The name of the IP protocol to be enabled, such as ``gre`` or + ``tcp``. The default is ``gre``. + +* ``--sport=<sport>`` or ``--dport=<dport>`` + + TCP or UDP source or destination port to match. These are optional + and allowed only with ``--protocol=tcp`` or ``--protocol=udp``. + +The ``delete-transient-ports`` command +-------------------------------------- + +Deletes all ports that have the ``other_config:transient`` value set to true. + +The ``help`` command +-------------------- + +Prints a usage message and exits successfully. + +Options +======= + +In addition to the options listed for each command above, these +options control the behavior of several ``ovs-ctl`` commands. + +By default, ``ovs-ctl`` controls the ``ovsdb-server`` and +``ovs-vswitchd`` daemons. The following options restrict that control +to exclude one or the other: + +* ``--no-ovsdb-server`` + + Specifies that the ``ovs-ctl`` commands ``start``, ``stop``, and + ``restart`` should not modify the running status of + ``ovsdb-server``. + +* ``--no-ovs-vswitchd`` + + Specifies that the ``ovs-ctl`` commands ``start``, ``stop``, and + ``restart`` should not modify the running status of + ``ovs-vswitchd``. It is an error to include this option with the + ``force-reload-kmod`` command. + +Exit Status +=========== + +``ovs-ctl`` exits with status 0 on success and nonzero on failure. +The ``start`` command is considered to succeed if OVS is already +started; the ``stop`` command is considered to succeed if OVS is +already stopped. + +Environment +=========== + +The following environment variables affect ``ovs-ctl``: + +* ``PATH`` + + ``ovs-ctl`` does not hardcode the location of any of the programs + that it runs. ``ovs-ctl`` will add the <sbindir> and <bindir> that + were specified at ``configure`` time to ``PATH``, if they are not + already present. + +* ``OVS_LOGDIR``, ``OVS_RUNDIR``, ``OVS_DBDIR``, ``OVS_SYSCONFDIR``, + ``OVS_PKGDATADIR``, ``OVS_BINDIR``, ``OVS_SBINDIR`` + + Setting one of these variables in the environment overrides the + respective ``configure`` option, both for ``ovs-ctl`` itself and for + the other Open vSwitch programs that it runs. + +Files +===== + +``ovs-ctl`` uses the following files: + +* ``ovs-lib`` + + Shell function library used internally by ``ovs-ctl``. It must be + installed in the same directory as ``ovs-ctl``. + +* ``<logdir>/<daemon>.log`` + + Per-daemon logfiles. + +* ``<rundir>/<daemon>.pid`` + + Per-daemon pidfiles to track whether a daemon is running and with + what process ID. + +* ``<pkgdatadir>/vswitch.ovsschema`` + + The OVS database schema used to initialize the database (use + ``--db-schema`` to override this location). + +* ``<dbdir>/conf.db`` + + The OVS database (use ``--db-file`` to override this location). + +* ``<rundir>/openvswitch/db.sock`` + + The Unix domain socket used for local communication with + ``ovsdb-server`` (use ``--db-sock`` to override this location). + +* ``<sysconfdir>/openvswitch/system-id.conf`` + + The persistent system UUID created and read by + ``--system-id=random``. + +* ``<sysconfdir>/openvswitch/system-type.conf`` and + ``<sysconfdir>/openvswitch/system-version.conf`` + + The ``system-type`` and ``system-version`` values stored in the + database's ``Open_vSwitch`` table when not specified as a + command-line option. + +Example +======= + +The files ``debian/openvswitch-switch.init`` and +``xenserver/etc_init.d_openvswitch`` in the Open vSwitch source +distribution are good examples of how to use ``ovs-ctl``. + +See Also +======== + +``README.rst``, ``ovsdb-server(8)``, ``ovs-vswitchd(8)``. diff --git a/Documentation/ref/ovs-l3ping.8.rst b/Documentation/ref/ovs-l3ping.8.rst new file mode 100644 index 000000000..f9c88fcd6 --- /dev/null +++ b/Documentation/ref/ovs-l3ping.8.rst @@ -0,0 +1,129 @@ +========== +ovs-l3ping +========== + +Synopsis +======== + +``ovs-l3ping -s <TunnelRemoteIP>,<InnerIP>[/<mask>] -t <tunnelmode>`` + +``ovs-l3ping -s <TunnelRemoteIP>,<InnerIP>[/<mask>][:<ControlPort>] -t +<tunnelmode>`` + +``ovs-l3ping -c <TunnelRemoteIP>,<InnerIP>[/<mask>],<RemoteInnerIP> -t +<tunnelmode>`` + +``ovs-l3ping -c +<TunnelRemoteIP>,<InnerIP>[/<mask>][:<ControlPort>[:<DataPort>]],<RemoteInnerIP>[:<ControlPort>[:<DataPort>]] +[-b <targetbandwidth>] [-i <testinterval>] +-t <tunnelmode>`` + +``ovs-l3ping -h | --help`` + +``ovs-l3ping -V | --version`` + +Description +=========== + +The ``ovs-l3ping`` program may be used to check for problems that +could be caused by invalid routing policy, misconfigured firewall in +the tunnel path or a bad NIC driver. On one of the nodes, run +``ovs-l3ping`` in server mode and on the other node run it in client +mode. The client and server will establish L3 tunnel, over which +client will give further testing instructions. The ``ovs-l3ping`` +client will perform UDP and TCP tests. This tool is different from +``ovs-test`` that it encapsulates XML/RPC control connection over the +tunnel, so there is no need to open special holes in firewall. + +UDP tests can report packet loss and achieved bandwidth for various +datagram sizes. By default target bandwidth for UDP tests is 1Mbit/s. + +TCP tests report only achieved bandwidth, because kernel TCP stack +takes care of flow control and packet loss. + +Client Mode +----------- + +An ``ovs-l3ping`` client will create a L3 tunnel and connect over it +to the ``ovs-l3ping`` server to schedule the tests. <TunnelRemoteIP> +is the peer's IP address, where tunnel will be terminated. <InnerIP> +is the address that will be temporarily assigned during testing. All +test traffic originating from this IP address to the <RemoteInnerIP> +will be tunneled. It is possible to override default <ControlPort> +and <DataPort>, if there is any other application that already listens +on those two ports. + +Server Mode +----------- + +To conduct tests, ``ovs-l3ping`` server must be running. It is +required that both client and server <InnerIP> addresses are in the +same subnet. It is possible to specify <InnerIP> with netmask in CIDR +format. + +Options +======= + +One of ``-s`` or ``-c`` is required. The ``-t`` option is +also required. + +* ``-s <TunnelRemoteIP>,<InnerIP>[/<mask>][:<ControlPort>]`` or + ``--server <TunnelRemoteIP>,<InnerIP>[/<mask>][:<ControlPort>]`` + + Run in server mode and create L3 tunnel with the client that will be + accepting tunnel at <TunnelRemoteIP> address. The socket on + ``<InnerIP>[:<ControlPort>]`` will be used to receive further + instructions from the client. + +* ``-c + <TunnelRemoteIP>,<InnerIP>[/<mask>][:<ControlPort>[:<DataPort>]],<RemoteInnerIP>[:<ControlPort>[:<DataPort>]]`` + or ``--client + <TunnelRemoteIP>,<InnerIP>[/<mask>][:<ControlPort>[:<DataPort>]],<RemoteInnerIP>[:<ControlPort>[:<DataPort>]]`` + + Run in client mode and create L3 tunnel with the server on + <TunnelRemoteIP>. The client will use <InnerIP> to generate test + traffic with the server's <RemoteInnerIP>. + +* ``-b <targetbandwidth>`` or ``--bandwidth <targetbandwidth>`` + + Target bandwidth for UDP tests. The <targetbandwidth> must be given + in bits per second. Use postfix M or K to alter the target + bandwidth magnitude. + +* ``-i <testinterval>`` or ``--interval <testinterval>`` + + How long each test should run. By default 5 seconds. + +* ``-t <tunnelmode>`` or ``--tunnel-mode <tunnelmode>`` + + Specify the tunnel type. This option must match on server and + client. + +* ``-h`` or ``--help`` + + Prints a brief help message to the console. + +* ``-V`` or ``--version`` + + Prints version information to the console. + +Examples +======== + +On host 192.168.122.220 start ``ovs-l3ping`` in server mode. This command +will create a temporary GRE tunnel with the host 192.168.122.236 and assign +10.1.1.1/28 as the inner IP address, where client will have to connect:: + + ovs-l3ping -s 192.168.122.236,10.1.1.1/28 -t gre + +On host 192.168.122.236 start ``ovs-l3ping`` in client mode. This command +will use 10.1.1.2/28 as the local inner IP address and will connect over the +L3 tunnel to the server's inner IP address at 10.1.1.1:: + + ovs-l3ping -c 192.168.122.220,10.1.1.2/28,10.1.1.1 -t gre + +See Also +======== + +``ovs-vswitchd(8)``, ``ovs-ofctl(8)``, ``ovs-vsctl(8)``, +``ovs-vlan-test(8)``, ``ovs-test(8)``, ``ethtool(8)``, ``uname(1)``. diff --git a/Documentation/ref/ovs-parse-backtrace.8.rst b/Documentation/ref/ovs-parse-backtrace.8.rst new file mode 100644 index 000000000..27270c612 --- /dev/null +++ b/Documentation/ref/ovs-parse-backtrace.8.rst @@ -0,0 +1,34 @@ +=================== +ovs-parse-backtrace +=================== + +Synopsis +======== + +``ovs-appctl backtrace | ovs-parse-backtrace [<binary>]`` + +``ovs-parse-backtrace [<binary>] < <backtrace>`` + +Description +=========== + +In some configurations, many Open vSwitch daemons can produce a series of +backtraces using the ``ovs-appctl backtrace`` command. Users can analyze +these backtraces to figure out what the given Open vSwitch daemon may be +spending most of its time doing. ``ovs-parse-backtrace`` makes this output +easier to interpret. + +The ``ovs-appctl backtrace`` output must be supplied on standard input. The +binary that produced the output should be supplied as the sole non-option +argument. For best results, the binary should have debug symbols. + +Options +======= + +* ``--help`` + + Prints a usage message and exits. + +* ``--version`` + + Prints the version and exits. diff --git a/Documentation/ref/ovs-pki.8.rst b/Documentation/ref/ovs-pki.8.rst new file mode 100644 index 000000000..517d272fb --- /dev/null +++ b/Documentation/ref/ovs-pki.8.rst @@ -0,0 +1,251 @@ +======= +ovs-pki +======= + +Synopsis +======== + +Each command takes the form: + +``ovs-pki <options> <command> <args>...`` + +The implemented commands and their arguments are: + +* ``ovs-pki init`` + +* ``ovs-pki req <name>`` + +* ``ovs-pki sign <name> [<type>]`` + +* ``ovs-pki req+sign <name> [<type>]`` + +* ``ovs-pki verify <name> [<type>]`` + +* ``ovs-pki fingerprint <file>`` + +* ``ovs-pki self-sign <name>`` + +Each <type> above is a certificate type, either ``switch`` +(default) or ``controller``. + +The available options are: + +* ``-k <type>`` or ``--key=<type>`` + +* ``-B <nbits>`` or ``--bits=<nbits>`` + +* ``-D <file>`` or ``--dsaparam=<file>`` + +* ``-b`` or ``--batch`` + +* ``-f`` or ``--force`` + +* ``-d <dir>`` or ``--dir=<dir>`` + +* ``-l <file>`` or ``--log=<file>`` + +* ``-u`` or ``--unique`` + +* ``-h`` or ``--help`` + + +Description +=========== + +The ``ovs-pki`` program sets up and manages a public key +infrastructure for use with OpenFlow. It is intended to be a simple +interface for organizations that do not have an established public key +infrastructure. Other PKI tools can substitute for or supplement the +use of ``ovs-pki``. + +``ovs-pki`` uses ``openssl(1)`` for certificate management and key +generation. + +Offline Commands +================ + +The following ``ovs-pki`` commands support manual PKI administration: + +* ``init`` + + Initializes a new PKI (by default in ``/var/lib/openvswitch/pki``, + although this default may be changed at Open vSwitch build time) and + populates it with a pair of certificate authorities for controllers + and switches. + + This command should ideally be run on a high-security machine + separate from any OpenFlow controller or switch, called the CA + machine. The files ``pki/controllerca/cacert.pem`` and + ``pki/switchca/cacert.pem`` that it produces will need to be copied + over to the OpenFlow switches and controllers, respectively. Their + contents may safely be made public. + + By default, ``ovs-pki`` generates 2048-bit RSA keys. The ``-B`` or + ``--bits`` option (see below) may be used to override the key + length. The ``-k dsa`` or ``--key=dsa`` option may be used to use + DSA in place of RSA. If DSA is selected, the ``dsaparam.pem`` file + generated in the new PKI hierarchy must be copied to any machine on + which the ``req`` command (see below) will be executed. Its + contents may safely be made public. + + Other files generated by ``init`` may remain on the CA machine. The + files ``pki/controllerca/private/cakey.pem`` and + ``pki/switchca/private/cakey.pem`` have particularly sensitive + contents that should not be exposed. + +* ``req <name>`` + + Generates a new private key named ``<name>-privkey.pem`` and + corresponding certificate request named ``<name>-req.pem``. + The private key can be intended for use by a switch or a controller. + + This command should ideally be run on the switch or controller that + will use the private key to identify itself. The file + ``<name>-req.pem`` must be copied to the CA machine for signing + with the ``sign`` command (below). + + This command will output a fingerprint to stdout as its final step. + Write down the fingerprint and take it to the CA machine before + continuing with the ``sign`` step. + + When RSA keys are in use (as is the default), ``req``, unlike the + rest of the ``ovs-pki`` commands, does not need access to a PKI + hierarchy created by ``ovs-pki init``. The ``-B`` or + ``--bits`` option (see below) may be used to specify the number of + bits in the generated RSA key. + + When DSA keys are used (as specified with ``--key=dsa``), ``req`` + needs access to the ``dsaparam.pem`` file created as part of the PKI + hierarchy (but not to other files in that tree). By default, + ``ovs-pki`` looks for this file in the PKI directory as + ``dsaparam.pem``, but the ``-D`` or ``--dsaparam`` option (see + below) may be used to specify an alternate location. + + ``<name>-privkey.pem`` has sensitive contents that should not be + exposed. ``<name>-req.pem`` may be safely made public. + +* ``sign <name> [<type>]`` + + Signs the certificate request named ``<name>-req.pem`` that was + produced in the previous step, producing a certificate named + ``<name>-cert.pem``. <type>, either ``switch`` (default) or + ``controller``, indicates the use for which the key is being + certified. + + This command must be run on the CA machine. + + The command will output a fingerprint to stdout and request that you + verify that it is the same fingerprint output by the ``req`` + command. This ensures that the request being signed is the same one + produced by ``req``. (The ``-b`` or ``--batch`` option + suppresses the verification step.) + + The file ``<name>-cert.pem`` will need to be copied back to the + switch or controller for which it is intended. Its contents may + safely be made public. + +* ``req+sign <name> [<type>]`` + + Combines the ``req`` and ``sign`` commands into a single step, + outputting all the files produced by each. The + ``<name>-privkey.pem`` and ``<name>-cert.pem`` files must + be copied securely to the switch or controller. + ``<name>-privkey.pem`` has sensitive contents and must not be + exposed in transit. Afterward, it should be deleted from the CA + machine. + + This combined method is, theoretically, less secure than the + individual steps performed separately on two different machines, + because there is additional potential for exposure of the private + key. However, it is also more convenient. + +* ``verify <name> [<type>]`` + + Verifies that ``<name>-cert.pem`` is a valid certificate for the + given <type> of use, either ``switch`` (default) or ``controller``. + If the certificate is valid for this use, it prints the message + ``<name>-cert.pem: OK``; otherwise, it prints an error message. + +* ``fingerprint <file>`` + + Prints the fingerprint for <file>. If <file> is a + certificate, then this is the SHA-1 digest of the DER encoded version + of the certificate; otherwise, it is the SHA-1 digest of the entire + file. + +* ``self-sign <name>`` + + Signs the certificate request named ``<name>-req.pem`` using the + private key ``<name>-privkey.pem``, producing a self-signed + certificate named ``<name>-cert.pem``. The input files should have + been produced with ``ovs-pki req``. + + Some controllers accept such self-signed certificates. + +Options +======= + +* ``-k <type>`` or ``--key=<type>`` + + For the ``init`` command, sets the public key algorithm to use for + the new PKI hierarchy. For the ``req`` and ``req+sign`` commands, + sets the public key algorithm to use for the key to be generated, + which must match the value specified on ``init``. With other + commands, the value has no effect. + + The <type> may be ``rsa`` (the default) or ``dsa``. + +* ``-B <nbits>`` or ``--bits=<nbits>`` + + Sets the number of bits in the key to be generated. When RSA keys are + in use, this option affects only the ``init``, ``req``, and + ``req+sign`` commands, and the same value should be given each time. + With DSA keys are in use, this option affects only the ``init`` + command. + + The value must be at least 1024. The default is 2048. + +* ``-D <file>`` or ``--dsaparam=<file>`` + + Specifies an alternate location for the ``dsaparam.pem`` file + required by the ``req`` and ``req+sign`` commands. This option + affects only these commands, and only when DSA keys are used. + + The default is ``dsaparam.pem`` under the PKI hierarchy. + +* ``-b`` or ``--batch`` + + Suppresses the interactive verification of fingerprints that the + ``sign`` command by default requires. + +* ``-d <dir>`` or ``--dir=<dir>`` + + Specifies the location of the PKI hierarchy to be used or created by + the command. All commands, except ``req``, need access to a PKI + hierarchy. + + The default PKI hierarchy is ``/var/lib/openvswitch/pki``, although + this default may be changed at Open vSwitch build time + +* ``-f`` or ``--force`` + + By default, ``ovs-pki`` will not overwrite existing files or + directories. This option overrides this behavior. + +* ``-l <file>`` or ``--log=<file>`` + + Sets the log file to <file>. The default is ``ovs-pki.log`` in the + OVS log directory. The default OVS log directory is + ``/var/log/openvswitch``, although this default may be changed at + Open vSwitch build time. + +* ``-u`` or ``--unique`` + + Changes the format of the certificate's Common Name (CN) field. By + default, this field has the format ``<name> id:<uuid-or-date>``. This + option causes the provided name to be treated as unique and changes + the format of the CN field to be simply ``<name>``. + +* ``-h`` or ``--help`` + + Prints a help usage message and exits. diff --git a/Documentation/ref/ovs-tcpdump.8.rst b/Documentation/ref/ovs-tcpdump.8.rst new file mode 100644 index 000000000..048b70f23 --- /dev/null +++ b/Documentation/ref/ovs-tcpdump.8.rst @@ -0,0 +1,68 @@ +=========== +ovs-tcpdump +=========== + +Synopsis +======== + +``ovs-tcpdump -i <port> tcpdump <options>...`` + +Description +=========== + +``ovs-tcpdump`` creates switch mirror ports in the ``ovs-vswitchd`` +daemon and executes ``tcpdump`` to listen against those ports. When +the ``tcpdump`` instance exits, it then cleans up the mirror port it +created. + +``ovs-tcpdump`` will not allow multiple mirrors for the same port. It +has some logic to parse the current configuration and prevent +duplicate mirrors. + +The ``-i`` option may not appear multiple times. + +It is important to note that under Linux-based kernels, tap devices do +not receive packets unless the specific tuntap device has been opened by an +application. This requires ``CAP_NET_ADMIN`` privileges, so the +``ovs-tcpdump`` command must be run as a user with such permissions (this +is usually a super-user). + +Options +======= + +* ``-h`` or ``--help`` + + Prints a brief help message to the console. + +* ``-V`` or ``--version`` + + Prints version information to the console. + +* ``--db-sock <socket>`` + + The Open vSwitch database socket connection string. The default is + ``unix:<rundir>/db.sock``. + +* ``--dump-cmd <command>`` + + The command to run instead of ``tcpdump``. + +* ``-i`` or ``--interface`` + + The interface for which a mirror port should be created, and packets + should be dumped. + +* ``--mirror-to`` + + The name of the interface which should be the destination of the mirrored + packets. The default is ``mi<port>``. + +* ``--span`` + + If specified, mirror all ports (optional). + +See Also +======== + +``ovs-appctl(8)``, ``ovs-vswitchd(8)``, ``ovs-pcap(1)``, +``ovs-tcpundump(1)``, ``tcpdump(8)``, ``wireshark(8)``. diff --git a/Documentation/ref/ovs-tcpundump.1.rst b/Documentation/ref/ovs-tcpundump.1.rst new file mode 100644 index 000000000..27710226f --- /dev/null +++ b/Documentation/ref/ovs-tcpundump.1.rst @@ -0,0 +1,39 @@ +============= +ovs-tcpundump +============= + +Synopsis +======== + +``ovs-tcpundump < <file>`` + +``ovs-tcpundump -h | --help`` + +``ovs-tcpundump -V | --version`` + +The ``ovs-tcpundump`` program reads ``tcpdump -xx output`` from stdin, +looking for hexadecimal packet data, and dumps each Ethernet as a +single hexadecimal string on stdout. This format is suitable for use +with the ``ofproto/trace`` command supported by ``ovs-vswitchd(8)`` +via ``ovs-appctl(8)``. + +At least two ``-x`` or ``-X`` options must be given, otherwise the +output will omit the Ethernet header, which prevents the output from +being used with ``ofproto/trace``. + +Options +======= + +* ``-h`` or ``--help`` + + Prints a brief help message to the console. + +* ``-V`` or ``--version`` + + Prints version information to the console. + +See Also +======== + +``ovs-appctl(8)``, ``ovs-vswitchd(8)``, ``ovs-pcap(1)``, +``tcpdump(8)``, ``wireshark(8)``. diff --git a/manpages.mk b/manpages.mk index 281ebd8fe..dc201484c 100644 --- a/manpages.mk +++ b/manpages.mk @@ -1,23 +1,5 @@ # Generated automatically -- do not modify! -*- buffer-read-only: t -*- -ovn/utilities/ovn-sbctl.8: \ - ovn/utilities/ovn-sbctl.8.in \ - lib/common.man \ - lib/db-ctl-base.man \ - lib/ovs.tmac \ - lib/ssl-bootstrap.man \ - lib/ssl.man \ - lib/table.man \ - lib/vlog.man -ovn/utilities/ovn-sbctl.8.in: -lib/common.man: -lib/db-ctl-base.man: -lib/ovs.tmac: -lib/ssl-bootstrap.man: -lib/ssl.man: -lib/table.man: -lib/vlog.man: - ovsdb/ovsdb-client.1: \ ovsdb/ovsdb-client.1.in \ lib/common-syn.man \ @@ -116,14 +98,13 @@ lib/vlog-syn.man: lib/vlog.man: ovsdb/ovsdb-schemas.man: -utilities/ovs-appctl.8: \ - utilities/ovs-appctl.8.in \ - lib/common.man \ +utilities/bugtool/ovs-bugtool.8: \ + utilities/bugtool/ovs-bugtool.8.in \ lib/ovs.tmac -utilities/ovs-appctl.8.in: -lib/common.man: +utilities/bugtool/ovs-bugtool.8.in: lib/ovs.tmac: + utilities/ovs-dpctl-top.8: \ utilities/ovs-dpctl-top.8.in \ lib/ovs.tmac @@ -142,16 +123,6 @@ lib/dpctl.man: lib/ovs.tmac: lib/vlog.man: -utilities/ovs-l3ping.8: \ - utilities/ovs-l3ping.8.in \ - lib/common-syn.man \ - lib/common.man \ - lib/ovs.tmac -utilities/ovs-l3ping.8.in: -lib/common-syn.man: -lib/common.man: -lib/ovs.tmac: - utilities/ovs-ofctl.8: \ utilities/ovs-ofctl.8.in \ lib/colors.man \ @@ -184,28 +155,6 @@ lib/common-syn.man: lib/common.man: lib/ovs.tmac: -utilities/ovs-pki.8: \ - utilities/ovs-pki.8.in \ - lib/ovs.tmac -utilities/ovs-pki.8.in: -lib/ovs.tmac: - -utilities/ovs-tcpdump.8: \ - utilities/ovs-tcpdump.8.in \ - lib/common.man \ - lib/ovs.tmac -utilities/ovs-tcpdump.8.in: -lib/common.man: -lib/ovs.tmac: - -utilities/ovs-tcpundump.1: \ - utilities/ovs-tcpundump.1.in \ - lib/common-syn.man \ - lib/common.man \ - lib/ovs.tmac -utilities/ovs-tcpundump.1.in: -lib/common-syn.man: -lib/common.man: lib/ovs.tmac: utilities/ovs-testcontroller.8: \ diff --git a/utilities/automake.mk b/utilities/automake.mk index 37a59cfea..e2e22c39a 100644 --- a/utilities/automake.mk +++ b/utilities/automake.mk @@ -63,22 +63,14 @@ EXTRA_DIST += \ utilities/docker/debian/Dockerfile \ utilities/docker/debian/build-kernel-modules.sh MAN_ROOTS += \ - utilities/ovs-appctl.8.in \ utilities/ovs-testcontroller.8.in \ - utilities/ovs-ctl.8 \ utilities/ovs-dpctl.8.in \ utilities/ovs-dpctl-top.8.in \ utilities/ovs-kmod-ctl.8 \ - utilities/ovs-l3ping.8.in \ utilities/ovs-ofctl.8.in \ - utilities/ovs-parse-backtrace.8 \ utilities/ovs-pcap.1.in \ - utilities/ovs-pki.8.in \ - utilities/ovs-tcpdump.8.in \ - utilities/ovs-tcpundump.1.in \ utilities/ovs-vsctl.8.in CLEANFILES += \ - utilities/ovs-appctl.8 \ utilities/ovs-ctl \ utilities/ovs-check-dead-ifs \ utilities/ovs-testcontroller.8 \ @@ -87,37 +79,26 @@ CLEANFILES += \ utilities/ovs-dpctl-top.8 \ utilities/ovs-kmod-ctl \ utilities/ovs-l3ping \ - utilities/ovs-l3ping.8 \ utilities/ovs-lib \ utilities/ovs-ofctl.8 \ utilities/ovs-parse-backtrace \ utilities/ovs-pcap \ utilities/ovs-pcap.1 \ utilities/ovs-pki \ - utilities/ovs-pki.8 \ utilities/ovs-sim \ utilities/ovs-tcpdump \ - utilities/ovs-tcpdump.8 \ utilities/ovs-tcpundump \ - utilities/ovs-tcpundump.1 \ utilities/ovs-test \ utilities/ovs-vlan-test \ utilities/ovs-vsctl.8 man_MANS += \ - utilities/ovs-appctl.8 \ - utilities/ovs-ctl.8 \ utilities/ovs-testcontroller.8 \ utilities/ovs-dpctl.8 \ utilities/ovs-dpctl-top.8 \ utilities/ovs-kmod-ctl.8 \ - utilities/ovs-l3ping.8 \ utilities/ovs-ofctl.8 \ - utilities/ovs-parse-backtrace.8 \ utilities/ovs-pcap.1 \ - utilities/ovs-pki.8 \ - utilities/ovs-tcpdump.8 \ - utilities/ovs-tcpundump.1 \ utilities/ovs-vsctl.8 utilities_ovs_appctl_SOURCES = utilities/ovs-appctl.c diff --git a/utilities/ovs-appctl.8.in b/utilities/ovs-appctl.8.in deleted file mode 100644 index 9c3bd12e4..000000000 --- a/utilities/ovs-appctl.8.in +++ /dev/null @@ -1,293 +0,0 @@ -.\" -*- nroff -*- -.so lib/ovs.tmac -.TH ovs\-appctl 8 "@VERSION@" "Open vSwitch" "Open vSwitch Manual" -.ds PN ovs\-appctl -. -.SH NAME -ovs\-appctl \- utility for configuring running Open vSwitch daemons -. -.SH SYNOPSIS -\fBovs\-appctl\fR [\fB\-\-target=\fItarget\fR | \fB\-t\fR \fItarget\fR] -[\fB\-T \fIsecs\fR | \fB\-\-timeout=\fIsecs\fR] -\fIcommand \fR[\fIarg\fR...] -.br -\fBovs\-appctl \fB\-\-help\fR -.br -\fBovs\-appctl \fB\-\-version\fR -.SH DESCRIPTION -Open vSwitch daemons accept certain commands at runtime to control their -behavior and query their settings. Every daemon accepts a common set of -commands documented under \fBCOMMON COMMANDS\fR below. Some daemons -support additional commands documented in their own manpages. -\fBovs\-vswitchd\fR in particular accepts a number of additional -commands documented in \fBovs\-vswitchd\fR(8). -.PP -The \fBovs\-appctl\fR program provides a simple way to invoke these -commands. The command to be sent is specified on \fBovs\-appctl\fR's -command line as non-option arguments. \fBovs\-appctl\fR sends the -command and prints the daemon's response on standard output. -.PP -In normal use only a single option is accepted: -.IP "\fB\-t \fItarget\fR" -.IQ "\fB\-\-target=\fItarget\fR" -Tells \fBovs\-appctl\fR which daemon to contact. -.IP -If \fItarget\fR begins with \fB/\fR it must name a Unix domain socket -on which an Open vSwitch daemon is listening for control channel -connections. By default, each daemon listens on a Unix domain socket -named \fB@RUNDIR@/\fIprogram\fB.\fIpid\fB.ctl\fR, where \fIprogram\fR -is the program's name and \fIpid\fR is its process ID. For example, -if \fBovs\-vswitchd\fR has PID 123, it would listen on -\fB@RUNDIR@/ovs\-vswitchd.123.ctl\fR. -.IP -Otherwise, \fBovs\-appctl\fR looks for a pidfile, that is, a file -whose contents are the process ID of a running process as a decimal -number, named \fB@RUNDIR@/\fItarget\fB.pid\fR. (The \fB\-\-pidfile\fR -option makes an Open vSwitch daemon create a pidfile.) -\fBovs\-appctl\fR reads the pidfile, then looks for a Unix socket -named \fB@RUNDIR@/\fItarget\fB.\fIpid\fB.ctl\fR, where \fIpid\fR is -replaced by the process ID read from the pidfile, and uses that file -as if it had been specified directly as the target. -.IP -On Windows, \fItarget\fR can be an absolute path to a file that contains -a localhost TCP port on which an Open vSwitch daemon is listening -for control channel connections. By default, each daemon writes the -TCP port on which it is listening for control connection into the file -\fIprogram\fB.ctl\fR located inside the configured \fIOVS_RUNDIR\fR -directory. If \fItarget\fR is not an absolute path, \fBovs\-appctl\fR -looks for a file named \fItarget\fB.ctl\fR in the configured \fIOVS_RUNDIR\fR -directory. -.IP -The default target is \fBovs\-vswitchd\fR. -. -.IP "\fB\-T \fIsecs\fR" -.IQ "\fB\-\-timeout=\fIsecs\fR" -By default, or with a \fIsecs\fR of \fB0\fR, \fBovs\-appctl\fR waits -forever to connect to the daemon and receive a response. This option -limits runtime to approximately \fIsecs\fR seconds. If the timeout -expires, \fBovs\-appctl\fR exits with a \fBSIGALRM\fR signal. -. -.SH COMMON COMMANDS -Every Open vSwitch daemon supports a common set of commands, which are -documented in this section. -. -.SS GENERAL COMMANDS -These commands display daemon-specific commands and the running version. -Note that these commands are different from the \fB\-\-help\fR and -\fB\-\-version\fR options that return information about the -\fBovs\-appctl\fR utility itself. -. -.IP "\fBlist-commands\fR" -Lists the commands supported by the target. -. -.IP "\fBversion\fR" -Displays the version and compilation date of the target. -. -.SS LOGGING COMMANDS -Open vSwitch has several log levels. The highest-severity log level is: -. -.IP "\fBoff\fR" -No message is ever logged at this level, so setting a logging -destination's log level to \fBoff\fR disables logging to that destination. -. -.PP -The following log levels, in order of descending severity, are -available: -. -.IP "\fBemer\fR" -A major failure forced a process to abort. -.IP "\fBerr\fR" -A high-level operation or a subsystem failed. Attention is -warranted. -.IP "\fBwarn\fR" -A low-level operation failed, but higher-level subsystems may be able -to recover. -.IP "\fBinfo\fR" -Information that may be useful in retrospect when investigating -a problem. -.IP "\fBdbg\fR" -Information useful only to someone with intricate knowledge of the -system, or that would commonly cause too-voluminous log output. Log -messages at this level are not logged by default. -. -.PP -Every Open vSwitch daemon supports the following commands for examining -and adjusting log levels. -.IP "\fBvlog/list\fR" -Lists the known logging modules and their current levels. -. -.IP "\fBvlog/list-pattern\fR" -Lists logging pattern used for each destination. -. -.IP "\fBvlog/set\fR [\fIspec\fR]" -Sets logging levels. Without any \fIspec\fR, sets the log level for -every module and destination to \fBdbg\fR. Otherwise, \fIspec\fR is a -list of words separated by spaces or commas or colons, up to one from -each category below: -. -.RS -.IP \(bu -A valid module name, as displayed by the \fBvlog/list\fR command on -\fBovs\-appctl\fR(8), limits the log level change to the specified -module. -. -.IP \(bu -\fBsyslog\fR, \fBconsole\fR, or \fBfile\fR, to limit the log level -change to only to the system log, to the console, or to a file, -respectively. -.IP -On Windows platform, \fBsyslog\fR is accepted as a word and -is only useful if the \fItarget\fR was started with the -\fB\-\-syslog\-target\fR option (the word has no effect otherwise). -. -.IP \(bu -\fBoff\fR, \fBemer\fR, \fBerr\fR, \fBwarn\fR, \fBinfo\fR, or -\fBdbg\fR, to control the log level. Messages of the given severity -or higher will be logged, and messages of lower severity will be -filtered out. \fBoff\fR filters out all messages. -.RE -. -.IP -Case is not significant within \fIspec\fR. -.IP -Regardless of the log levels set for \fBfile\fR, logging to a file -will not take place unless the target application was invoked with the -\fB\-\-log\-file\fR option. -.IP -For compatibility with older versions of OVS, \fBany\fR is accepted as -a word but has no effect. -. -.IP "\fBvlog/set PATTERN:\fIdestination\fB:\fIpattern\fR" -Sets the log pattern for \fIdestination\fR to \fIpattern\fR. Each time a -message is logged to \fIdestination\fR, \fIpattern\fR determines the -message's formatting. Most characters in \fIpattern\fR are copied -literally to the log, but special escapes beginning with \fB%\fR are -expanded as follows: -. -.RS -.IP \fB%A\fR -The name of the application logging the message, e.g. \fBovs\-vswitchd\fR. -. -.IP \fB%B\fR -The RFC5424 syslog PRI of the message. -. -.IP \fB%c\fR -The name of the module (as shown by \fBovs\-appctl \-\-list\fR) logging -the message. -. -.IP \fB%d\fR -The current date and time in ISO 8601 format (YYYY\-MM\-DD HH:MM:SS). -. -.IP \fB%d{\fIformat\fB}\fR -The current date and time in the specified \fIformat\fR, which takes -the same format as the \fItemplate\fR argument to \fBstrftime\fR(3). -As an extension, any \fB#\fR characters in \fIformat\fR will be -replaced by fractional seconds, e.g. use \fB%H:%M:%S.###\fR for the -time to the nearest millisecond. Sub-second times are only -approximate and currently decimal places after the third will always -be reported as zero. -. -.IP \fB%D\fR -The current UTC date and time in ISO 8601 format (YYYY\-MM\-DD HH:MM:SS). -. -.IP \fB%D{\fIformat\fB}\fR -The current UTC date and time in the specified \fIformat\fR, which -takes the same format as the \fItemplate\fR argument to -\fBstrftime\fR(3). Supports the same extension for sub-second -resolution as \fB%d{\fR...\fB}\fR. -. -.IP \fB%E\fR -The hostname of the node running the application. -. -.IP \fB%m\fR -The message being logged. -. -.IP \fB%N\fR -A serial number for this message within this run of the program, as a -decimal number. The first message a program logs has serial number 1, -the second one has serial number 2, and so on. -. -.IP \fB%n\fR -A new-line. -. -.IP \fB%p\fR -The level at which the message is logged, e.g. \fBDBG\fR. -. -.IP \fB%P\fR -The program's process ID (pid), as a decimal number. -. -.IP \fB%r\fR -The number of milliseconds elapsed from the start of the application -to the time the message was logged. -. -.IP \fB%t\fR -The subprogram name, that is, an identifying name for the process or -thread that emitted the log message, such as \fBmonitor\fR for the -process used for \fB\-\-monitor\fR or \fBmain\fR for the primary -process or thread in a program. -. -.IP \fB%T\fR -The subprogram name enclosed in parentheses, e.g. \fB(monitor)\fR, or -the empty string for the primary process or thread in a program. -. -.IP \fB%%\fR -A literal \fB%\fR. -.RE -. -.IP -A few options may appear between the \fB%\fR and the format specifier -character, in this order: -. -.RS -.IP \fB\-\fR -Left justify the escape's expansion within its field width. Right -justification is the default. -. -.IP \fB0\fR -Pad the field to the field width with \fB0\fRs. Padding with spaces -is the default. -. -.IP \fIwidth\fR -A number specifies the minimum field width. If the escape expands to -fewer characters than \fIwidth\fR then it is padded to fill the field -width. (A field wider than \fIwidth\fR is not truncated to fit.) -.RE -. -.IP -The default pattern for console and file output is \fB%D{%Y-%m-%dT -%H:%M:%SZ}|%05N|%c|%p|%m\fR; for syslog output, \fB%05N|%c|%p|%m\fR. -. -.IP -Daemons written in Python (e.g. \fBovs\-xapi\-sync\fR) do not allow -control over the log pattern. -. -.IP "\fBvlog/set\fR FACILITY:\fIfacility\fR" -Sets the RFC5424 facility of the log message. \fIfacility\fR can be one of -\fBkern\fR, \fBuser\fR, \fBmail\fR, \fBdaemon\fR, \fBauth\fR, \fBsyslog\fR, -\fBlpr\fR, \fBnews\fR, \fBuucp\fR, \fBclock\fR, \fBftp\fR, \fBntp\fR, -\fBaudit\fR, \fBalert\fR, \fBclock2\fR, \fBlocal0\fR, \fBlocal1\fR, -\fBlocal2\fR, \fBlocal3\fR, \fBlocal4\fR, \fBlocal5\fR, \fBlocal6\fR or -\fBlocal7\fR. -. -.IP "\fBvlog/close\fR" -Causes the daemon to close its log file, if it is open. (Use -\fBvlog/reopen\fR to reopen it later.) -. -.IP "\fBvlog/reopen\fR" -Causes the daemon 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.) -.IP -This has no effect if the target application was not invoked with the -\fB\-\-log\-file\fR option. -. -.SH OPTIONS -. -.so lib/common.man -. -.SH "SEE ALSO" -. -\fBovs\-appctl\fR can control all Open vSwitch daemons, including: -.BR ovs\-vswitchd (8), -and -.BR ovsdb\-server (8). diff --git a/utilities/ovs-ctl.8 b/utilities/ovs-ctl.8 deleted file mode 100644 index e25223c78..000000000 --- a/utilities/ovs-ctl.8 +++ /dev/null @@ -1,518 +0,0 @@ -.\" -*- nroff -*- -.de IQ -. br -. ns -. IP "\\$1" -.. -.de ST -. PP -. RS -0.15in -. I "\\$1" -. RE -.. -.TH ovs\-ctl 8 "June 2011" "Open vSwitch" "Open vSwitch Manual" -.ds PN ovs\-ctl -. -.SH NAME -ovs\-ctl \- OVS startup helper script -. -.SH SYNOPSIS -\fBovs\-ctl\fR \fB\-\-system\-id=random\fR|\fIuuid\fR -[\fIoptions\fR] \fBstart -.br -\fBovs\-ctl stop -.br -\fBovs\-ctl\fR \fB\-\-system\-id=random\fR|\fIuuid\fR -[\fIoptions\fR] \fBrestart -.br -\fBovs\-ctl status -.br -\fBovs\-ctl version -.br -\fBovs\-ctl -[\fIoptions\fR] -\fBload\-kmod\fR -.br -\fBovs\-ctl -\fB\-\-system\-id=random\fR|\fIuuid\fR -[\fIoptions\fR] -\fBforce\-reload\-kmod\fR -.br -\fBovs\-ctl -\fR[\fB\-\-protocol=\fIprotocol\fR] -[\fB\-\-sport=\fIsport\fR] -[\fB\-\-dport=\fIdport\fR] -\fBenable\-protocol\fR -.br -\fBovs\-ctl delete\-transient\-ports -.br -\fBovs\-ctl help \fR| \fB\-h \fR| \fB\-\-help -.br -\fBovs\-ctl \-\-version -. -.SH DESCRIPTION -. -.PP -The \fBovs\-ctl\fR program starts, stops, and checks the status of -Open vSwitch daemons. It is not meant to be invoked directly by -system administrators but to be called internally by system startup -scripts. -. -.PP -Each of \fBovs\-ctl\fR's commands is described separately below. -. -.SH "The ``start'' command" -. -.PP -The \fBstart\fR command starts Open vSwitch. It performs the -following tasks: -. -.IP 1. -Loads the Open vSwitch kernel module. If this fails, and the Linux -bridge module is loaded but no bridges exist, it tries to unload the -bridge module and tries loading the Open vSwitch kernel module again. -(This is because the Open vSwitch kernel module cannot coexist with -the Linux bridge module before 2.6.37.) -. -.PP -The \fBstart\fR command skips the following steps if -\fBovsdb\-server\fR is already running: -.IP 2. -If the Open vSwitch database file does not exist, it creates it. -If the database does exist, but it has an obsolete version, it -upgrades it to the latest schema. -. -.IP 3. -Starts \fBovsdb-server\fR, unless the \fB\-\-no\-ovsdb\-server\fR command -option is given. -. -.IP 4. -Initializes a few values inside the database. -. -.IP 5. -If the \fB\-\-delete\-bridges\fR option was used, deletes all of the -bridges from the database. -. -.IP 6. -If the \fB\-\-delete\-transient\-ports\fR option was used, deletes all ports -that have \fBother_config:transient\fR set to true. -. -.PP -The \fBstart\fR command skips the following step if -\fBovs\-vswitchd\fR is already running, or if the \fB\-\-no\-ovs\-vswitchd\fR -command option is given: -.IP 7. -Starts \fBovs\-vswitchd\fR. -. -.SS "Options" -.PP -Several command-line options influence the \fBstart\fR command's -behavior. Some form of the following option should ordinarily be -specified: -. -.IP "\fB\-\-system\-id=\fIuuid\fR" -.IQ "\fB\-\-system\-id=random\fR" -This specifies a unique system identifier to store into -\fBexternal-ids:system-id\fR in the database's \fBOpen_vSwitch\fR -table. Remote managers that talk to the Open vSwitch database server -over network protocols use this value to identify and distinguish Open -vSwitch instances, so it should be unique (at least) within OVS -instances that will connect to a single controller. -.IP -When \fBrandom\fR is specified, \fBovs\-ctl\fR will generate a random -ID that persists from one run to another (stored in a file). When -another string is specified \fBovs\-ctl\fR uses it literally. -. -.PP -The following options should be specified if the defaults are not -suitable: -. -.IP "\fB\-\-system\-type=\fItype\fR" -.IQ "\fB\-\-system\-version=\fIversion\fR" -Sets the value to store in the \fBsystem-type\fR and -\fBsystem-version\fR columns, respectively, in the database's -\fBOpen_vSwitch\fR table. Remote managers may use these values to -determine the kind of system to which they are connected (primarily -for display to human administrators). -.IP -When not specified, \fBovs\-ctl\fR uses values from the optional -\fBsystem\-type.conf\fR and \fBsystem\-version.conf\fR files(see section -\fBFILES\fR) or it uses the \fBlsb_release\fR program, if present, to -provide reasonable defaults. -. -.PP -The following options are also likely to be useful: -. -.IP "\fB\-\-external\-id=\(dq\fIname\fB=\fIvalue\fB\(dq" -Sets \fBexternal-ids:\fIname\fR to \fIvalue\fR in the database's -\fBOpen_vSwitch\fR table. Specifying this option multiple times adds -multiple key-value pairs. -. -.IP "\fB\-\-delete\-bridges\fR" -Ordinarily Open vSwitch bridges persist from one system boot to the -next, as long as the database is preserved. Some environments instead -expect to re-create all of the bridges and other configuration state -on every boot. This option supports that, by deleting all Open -vSwitch bridges after starting \fBovsdb\-server\fR but before starting -\fBovs\-vswitchd\fR. -. -.IP "\fB\-\-delete\-transient\-ports\fR" -Deletes all ports that have the other_config:transient value set to true. This -is important on certain environments where some ports are going to be recreated -after reboot, but other ports need to be persisted in the database. -. -.IP "\fB\-\-ovs\-user=user[:group]\fR" -Ordinarily Open vSwitch daemons are started as the user invoking the ovs-ctl -command. Some system administrators would prefer to have the various daemons -spawn as different users in their environments. This option allows passing the -\fB\-\-user\fR option to the \fBovsdb\-server\fR and \fBovs\-vswitchd\fR -daemons, allowing them to change their privilege levels. -. -.PP -The following options are less important: -. -.IP "\fB\-\-no\-monitor\fR" -By default \fBovs\-ctl\fR passes \fB\-\-monitor\fR to \fBovs\-vswitchd\fR and -\fBovsdb\-server\fR, requesting that it spawn a process monitor which will -restart the daemon if it crashes. This option suppresses that behavior. -. -.IP "\fB\-\-daemon-cwd=\fIdirectory\fR" -Specifies the current working directory that the OVS daemons should -run from. The default is \fB/\fR (the root directory) if this option -is not specified. (This option is useful because most systems create -core files in a process's current working directory and because a file -system that is in use as a process's current working directory cannot -be unmounted.) -. -.IP "\fB\-\-no\-force\-corefiles\fR" -By default, \fBovs\-ctl\fR enables core dumps for the OVS daemons. -This option disables that behavior. -. -.IP "\fB\-\-no\-mlockall\fR" -By default \fBovs\-ctl\fR passes \fB\-\-mlockall\fR to -\fBovs\-vswitchd\fR, requesting that it lock all of its virtual -memory, preventing it from being paged to disk. This option -suppresses that behavior. -. -.IP "\fB\-\-no\-self\-confinement\fR" -Disable self-confinement for \fBovs-vswitchd\fR and \fBovsdb\-server\fR -daemons. This flag may be used when, for example, OpenFlow controller -creates its Unix Domain Socket outside OVS run directory and OVS needs -to connect to it. It is better to stick with the default behavior and -not to use this flag, unless: -. -.RS -.IP \(bu -You have Open vSwitch running under SELinux or AppArmor Mandatory -Access Control that would prevent OVS from messing with sockets -outside ordinary OVS directories. -. -.IP \(bu -You believe that relying on protocol handshakes (e.g. OpenFlow) -is enough to prevent OVS to adversely interact with other daemons -running on your system. -. -.IP \(bu -You don't have much worries of remote OVSDB exploits in the first -place, because, perhaps, OVSDB manager is running on the same host -as OVS and share similar attack vectors. -.RE -. -.IP "\fB\-\-ovsdb\-server\-priority=\fIniceness\fR" -.IQ "\fB\-\-ovs\-vswitchd\-priority=\fIniceness\fR" -Sets the \fBnice\fR(1) level used for each daemon. All of them -default to \fB\-10\fR. -. -.IP "\fB\-\-ovsdb\-server\-wrapper=\fIwrapper\fR" -.IQ "\fB\-\-ovs\-vswitchd\-wrapper=\fIwrapper\fR" -. -Configures the specified daemon to run under \fIwrapper\fR, which is -one of the following: -. -.RS -.IP "\fBvalgrind\fR" -Run the daemon under \fBvalgrind\fR(1), if it is installed, logging to -\fIdaemon\fB.valgrind.log.\fIpid\fR in the log directory. -. -.IP "\fBstrace\fR" -Run the daemon under \fBstrace\fR(1), if it is installed, logging to -\fIdaemon\fB.strace.log.\fIpid\fR in the log directory. -. -.IP "\fBglibc\fR" -Enable GNU C library features designed to find memory errors. -.RE -. -.IP -By default, no wrapper is used. -. -.IP -Each of the wrappers can expose bugs in Open vSwitch that lead to -incorrect operation, including crashes. The \fBvalgrind\fR and -\fBstrace\fR wrappers greatly slow daemon operations so they should -not be used in production. They also produce voluminous logs that can -quickly fill small disk partitions. The \fBglibc\fR wrapper is less -resource-intensive but still somewhat slows the daemons. -. -.PP -The following options control file locations. They should only be -used if the default locations cannot be used. See \fBFILES\fR, below, -for more information. -. -.IP "\fB\-\-db\-file=\fIfile\fR" -Overrides the file name for the OVS database. -. -.IP "\fB\-\-db\-sock=\fIsocket\fR" -Overrides the file name for the Unix domain socket used to connect to -\fBovsdb\-server\fR. -. -.IP "\fB\-\-db\-schema=\fIschema\fR" -Overrides the file name for the OVS database schema. -. -.IP "\fB\-\-extra-dbs=\fIfile\fR" -Adds \fIfile\fR as an extra database for \fBovsdb\-server\fR to serve -out. Multiple space-separated file names may also be specified. -\fIfile\fR should begin with \fB/\fR; if it does not, then it will be -taken as relative to \fIdbdir\fR. -. -.SH "The ``stop'' command" -. -.PP -The \fBstop\fR command does not unload the Open vSwitch kernel -modules. It can take the same \fB\-\-no\-ovsdb\-server\fR and -\fB\-\-no\-ovs\-vswitchd\fR options as that of the \fBstart\fR -command. -. -.PP -This command does nothing and finishes successfully if the OVS daemons -aren't running. -. -.SH "The ``restart'' command" -. -.PP -The \fBrestart\fR command performs a \fBstop\fR followed by a \fBstart\fR -command. The command can take the same options as that of the \fBstart\fR -command. In addition, it saves and restores OpenFlow flows for each -individual bridge. -. -.SH "The ``status'' command" -. -.PP -The \fBstatus\fR command checks whether the OVS daemons -\fBovs-vswitchd\fR and \fBovsdb\-server\fR are running and prints -messages with that information. It exits with status 0 if -the daemons are running, 1 otherwise. -. -.SH "The ``version'' command" -. -.PP -The \fBversion\fR command runs \fBovsdb\-server \-\-version\fR and -\fBovs\-vswitchd \-\-version\fR. -. -.SH "The ``force\-reload\-kmod'' command" -. -.PP -The \fBforce\-reload\-kmod\fR command allows upgrading the Open -vSwitch kernel module without rebooting. It performs the following -tasks: -. -.IP 1. -Gets a list of OVS ``internal'' interfaces, that is, network devices -implemented by Open vSwitch. The most common examples of these are -bridge ``local ports''. -. -.IP 2. -Saves the OpenFlow flows of each bridge. -. -.IP 3. -Stops the Open vSwitch daemons, as if by a call to \fBovs\-ctl -stop\fR. -. -.IP 4. -Saves the kernel configuration state of the OVS internal interfaces -listed in step 1, including IP and IPv6 addresses and routing table -entries. -. -.IP 5. -Unloads the Open vSwitch kernel module (including the bridge -compatibility module if it is loaded). -. -.IP 6. -Starts OVS back up, as if by a call to \fBovs\-ctl start\fR. This -reloads the kernel module, restarts the OVS daemons and finally -restores the saved OpenFlow flows. -. -.IP 7. -Restores the kernel configuration state that was saved in step 4. -. -.IP 8. -Checks for daemons that may need to be restarted because they have -packet sockets that are listening on old instances of Open vSwitch -kernel interfaces and, if it finds any, prints a warning on stdout. -DHCP is a common example: if the ISC DHCP client is running on an OVS -internal interface, then it will have to be restarted after completing -the above procedure. (It would be nice if \fBovs\-ctl\fR could restart -daemons automatically, but the details are far too specific to a -particular distribution and installation.) -. -.PP -\fBforce\-kmod\-reload\fR internally stops and starts OVS, so it -accepts all of the options accepted by the \fBstart\fR command except -for the \fB\-\-no\-ovs\-vswitchd\fR option. -. -.SH "The ``load\-kmod'' command" -. -.PP -The \fBload\-kmod\fR command loads the openvswitch kernel modules if -they are not already loaded. This operation also occurs as part of -the \fBstart\fR command. The motivation for providing the \fBload\-kmod\fR -command is to allow errors when loading modules to be handled separatetly -from other errors that may occur when running the \fBstart\fR command. -. -.PP -By default the \fBload\-kmod\fR command attempts to load the -openvswitch kernel module. -. -.SH "The ``enable\-protocol'' command" -. -.PP -The \fBenable\-protocol\fR command checks for rules related to a -specified protocol in the system's \fBiptables\fR(8) configuration. If there -are no rules specifically related to that protocol, then it inserts a -rule to accept the specified protocol. -. -.PP -More specifically: -. -.IP \(bu -If \fBiptables\fR is not installed or not enabled, this command does -nothing, assuming that lack of filtering means that the protocol is -enabled. -. -.IP \(bu -If the \fBINPUT\fR chain has a rule that matches the specified -protocol, then this command does nothing, assuming that whatever rule -is installed reflects the system administrator's decisions. -. -.IP \(bu -Otherwise, this command installs a rule that accepts traffic of the -specified protocol. -. -.PP -This command normally completes successfully, even if it does -nothing. Only the failure of an attempt to insert a rule normally -causes it to return an exit code other than 0. -. -The following options control the protocol to be enabled: -. -.IP "\fB\-\-protocol=\fIprotocol\fR" -The name of the IP protocol to be enabled, such as \fBgre\fR or -\fBtcp\fR. The default is \fBgre\fR. -. -.IP "\fB\-\-sport=\fIsport\fR" -.IQ "\fB\-\-dport=\fIdport\fR" -TCP or UDP source or destination port to match. These are optional -and allowed only with \fB\-\-protocol=tcp\fR or -\fB\-\-protocol=udp\fR. -. -.SH "The ``delete\-transient\-ports'' command" -. -Deletes all ports that have the \fBother_config:transient\fR value set to true. -. -.SH "The ``help'' command" -. -Prints a usage message and exits successfully. -. -.SH "OPTIONS" -.PP -In addition to the options listed for each command above, these options -control the behavior of several of \fBovs\-ctl\fR's commands. -. -.PP -By default, \fBovs\-ctl\fR will control the \fBovsdb\-server\fR, and -the \fBovs\-vswitchd\fR daemons. The following options restrict that control -to exclude one or the other: -. -.IP "\fB\-\-no\-ovsdb-server\fR" -Specifies that the \fBovs\-ctl\fR commands \fBstart\fR, \fBstop\fR, and -\fBrestart\fR should not modify the running status of \fBovsdb\-server\fR. -. -.IP "\fB\-\-no\-ovs\-vswitchd\fR" -Specifies that the \fBovs\-ctl\fR commands \fBstart\fR, \fBstop\fR, and -\fBrestart\fR should not modify the running status of \fBovs\-vswitchd\fR. -It is an error to include this option with the \fBforce\-reload\-kmod\fR -command. -. -.SH "EXIT STATUS" -. -\fBovs\-ctl\fR exits with status 0 on success and nonzero on failure. -The \fBstart\fR command is considered to succeed if OVS is already -started; the \fBstop\fR command is considered to succeed if OVS is -already stopped. -. -.SH "ENVIRONMENT" -. -The following environment variables affect \fBovs\-ctl\fR: -. -.IP "\fBPATH\fR" -\fBovs\-ctl\fR does not hardcode the location of any of the programs -that it runs. \fBovs\-ctl\fR will add the \fIsbindir\fR and -\fIbindir\fR that were specified at \fBconfigure\fR time to -\fBPATH\fR, if they are not already present. -. -.IP "\fBOVS_LOGDIR\fR" -.IQ "\fBOVS_RUNDIR\fR" -.IQ "\fBOVS_DBDIR\fR" -.IQ "\fBOVS_SYSCONFDIR\fR" -.IQ "\fBOVS_PKGDATADIR\fR" -.IQ "\fBOVS_BINDIR\fR" -.IQ "\fBOVS_SBINDIR\fR" -Setting one of these variables in the environment overrides the -respective \fBconfigure\fR option, both for \fBovs\-ctl\fR itself and -for the other Open vSwitch programs that it runs. -. -.SH "FILES" -. -\fBovs\-ctl\fR uses the following files: -. -.IP "\fBovs\-lib" -Shell function library used internally by \fBovs\-ctl\fR. It must be -installed in the same directory as \fBovs\-ctl\fR. -. -.IP "\fIlogdir\fB/\fIdaemon\fB.log\fR" -Per-daemon logfiles. -. -.IP "\fIrundir\fB/\fIdaemon\fB.pid\fR" -Per-daemon pidfiles to track whether a daemon is running and with what -process ID. -. -.IP "\fIpkgdatadir\fB/vswitch.ovsschema\fR" -The OVS database schema used to initialize the database (use -\fB\-\-db\-schema to override this location). -. -.IP "\fIdbdir\fB/conf.db\fR" -The OVS database (use \fB\-\-db\-file\fR to override this location). -. -.IP "\fIrundir\fB/openvswitch/db.sock\fR" -The Unix domain socket used for local communication with -\fBovsdb\-server\fR (use \fB\-\-db\-sock\fR to override this -location). -. -.IP "\fIsysconfdir\fB/openvswitch/system-id.conf\fR" -The persistent system UUID created and read by -\fB\-\-system\-id=random\fR. -. -.IP "\fIsysconfdir\fB/openvswitch/system\-type.conf\fR" -.IQ "\fIsysconfdir\fB/openvswitch/system\-version.conf\fR" -The \fBsystem\-type\fR and \fBsystem\-version\fR values stored in the database's -\fBOpen_vSwitch\fR table when not specified as a command-line option. -. -.SH "EXAMPLE" -. -.PP -The files \fBdebian/openvswitch\-switch.init\fR and -\fBxenserver/etc_init.d_openvswitch\fR in the Open vSwitch source -distribution are good examples of how to use \fBovs\-ctl\fR. -. -.SH "SEE ALSO" -. -\fBREADME.rst\fR, \fBovsdb\-server\fR(8), \fBovs\-vswitchd\fR(8). diff --git a/utilities/ovs-l3ping.8.in b/utilities/ovs-l3ping.8.in deleted file mode 100644 index 95a00b7bc..000000000 --- a/utilities/ovs-l3ping.8.in +++ /dev/null @@ -1,110 +0,0 @@ -.so lib/ovs.tmac -.TH ovs\-l3ping 1 "@VERSION@" "Open vSwitch" "Open vSwitch Manual" -. -.SH NAME -\fBovs\-l3ping\fR \- check network deployment for L3 tunneling -problems -. -.SH SYNOPSIS -\fBovs\-l3ping\fR \fB\-s\fR \fITunnelRemoteIP,InnerIP[/mask]\fR \fB\-t\fR \fItunnelmode\fR -.br -\fBovs\-l3ping\fR \fB\-s\fR \fITunnelRemoteIP,InnerIP[/mask][:ControlPort]\fR \fB\-t\fR \fItunnelmode\fR -.PP -\fBovs\-l3ping\fR \fB\-c\fR \fITunnelRemoteIP,InnerIP[/mask],RemoteInnerIP\fR \fB\-t\fR \fItunnelmode\fR -.br -\fBovs\-l3ping\fR \fB\-c\fR \fITunnelRemoteIP,InnerIP[/mask][:ControlPort\ -[:DataPort]],RemoteInnerIP[:ControlPort[:DataPort]]\fR -[\fB\-b\fR \fItargetbandwidth\fR] [\fB\-i\fR \fItestinterval\fR] -\fB\-t\fR \fItunnelmode\fR -.so lib/common-syn.man -. -.SH DESCRIPTION -The \fBovs\-l3ping\fR program may be used to check for problems that could -be caused by invalid routing policy, misconfigured firewall in the tunnel -path or a bad NIC driver. On one of the nodes, run \fBovs\-l3ping\fR in -server mode and on the other node run it in client mode. The client and -server will establish L3 tunnel, over which client will give further testing -instructions. The \fBovs\-l3ping\fR client will perform UDP and TCP tests. -This tool is different from \fBovs\-test\fR that it encapsulates XML/RPC -control connection over the tunnel, so there is no need to open special holes -in firewall. -.PP -UDP tests can report packet loss and achieved bandwidth for various -datagram sizes. By default target bandwidth for UDP tests is 1Mbit/s. -.PP -TCP tests report only achieved bandwidth, because kernel TCP stack -takes care of flow control and packet loss. -. -.SS "Client Mode" -An \fBovs\-l3ping\fR client will create a L3 tunnel and connect over it to the -\fBovs\-l3ping\fR server to schedule the tests. \fITunnelRemoteIP\fR is the -peer's IP address, where tunnel will be terminated. \fIInnerIP\fR is the -address that will be temporarily assigned during testing. All test traffic -originating from this IP address to the \fIRemoteInnerIP\fR will be tunneled. -It is possible to override default \fIControlPort\fR and \fIDataPort\fR, if -there is any other application that already listens on those two ports. -. -.SS "Server Mode" -To conduct tests, \fBovs\-l3ping\fR server must be running. It is required -that both client and server \fIInnerIP\fR addresses are in the same subnet. -It is possible to specify \fIInnerIP\fR with netmask in CIDR format. -. -.SH OPTIONS -One of \fB\-s\fR or \fB\-c\fR is required. The \fB\-t\fR option is -also required. -. -.IP "\fB\-s \fITunnelRemoteIP,InnerIP[/mask][:ControlPort]\fR" -.IQ "\fB\-\-server\fR \fITunnelRemoteIP,InnerIP[/mask][:ControlPort]\fR" -Run in server mode and create L3 tunnel with the client that will be -accepting tunnel at \fITunnelRemoteIP\fR address. The socket on -\fIInnerIP[:ControlPort]\fR will be used to receive further instructions -from the client. -. -.IP "\fB\-c \fITunnelRemoteIP,InnerIP[/mask][:ControlPort\ -[:DataPort]],RemoteInnerIP[:ControlPort[:DataPort]]\fR" -.IQ "\fB\-\-client \fITunnelRemoteIP,InnerIP[/mask][:ControlPort\ -[:DataPort]],RemoteInnerIP[:ControlPort[:DataPort]]\fR" -Run in client mode and create L3 tunnel with the server on -\fITunnelRemoteIP\fR. The client will use \fIInnerIP\fR to generate test -traffic with the server's \fIRemoteInnerIP\fR. -. -.IP "\fB\-b \fItargetbandwidth\fR" -.IQ "\fB\-\-bandwidth\fR \fItargetbandwidth\fR" -Target bandwidth for UDP tests. The \fItargetbandwidth\fR must be given in -bits per second. It is possible to use postfix M or K to alter the target -bandwidth magnitude. -. -.IP "\fB\-i \fItestinterval\fR" -.IQ "\fB\-\-interval\fR \fItestinterval\fR" -How long each test should run. By default 5 seconds. -. -.IP "\fB\-t \fItunnelmode\fR" -.IQ "\fB\-\-tunnel\-mode\fR \fItunnelmode\fR" -Specify the tunnel type. This option must match on server and client. -. -.so lib/common.man -. -.SH EXAMPLES -.PP -On host 192.168.122.220 start \fBovs\-l3ping\fR in server mode. This command -will create a temporary GRE tunnel with the host 192.168.122.236 and assign -10.1.1.1/28 as the inner IP address, where client will have to connect: -.IP -.B ovs\-l3ping -s 192.168.122.236,10.1.1.1/28 -t gre -. -.PP -On host 192.168.122.236 start \fBovs\-l3ping\fR in client mode. This command -will use 10.1.1.2/28 as the local inner IP address and will connect over the -L3 tunnel to the server's inner IP address at 10.1.1.1. -.IP -.B ovs\-l3ping -c 192.168.122.220,10.1.1.2/28,10.1.1.1 -t gre -. -.SH SEE ALSO -. -.BR ovs\-vswitchd (8), -.BR ovs\-ofctl (8), -.BR ovs\-vsctl (8), -.BR ovs\-vlan\-test (8), -.BR ovs\-test (8), -.BR ethtool (8), -.BR uname (1) diff --git a/utilities/ovs-parse-backtrace.8 b/utilities/ovs-parse-backtrace.8 deleted file mode 100644 index 2fa7c174f..000000000 --- a/utilities/ovs-parse-backtrace.8 +++ /dev/null @@ -1,28 +0,0 @@ -.TH ovs\-parse\-backtrace 8 "October 2012" "Open vSwitch" "Open vSwitch Manual" -. -.SH NAME -ovs\-parse\-backtrace \- parses ovs-appctl backtrace output -. -.SH SYNOPSIS -\fBovs\-appctl backtrace\fR | \fBovs\-parse\-backtrace\fR [\fIbinary\fR] -.P -\fBovs\-parse\-backtrace\fR [\fIbinary\fR] < \fIbacktrace\fR -. -.SH DESCRIPTION -In some configurations, many Open vSwitch daemons can produce a series of -backtraces using the \fBovs\-appctl backtrace\fR command. Users can analyze -these backtraces to figure out what the given Open vSwitch daemon may be -spending most of its time doing. \fBovs\-parse\-backtrace\fR makes this output -easier to interpret. -.PP -The \fBovs\-appctl backtrace\fR output must be supplied on standard input. The -binary that produced the output should be supplied as the sole non-option -argument. For best results, the binary should have debug symbols. -. -.SH OPTIONS -.TP -\fB\-\-help\fR -Prints a usage message and exits. -.P -\fB\-\-version\fR -Prints the version and exits. diff --git a/utilities/ovs-pki.8.in b/utilities/ovs-pki.8.in deleted file mode 100644 index f8f5f063a..000000000 --- a/utilities/ovs-pki.8.in +++ /dev/null @@ -1,243 +0,0 @@ -.so lib/ovs.tmac -.TH ovs\-pki 8 "@VERSION@" "Open vSwitch" "Open vSwitch Manual" - -.SH NAME -ovs\-pki \- OpenFlow public key infrastructure management utility - -.SH SYNOPSIS -Each command takes the form: -.sp -\fBovs\-pki\fR [\fIoptions\fR] \fIcommand\fR [\fIargs\fR] -.sp -The implemented commands and their arguments are: -.br -\fBovs\-pki\fR \fBinit\fR -.br -\fBovs\-pki\fR \fBreq\fR \fIname\fR -.br -\fBovs\-pki\fR \fBsign\fR \fIname\fR [\fItype\fR] -.br -\fBovs\-pki\fR \fBreq+sign\fR \fIname\fR [\fItype\fR] -.br -\fBovs\-pki\fR \fBverify\fR \fIname\fR [\fItype\fR] -.br -\fBovs\-pki\fR \fBfingerprint\fR \fIfile\fR -.br -\fBovs\-pki\fR \fBself\-sign\fR \fIname\fR -.sp -Each \fItype\fR above is a certificate type, either \fBswitch\fR -(default) or \fBcontroller\fR. -.sp -The available options are: -.br -[\fB\-k\fR \fItype\fR | \fB\-\^\-key=\fItype\fR] -.br -[\fB\-B\fR \fInbits\fR | \fB\-\^\-bits=\fInbits\fR] -.br -[\fB\-D\fR \fIfile\fR | \fB\-\^\-dsaparam=\fIfile\fR] -.br -[\fB\-b\fR | \fB\-\^\-batch\fR] -.br -[\fB\-f\fR | \fB\-\^\-force\fR] -.br -[\fB\-d\fR \fIdir\fR | \fB\-\^\-dir=\fR\fIdir\fR] -.br -[\fB\-l\fR \fIfile\fR | \fB\-\^\-log=\fIfile\fR] -.br -[\fB\-u\fR | \fB\-\^\-unique\fR] -.br -[\fB\-h\fR | \fB\-\^\-help\fR] -.sp -Some options do not apply to every command. - -.SH DESCRIPTION -The \fBovs\-pki\fR program sets up and manages a public key -infrastructure for use with OpenFlow. It is intended to be a simple -interface for organizations that do not have an established public key -infrastructure. Other PKI tools can substitute for or supplement the -use of \fBovs\-pki\fR. - -\fBovs\-pki\fR uses \fBopenssl\fR(1) for certificate management and key -generation. - -.SH "OFFLINE COMMANDS" - -The following \fBovs\-pki\fR commands support manual PKI -administration: - -.TP -\fBinit\fR -Initializes a new PKI (by default in directory \fB@PKIDIR@\fR) and populates -it with a pair of certificate authorities for controllers and -switches. - -This command should ideally be run on a high\-security machine separate -from any OpenFlow controller or switch, called the CA machine. The -files \fBpki/controllerca/cacert.pem\fR and -\fBpki/switchca/cacert.pem\fR that it produces will need to be copied -over to the OpenFlow switches and controllers, respectively. Their -contents may safely be made public. - -By default, \fBovs\-pki\fR generates 2048\-bit RSA keys. The \fB\-B\fR -or \fB\-\^\-bits\fR option (see below) may be used to override the key -length. The \fB\-k dsa\fR or \fB\-\^\-key=dsa\fR option may be used to use -DSA in place of RSA. If DSA is selected, the \fBdsaparam.pem\fR file -generated in the new PKI hierarchy must be copied to any machine on -which the \fBreq\fR command (see below) will be executed. Its -contents may safely be made public. - -Other files generated by \fBinit\fR may remain on the CA machine. -The files \fBpki/controllerca/private/cakey.pem\fR and -\fBpki/switchca/private/cakey.pem\fR have particularly sensitive -contents that should not be exposed. - -.TP -\fBreq\fR \fIname\fR -Generates a new private key named \fIname\fR\fB\-privkey.pem\fR and -corresponding certificate request named \fIname\fR\fB\-req.pem\fR. -The private key can be intended for use by a switch or a controller. - -This command should ideally be run on the switch or controller that -will use the private key to identify itself. The file -\fIname\fR\fB\-req.pem\fR must be copied to the CA machine for signing -with the \fBsign\fR command (below). - -This command will output a fingerprint to stdout as its final step. -Write down the fingerprint and take it to the CA machine before -continuing with the \fBsign\fR step. - -When RSA keys are in use (as is the default), \fBreq\fR, unlike the -rest of \fBovs\-pki\fR's commands, does not need access to a PKI -hierarchy created by \fBovs\-pki init\fR. The \fB\-B\fR or -\fB\-\^\-bits\fR option (see below) may be used to specify the number of -bits in the generated RSA key. - -When DSA keys are used (as specified with \fB\-\^\-key=dsa\fR), \fBreq\fR -needs access to the \fBdsaparam.pem\fR file created as part of the PKI -hierarchy (but not to other files in that tree). By default, -\fBovs\-pki\fR looks for this file in \fB@PKIDIR@/dsaparam.pem\fR, but -the \fB\-D\fR or \fB\-\^\-dsaparam\fR option (see below) may be used to -specify an alternate location. - -\fIname\fR\fB\-privkey.pem\fR has sensitive contents that should not be -exposed. \fIname\fR\fB\-req.pem\fR may be safely made public. - -.TP -\fBsign\fR \fIname\fR [\fItype\fR] -Signs the certificate request named \fIname\fR\fB\-req.pem\fR that was -produced in the previous step, producing a certificate named -\fIname\fR\fB\-cert.pem\fR. \fItype\fR, either \fBswitch\fR (default) or -\fBcontroller\fR, indicates the use for which the key is being -certified. - -This command must be run on the CA machine. - -The command will output a fingerprint to stdout and request that you -verify that it is the same fingerprint output by the \fBreq\fR -command. This ensures that the request being signed is the same one -produced by \fBreq\fR. (The \fB\-b\fR or \fB\-\^\-batch\fR option -suppresses the verification step.) - -The file \fIname\fR\fB\-cert.pem\fR will need to be copied back to the -switch or controller for which it is intended. Its contents may -safely be made public. - -.TP -\fBreq+sign\fR \fIname\fR [\fItype\fR] -Combines the \fBreq\fR and \fBsign\fR commands into a single step, -outputting all the files produced by each. The -\fIname\fR\fB\-privkey.pem\fR and \fIname\fR\fB\-cert.pem\fR files must -be copied securely to the switch or controller. -\fIname\fR\fB\-privkey.pem\fR has sensitive contents and must not be -exposed in transit. Afterward, it should be deleted from the CA -machine. - -This combined method is, theoretically, less secure than the -individual steps performed separately on two different machines, -because there is additional potential for exposure of the private -key. However, it is also more convenient. - -.TP -\fBverify\fR \fIname\fR [\fItype\fR] -Verifies that \fIname\fR\fB\-cert.pem\fR is a valid certificate for the -given \fItype\fR of use, either \fBswitch\fR (default) or -\fBcontroller\fR. If the certificate is valid for this use, it prints -the message ``\fIname\fR\fB\-cert.pem\fR: OK''; otherwise, it prints an -error message. - -.TP -\fBfingerprint\fR \fIfile\fR -Prints the fingerprint for \fIfile\fR. If \fIfile\fR is a -certificate, then this is the SHA\-1 digest of the DER encoded version -of the certificate; otherwise, it is the SHA\-1 digest of the entire -file. - -.TP -\fBself\-sign\fR \fIname\fR -Signs the certificate request named \fIname\fB\-req.pem\fR using the -private key \fIname\fB\-privkey.pem\fR, producing a self-signed -certificate named \fIname\fB\-cert.pem\fR. The input files should have -been produced with \fBovs\-pki req\fR. - -Some controllers accept such self-signed certificates. - -.SH OPTIONS -.IP "\fB\-k\fR \fItype\fR" -.IQ "\fB\-\^\-key=\fItype\fR" -For the \fBinit\fR command, sets the public key algorithm to use for -the new PKI hierarchy. For the \fBreq\fR and \fBreq+sign\fR commands, -sets the public key algorithm to use for the key to be generated, -which must match the value specified on \fBinit\fR. With other -commands, the value has no effect. - -The \fItype\fR may be \fBrsa\fR (the default) or \fBdsa\fR. - -.IP "\fB\-B\fR \fInbits\fR" -.IQ "\fB\-\^\-bits=\fInbits\fR" -Sets the number of bits in the key to be generated. When RSA keys are -in use, this option affects only the \fBinit\fR, \fBreq\fR, and -\fBreq+sign\fR commands, and the same value should be given each time. -With DSA keys are in use, this option affects only the \fBinit\fR -command. - -The value must be at least 1024. The default is 2048. - -.IP "\fB\-D\fR \fIfile\fR" -.IQ "\fB\-\^\-dsaparam=\fIfile\fR" -Specifies an alternate location for the \fBdsaparam.pem\fR file -required by the \fBreq\fR and \fBreq+sign\fR commands. This option -affects only these commands, and only when DSA keys are used. - -The default is \fBdsaparam.pem\fR under the PKI hierarchy. - -.IP "\fB\-b\fR" -.IQ "\fB\-\^\-batch\fR" -Suppresses the interactive verification of fingerprints that the -\fBsign\fR command by default requires. - -.IP "\fB\-d\fR \fIdir\fR" -.IQ "\fB\-\^\-dir=\fR\fIdir\fR" -Specifies the location of the PKI hierarchy to be used or created by -the command (default: \fB@PKIDIR@\fR). All commands, except \fBreq\fR, -need access to a PKI hierarchy. - -.IP "\fB\-f\fR" -.IQ "\fB\-\^\-force\fR" -By default, \fBovs\-pki\fR will not overwrite existing files or -directories. This option overrides this behavior. - -.IP "\fB\-l\fR \fIfile\fR" -.IQ "\fB\-\^\-log=\fIfile\fR" -Sets the log file to \fIfile\fR. Default: -\fB@LOGDIR@/ovs\-pki.log\fR. - -.IP "\fB\-u\fR" -.IQ "\fB\-\^\-unique\fR" -Changes the format of the certificate's Common Name (CN) field; by -default, this field has the format "<name> id:<uuid-or-date>", this -option causes the provided name to be treated as unique and changes -the format of the CN field to be simply "<name>". - -.IP "\fB\-h\fR" -.IQ "\fB\-\^\-help\fR" -Prints a help usage message and exits. diff --git a/utilities/ovs-tcpdump.8.in b/utilities/ovs-tcpdump.8.in deleted file mode 100644 index aca61e2bc..000000000 --- a/utilities/ovs-tcpdump.8.in +++ /dev/null @@ -1,55 +0,0 @@ -.so lib/ovs.tmac -.TH ovs\-tcpdump 8 "@VERSION@" "Open vSwitch" "Open vSwitch Manual" -. -.SH NAME -ovs\-tcpdump \- Dump traffic from an Open vSwitch port using \fBtcpdump\fR. -. -.SH SYNOPSIS -\fBovs\-tcpdump\fR \fB\-i\fR \fIport\fR \fBtcpdump options...\fR -. -.SH DESCRIPTION -\fBovs\-tcpdump\fR creates switch mirror ports in the \fBovs\-vswitchd\fR -daemon and executes \fBtcpdump\fR to listen against those ports. When the -\fBtcpdump\fR instance exits, it then cleans up the mirror port it created. -.PP -\fBovs\-tcpdump\fR will not allow multiple mirrors for the same port. It has -some logic to parse the current configuration and prevent duplicate mirrors. -.PP -The \fB\-i\fR option may not appear multiple times. -.PP -It is important to note that under \fBLinux\fR based kernels, tap devices do -not receive packets unless the specific tuntap device has been opened by an -application. This requires \fBCAP_NET_ADMIN\fR privileges, so the -\fBovs-tcpdump\fR command must be run as a user with such permissions (this -is usually a super-user). -. -.SH "OPTIONS" -.so lib/common.man -. -.IP "\fB\-\-db\-sock\fR" -The Open vSwitch database socket connection string. The default is -\fIunix:@RUNDIR@/db.sock\fR -. -.IP "\fB\-\-dump\-cmd\fR" -The command to run instead of \fBtcpdump\fR. -. -.IP "\fB\-i\fR" -.IQ "\fB\-\-interface\fR" -The interface for which a mirror port should be created, and packets should -be dumped. -. -.IP "\fB\-\-mirror\-to\fR" -The name of the interface which should be the destination of the mirrored -packets. The default is miINTERFACE -. -.IP "\fB\-\-span\fR" -If specified, mirror all ports (optional). -. -.SH "SEE ALSO" -. -.BR ovs\-appctl (8), -.BR ovs\-vswitchd (8), -.BR ovs\-pcap (1), -.BR ovs\-tcpundump (1), -.BR tcpdump (8), -.BR wireshark (8). diff --git a/utilities/ovs-tcpundump.1.in b/utilities/ovs-tcpundump.1.in deleted file mode 100644 index ec2c1505d..000000000 --- a/utilities/ovs-tcpundump.1.in +++ /dev/null @@ -1,32 +0,0 @@ -.so lib/ovs.tmac -.TH ovs\-tcpundump 1 "@VERSION@" "Open vSwitch" "Open vSwitch Manual" -. -.SH NAME -ovs\-tcpundump \- convert ``tcpdump \-xx'' output to hex strings -. -.SH SYNOPSIS -\fBovs\-tcpundump < \fIfile\fR -.so lib/common-syn.man -. -.SH DESCRIPTION -The \fBovs\-tcpundump\fR program reads \fBtcpdump \-xx\fR output on -stdin, looking for hexadecimal packet data, and dumps each Ethernet as -a single hexadecimal string on stdout. This format is suitable for -use with the \fBofproto/trace\fR command supported by -\fBovs\-vswitchd\fR(8) -via \fBovs\-appctl\fR(8). -.PP -At least two \fB\-x\fR or \fB\-X\fR options must be given, otherwise -the output will omit the Ethernet header, which prevents the output -from being using with \fBofproto/trace\fR. -. -.SH "OPTIONS" -.so lib/common.man -. -.SH "SEE ALSO" -. -.BR ovs\-appctl (8), -.BR ovs\-vswitchd (8), -.BR ovs\-pcap (1), -.BR tcpdump (8), -.BR wireshark (8). |