Diff Formats

The configuration management tool onecfg allows us to compare the configuration files to identify user changes against the OpenNebula distributed files. The result of a comparison, the differential output, describes all the individual changes which were made and which can even be applied again later or on a different machine.

The following table shows supported formats by each subcommand:

Only line format will be described here in detail, as it’s powerful in achieving even complex changes and easy enough to read or write manually.

Line Format

Each line of change consists of the following space-separated parts:

<FILENAME> <COMMAND> <PATH> [<JSON VALUE>]

with the following meanings:

FILENAME

Filename is an absolute path to the well-known configuration file of OpenNebula that is going to be changed.

COMMAND

Command is a type of operation to be executed on the configuration file. Only the following commands are available:

• ins - insert new configuration parameter
• set - change existing parameter
• rm - remove parameter

PATH

Path uniquely identifies the location of the changed parameter as a slash / separated XPath-like segments and key from document root and without leading slash (e.g., path/path/path/key). If any path element contains spaces, the whole path must be quoted with (and only with!) double quotes ("), internal double quotes must be escaped by backslash (\).

Examples:

• for the following /etc/one/oned.conf snippet

PORT = 2633                                  # path 1

DB = [ BACKEND = "sqlite",                   # path 2
       TIMEOUT = 2500 ]

IM_MAD = [
      NAME       = "monitord",
      EXECUTABLE = "onemonitord",
      ARGUMENTS  = "-c monitord.conf",
      THREADS    = 8 ]                       # path 3

these paths are valid to address the emphasized parameters:

1. PORT
2. DB/BACKEND or "DB/BACKEND"
3. IM_MAD/"monitord"/THREADS or "IM_MAD/\"monitord\"/THREADS"

• for the following /etc/one/fireedge-server.conf snippet

# OpenNebula: use it if you have oned and fireedge on different servers
:one_xmlrpc: http://localhost:2633/RPC2     # path 4

these paths are valid to address the emphasized parameter(s):

1. :one_xmlrpc or ":one_xmlrpc"

• for the following /etc/one/cli/oneimage.yaml snippet

---
:ID:
  :desc: ONE identifier for the Image       # path 5
  :size: 4
  :adjust: true

these paths are valid to address the emphasized parameter(s):

1. :IP/:desc or ":IP/:desc"

JSON VALUE

The value encoded in JSON is mandatory only for ins and set commands. It can contain simple values or complex structures, string values must be quoted with (and only with!) double quotes (").

Examples:

• no text is an uninitialized value
• null - uninitialized value
• 11 - Integer value 11
• "11" - String value 11
• '11' - invalid JSON value!
• "'11'" - String value '11'
• "\"11\" - String value "11" (strings with inner quotes must be escaped)
• true - Boolean value true
• "true" - String value true
• ["apple", "orange"] - Array with 2 String values apple and orange
• ['apple', 'orange"] - invalid JSON value!
• {"fruit": "apple"} - Hash with key fruit with value apple
• {'fruit': 'apple'} - invalid JSON value!

Examples

# onecfg diff --format line
/etc/one/cli/oneimage.yaml ins :ID/:adjust false
/etc/one/cli/oneimage.yaml set :USER/:size 15
/etc/one/cli/oneimage.yaml set :GROUP/:size 15
/etc/one/cli/oneimage.yaml ins :NAME/:expand false
/etc/one/oned.conf set DEFAULT_DEVICE_PREFIX "\"sd\""
/etc/one/oned.conf ins HM_MAD/ARGUMENTS "\"-p 2101 -l 2102 -b 127.0.0.1\""
/etc/one/oned.conf ins VM_RESTRICTED_ATTR "\"NIC/FILTER\""

How to read the output? Let’s go through few examples from above:

• /etc/one/cli/oneimage.yaml ins :ID/:adjust false - add new key :adjust with Boolean value false into top Hash structure :ID
• /etc/one/cli/oneimage.yaml set :USER/:size 15 - value for existing key :size inside top Hash structure :USER changes to 15

Text Format

Text format is similar to line format with visually separated sections for each configuration file and without a redundant filename on each line. It’s easier to read by humans but can’t be used as an input of the patch subcommand.

Example

# onecfg diff --format text
/etc/one/cli/oneimage.yaml
- ins :ID/:adjust false
- set :USER/:size 15
- set :GROUP/:size 15
- ins :NAME/:expand false

/etc/one/oned.conf
- set DEFAULT_DEVICE_PREFIX "\"sd\""
- ins HM_MAD/ARGUMENTS "\"-p 2101 -l 2102 -b 127.0.0.1\""
- ins VM_RESTRICTED_ATTR "\"NIC/FILTER\""

YAML Format

Contains complete information about the changes, the old original and new values, position (index) of value within an array, and even preserves symbolized keys and values (which are used in several configuration files). This format is recommended for use if it’s expected to identify and apply (patch) changes most accurately.

Example

# onecfg diff --format yaml
---
patches:
  "/etc/one/cli/oneimage.yaml":
    class: Yaml::Strict
    change:
    - path:
      - :ID
      key: :adjust
      value: false
      state: ins
      extra: {}
    - path:
      - :USER
      key: :size
      value: 15
      old: 8
      state: set
      extra: {}
    - path:
      - :GROUP
      key: :size
      value: 15
      old: 8
      state: set
      extra: {}
    - path:
      - :NAME
      key: :expand
      value: false
      state: ins
      extra: {}

< Previous page Next page >