utilities/ovs-cfg-mod.8.in

   1 .\" -*- nroff -*-
   2 .de IQ
   3 .  br
   4 .  ns
   5 .  IP "\\$1"
   6 ..
   7 .TH ovs\-cfg\-mod 8 "June 2009" "Open vSwitch" "Open vSwitch Manual"
   8 .ds PN ovs\-cfg\-mod
   9 .
  10 .SH NAME
  11 ovs\-cfg\-mod \- Safely manage a ovs\-vswitchd.conf\-style configuration file
  12 .
  13 .SH SYNOPSIS
  14 \fB ovs\-cfg\-mod \fR[\fB\-T \fItimeout\fR] \fB\-F \fIfile\fR
  15 [\fIaction\fR] [\fIaction\fR...\fR]
  16 .
  17 .SH DESCRIPTION
  18 A program for managing a \fovs\-vswitchd.conf\fR(5)\-style configuration
  19 file.  \fBovs\-cfg\-mod\fR uses the same locking mechanisms as
  20 \fBovs\-vswitchd\fR and its related utilities.  This allows it to be
  21 run safely on ``live'' configurations.
  22 .
  23 .SH OPTIONS
  24 .SS "Specifying the Configuration File"
  25 .
  26 .IP "\fB\-T\fR \fItimeout\fR
  27 .IQ "\fB\-\-timeout=\fItimeout\fR
  28 By default, \fBovs\-cfg\-mod\fR will wait forever to lock the
  29 configuration file specified on \fB\-F\fR or \fB\-\-config\-file\fR.  This
  30 option makes \fBovs\-cfg\-mod\fR wait no more than \fItimeout\fR
  31 milliseconds to obtain the lock, after which it exits unsuccessfully.
  32 .
  33 If it is present, this option must be specified before \fB\-F\fR or
  34 \fB\-\-config\-file\fR.
  35 .
  36 .IP "\fB\-F\fR \fIfile\fR"
  37 .IQ "\fB\-\-config\-file=\fIfile\fR"
  38 Use \fIfile\fR as the configuration file to query or modify.
  39 .
  40 This option is required.  It must be specified before any action
  41 options.
  42 .
  43 .SS "Specifying Actions"
  44 A series of one or more action options may follow the configuration
  45 file options.  These are executed in the order provided and under a
  46 single lock instance, so they appear atomic to external viewers of
  47 \fIfile\fR.
  48 .
  49 As discussed in \fBovs\-vswitchd.conf\fR(5), each line in the
  50 configuration file consists of a key\-value pair.  Actions generally
  51 take either a \fIkey\fR or \fIentry\fR argument.  A \fIkey\fR is a
  52 dot\-separated description of a configuration option.  A \fIentry\fR is
  53 a key\-value pair, separated by the \fB=\fR sign.
  54 .
  55 The following actions are supported:
  56 .
  57 .IP "\fB\-a\fR \fIentry\fR"
  58 .IQ "\fB\-\-add=\fIentry\fR"
  59 Add \fIentry\fR to \fIfile\fR.  Please note that duplicates are
  60 allowed, so if a unique key is required, a delete must be done first.
  61 .
  62 .IP "\fB\-d\fR \fIentry\fR"
  63 .IQ "\fB\-\-del\-entry=\fIentry\fR"
  64 Delete \fIentry\fR from \fIfile\fR.  Deletes only the first entry
  65 that matches \fIentry\fR.
  66 .
  67 .IP "\fB\-D\fR \fIkey\fR"
  68 .IQ "\fB\-\-del\-section=\fIkey\fR"
  69 Delete section \fIkey\fR from \fIfile\fR.
  70 .
  71 .IP "\fB\-\-del\-match=\fIpattern\fR"
  72 Deletes every entry that matches the given shell glob \fIpattern\fR.
  73 For example, \fB\-\-del\-match=bridge.*.port=*\fR deletes all the ports
  74 from every bridge, and \fB\-\-del\-match=bonding.bond0.*\fR is equivalent
  75 to \fB\-\-del\-section=bonding.bond0\fR.
  76 .
  77 .IP "\fB\-q\fR \fIkey\fR"
  78 .IQ "\fB\-\-query=\fIkey\fR"
  79 Queries \fIfile\fR for entries that match \fIkey\fR.  Each matching
  80 value is printed on a separate line.  Duplicates will be printed
  81 multiple times.
  82 .
  83 .IP "\fB\-c\fR"
  84 .IQ "\fB\-\-changes\fR"
  85 Logs all of the changes made to the configuration file in a ``unified
  86 diff''\-like format.  Only actual changes are logged, so that if, for
  87 example, a \fB\-\-del\-match\fR action did not match any key\-value pairs,
  88 then nothing will be logged due to that action.  Furthermore, only the
  89 net effects of changes are logged: if a key\-value pair was deleted and
  90 then an identical key\-value pair was added back, then nothing would be
  91 logged due to those changes.
  92 .
  93 This action logs changes that have taken effect at the point where it
  94 is inserted.  Thus, if it is given before any other action, it will
  95 not log any changes.  If \fB\-\-changes\fR is given more than once,
  96 instances after the first log only the changes since the previous
  97 instance.
  98 .
  99 .SH "SEE ALSO"
 100 .BR ovs\-vswitchd (8),
 101 .BR ovs\-vswitchd.conf (5)