Skip to content

Latest commit

 

History

History
201 lines (149 loc) · 8.22 KB

configuration.rst

File metadata and controls

201 lines (149 loc) · 8.22 KB
Raw

Configuration

Clixon configuration files are encoded in XML and modeled by YANG. By default, the main config file is installed as /usr/local/etc/clixon.xml, but can be changed by the -f <file> command-line option.

The YANG specification for Clixon configuration is clixon-config.yang. This configuration file is updated regularly.

Normally, all Clixon processes (backend, cli, netconf, restconf) use the same configuration, although some options are not valid for all processes. You can however have different configuration files for different clients by using the -f option.

Loading an obsolete config option will result in an error.

Please consult the clixon-config YANG spec directly if you want detailed description of config options.

5   Example

The following is the configuration file of a simple example:

<clixon-config xmlns="http://clicon.org/config">
  <CLICON_CONFIGFILE>/usr/local/etc/clixon.xml</CLICON_CONFIGFILE>
  <CLICON_CONFIGDIR>/usr/local/etc/clixon.d</CLICON_CONFIGDIR>
  <CLICON_FEATURE>*:*</CLICON_FEATURE>
  <CLICON_YANG_DIR>/usr/local/share/clixon</CLICON_YANG_DIR>
  <CLICON_YANG_MODULE_MAIN>clixon-hello</CLICON_YANG_MODULE_MAIN>
  <CLICON_CLI_MODE>hello</CLICON_CLI_MODE>
  <CLICON_CLISPEC_DIR>/usr/local/lib/hello/clispec</CLICON_CLISPEC_DIR>
  <CLICON_SOCK>/usr/local/var/hello.sock</CLICON_SOCK>
  <CLICON_BACKEND_PIDFILE>/usr/local/var/hello.pidfile</CLICON_BACKEND_PIDFILE>
  <CLICON_XMLDB_DIR>/usr/local/var/hello</CLICON_XMLDB_DIR>
  <CLICON_STARTUP_MODE>init</CLICON_STARTUP_MODE>
  <restconf>
     <enable>true</enable>
  </restconf>
</clixon-config>

The option CLICON_CONFIGFILE is special, it must be available before the configuration file is found (see Loading the configuration), which means that the value in the file is a no-op.

The restconf clause defines RESTCONF configuration options as described in the :ref:`restconf section <clixon_restconf>` section.

6   Loading the configuration

Clixon finds its configuration files, according to the following method:

  1. Start a clixon program with the -f <FILE> option. For example:

    clixon_backend -f FILE

  2. At install time, Use the --with-configfile=FILE option to configure a default location:

    ./configure --with-configfile=FILE

  3. At install time: ./configure --with-sysconfig=<dir> when configuring. Then FILE is <dir>/clixon.xml

  4. At install time: ./configure --sysconfig=<dir> when configuring. Then FILE is <dir>/etc/clixon.xml

  5. If none of the above: FILE is /usr/local/etc/clixon.xml

The following options control the Clixon configuration:

CLICON_CONFIGFILE
The configure file itself. Due to bootstrapping reasons, its value is meaningless in a file but can be useful for documentation purposes.
CLICON_CONFIGDIR

A directory of extra configuration files loaded after the main configuration. It can also be specified using the -E <dir> command-line option. These extra configuration files are read in alphabetical order after the main configuration as follows:

  • leaf values are overwritten
  • leaf-list values are appended

7   Runtime modification

You can modify clixon options at runtime by using the -o option to modify the configuration specified in the configuration file. For example, add usr/local/share/ietf to the list of directories where yang files are searched for:

clixon_cli -o CLICON_YANG_DIR=/usr/local/share/ietf

8   Features

CLICON_FEATURE is a list of values, describing how Clixon supports features.

A value is specified as one of the following:

  • <module>:<feature> : enable a specific feature in a specific module
  • *:* : enable all features in all modules
  • <module>:* : enable all features in the specified module
  • *:<feature> : enable the specific feature in all modules.

Example:

<CLICON_FEATURE>ietf-netconf:startup</CLICON_FEATURE>
<CLICON_FEATURE>ietf-netconf:*</CLICON_FEATURE>
<CLICON_FEATURE>*:*</CLICON_FEATURE>

Supplying the -o option adds a value to the feature list.

Clixon have three hardcoded features:

  • ietf-netconf:candidate (RFC6241 8.3)
  • ietf-netconf:validate (RFC6241 8.6)
  • ietf-netconf:xpath (RFC6241 8.9)

9   Finding YANG files

The example have two options for finding Yang files:

<CLICON_YANG_DIR>/usr/local/share/clixon</CLICON_YANG_DIR>
<CLICON_YANG_MODULE_MAIN>clixon-hello</CLICON_YANG_MODULE_MAIN>

which means that Yang files are searched for in /usr/local/share/clixon and that module clixon-hello is loaded. Note:

  • clixon-hello.yang must be present in /usr/local/share/clixon
  • Clixon itself may load several YANG files as part of the system startup, such as clixon-config.yang. These must all reside in the list of CLICON_YANG_DIR:s.
  • When a Yang file is loaded, it may contain references to other Yang files (eg using import and include). They must also be found in the list of CLICON_YANG_DIR:s.

The following configuration file options control the loading of Yang files:

CLICON_YANG_DIR
A list of directories (yang dir path) where Clixon searches for module and submodules recursively.
CLICON_YANG_MAIN_FILE
Load a specific Yang module given by a file.
CLICON_YANG_MODULE_MAIN
Specifies a single module to load. The module is searched for in the yang dir path.
CLICON_YANG_MODULE_REVISION
Specifies a revision to the main module.
CLICON_YANG_MAIN_DIR
Load all yang modules in this directory, not recursively.

Note that the special YANG_INSTALLDIR autoconf configure option, by default /usr/local/share/clixon should be included in the yang dir path for Clixon system files to be found.

You can combine the options, however, if there are different variants of the same module, more specific options override less specific. The precedence of the options are as follows:

  1. CLICON_YANG_MAIN_FILE
  2. CLICON_YANG_MODULE_MAIN
  3. CLICON_YANG_MAIN_DIR

Note that using CLICON_YANG_MAIN_DIR Clixon may find several files containing the same Yang module. Clixon will prefer the one without a revision date if such a file exists. If no file has a revision date, Clixon will prefer the newest.

10   Standard YANG files

The main examples and tests require IETF RFC standard YANGs. If you want to run the main example or run tests, you need to make them locally available by checking out https://github.com/YangModels/yang which has subdir standard. By default this directory is /usr/local/share/yang You can change this location by:

./configure --with-yang-standard-dir=DIR

Note that you do not need this for the clixon runtime.

11   Extending the configuration

You can extend the options with an application-specific YANG file where you augment the regular "clixon-config" as follows:

<clixon-config xmlns="http://clicon.org/config">
  <CLICON_CONFIGFILE>/usr/local/etc/clixon.xml</CLICON_CONFIGFILE>
  <CLICON_CONFIG_EXTEND>clixon-myconfig</CLICON_CONFIG_EXTEND>
  ...

You then install your own "clixon-myconfig.yang" where you add your own config options. Example:

module clixon-myconfig {
  yang-version 1.1;
  namespace "http://example.org/myconfig";
  ...
  import clixon-config {
      prefix "cc";
  }
  augment "/cc:clixon-config" {
      description
          "My extended options";
      leaf MYOPT {
          type string;
      }

You can now use your extended options in the regular config file, along with the basic ones, but with another namespace:

<clixon-config xmlns="http://clicon.org/config">
  <CLICON_CONFIGFILE>/usr/local/etc/clixon.xml</CLICON_CONFIGFILE>
  <CLICON_CONFIG_EXTEND>clixon-myconfig</CLICON_CONFIG_EXTEND>
  ...
  <MYOPT xmlns="http://example.org/myconfig">/usr/local/share/myopt</MYOPT>

You can also use the regular C-API to access the values of the options, eg:

char *val = clicon_option_str(h, "MYOPT");