==========
ovs-appctl
==========

Synopsis
========

``ovs-appctl``
[``--target=``\ *target* | ``-t`` *target*]
[``--timeout=``\ *secs* | ``-T`` *secs*]
[``--format=``\ *format* | ``-f`` *format*]
[``--pretty``]
*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.

* ``-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.

* ``-f`` *format* or ``--format=``\ *format*

  Tells ``ovs-appctl`` which output format to use.  By default, or with a
  *format* of ``text``, ``ovs-appctl`` will print plain-text for humans.
  When *format* is ``json``, ``ovs-appctl`` will return a JSON document.
  When ``json`` is requested, but a command has not implemented JSON
  output, the plain-text output will be wrapped in a provisional JSON
  document with the following structure::

    {"reply-format":"plain","reply":"$PLAIN_TEXT_HERE"}

* ``--pretty``

  By default, JSON output is printed as compactly as possible.  This option
  causes JSON in output to be printed in a more readable fashion.  For
  example, members of objects and elements of arrays are printed one
  per line, with indentation.  Requires ``--format=json``.

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.

  * ``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-monitor-ipsec``) 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)``.
