diff --git a/README.md b/README.md index c1e3551f..de4ff01c 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,8 @@ +
+ +
[![Build Status](https://travis-ci.org/clicon/clixon.png)](https://travis-ci.org/clicon/clixon) [![Documentation Status](https://readthedocs.org/projects/clixon-docs/badge/?version=latest)](https://clixon-docs.readthedocs.io/en/latest/?badge=latest) -Clixon -====== Clixon is a YANG-based configuration manager, with interactive CLI, NETCONF and RESTCONF interfaces, an embedded database and transaction diff --git a/yang/clixon/clixon-config@2020-02-22.yang b/yang/clixon/clixon-config@2020-02-22.yang new file mode 100644 index 00000000..3232bc34 --- /dev/null +++ b/yang/clixon/clixon-config@2020-02-22.yang @@ -0,0 +1,672 @@ +module clixon-config { + yang-version 1.1; + namespace "http://clicon.org/config"; + prefix cc; + + organization + "Clicon / Clixon"; + + contact + "Olof Hagsand "; + + description + "Clixon configuration file + ***** BEGIN LICENSE BLOCK ***** + Copyright (C) 2009-2019 Olof Hagsand + Copyright (C) 2020 Olof Hagsand and Rubicon Communications, LLC + + This file is part of CLIXON + + Licensed under the Apache License, Version 2.0 (the \"License\"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an \"AS IS\" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + Alternatively, the contents of this file may be used under the terms of + the GNU General Public License Version 3 or later (the \"GPL\"), + in which case the provisions of the GPL are applicable instead + of those above. If you wish to allow use of your version of this file only + under the terms of the GPL, and not to allow others to + use your version of this file under the terms of Apache License version 2, + indicate your decision by deleting the provisions above and replace them with + the notice and other provisions required by the GPL. If you do not delete + the provisions above, a recipient may use your version of this file under + the terms of any one of the Apache License version 2 or the GPL. + + ***** END LICENSE BLOCK *****"; + + revision 2020-02-22 { + description "Added search index extension"; + } + revision 2019-09-11 { + description + "Added: CLICON_BACKEND_USER: drop of privileges to user, + CLICON_BACKEND_PRIVILEGES: how to drop privileges + CLICON_NACM_CREDENTIALS: If and how to check backend sock priveleges with NACM + CLICON_NACM_RECOVERY_USER: Name of NACM recovery user."; + } + revision 2019-06-05 { + description + "Added: CLICON_YANG_REGEXP, CLICON_CLI_TAB_MODE, + CLICON_CLI_HIST_FILE, CLICON_CLI_HIST_SIZE, + CLICON_XML_CHANGELOG, CLICON_XML_CHANGELOG_FILE; + Renamed CLICON_XMLDB_CACHE to CLICON_DATASTORE_CACHE (changed type) + Deleted: CLICON_XMLDB_PLUGIN, CLICON_USE_STARTUP_CONFIG"; + } + revision 2019-03-05{ + description + "Changed URN. Changed top-level symbol to clixon-config. + Released in Clixon 3.10"; + } + revision 2019-02-06 { + description + "Released in Clixon 3.9"; + } + revision 2018-10-21 { + description + "Released in Clixon 3.8"; + } + extension search_index { + description "This list argument acts as a search index using optimized binary search. + "; + } + typedef startup_mode{ + description + "Which method to boot/start clicon backend. + The methods differ in how they reach a running state + Which source database to commit from, if any."; + type enumeration{ + enum none{ + description + "Do not touch running state + Typically after crash when running state and db are synched"; + } + enum init{ + description + "Initialize running state. + Start with a completely clean running state"; + } + enum running{ + description + "Commit running db configuration into running state + After reboot if a persistent running db exists"; + } + enum startup{ + description + "Commit startup configuration into running state + After reboot when no persistent running db exists"; + } + } + } + typedef datastore_format{ + description + "Datastore format."; + type enumeration{ + enum xml{ + description "Save and load xmldb as XML"; + } + enum json{ + description "Save and load xmldb as JSON"; + } + } + } + typedef datastore_cache{ + description + "XML configuration, ie running/candididate/ datastore cache behaviour."; + type enumeration{ + enum nocache{ + description "No cache always work directly with file"; + } + enum cache{ + description "Use in-memory cache. + Make copies when accessing internally."; + } + enum cache-zerocopy{ + description "Use in-memory cache and dont copy. + Fastest but opens up for callbacks changing cache."; + } + } + } + typedef cli_genmodel_type{ + description + "How to generate CLI from YANG model, + eg list a{ key x; leaf x; leaf y;}"; + type enumeration{ + enum NONE{ + description "No extra keywords: a "; + } + enum VARS{ + description "Keywords on non-key variables: a y "; + } + enum ALL{ + description "Keywords on all variables: a x y "; + } + } + } + typedef nacm_mode{ + description + "Mode of RFC8341 Network Configuration Access Control Model. + It is unclear from the RFC whether NACM rules are internal + in a configuration (ie embedded in regular config) or external/OOB + in s separate, specific NACM-config"; + type enumeration{ + enum disabled{ + description "NACM is disabled"; + } + enum internal{ + description "NACM is enabled and available in the regular config"; + } + enum external{ + description "NACM is enabled and available in a separate config"; + } + } + } + typedef regexp_mode{ + description + "The regular expression engine Clixon uses in its validation of + Yang patterns, and in the CLI. + Yang RFC 7950 stipulates XSD XML Schema regexps + according to W3 CXML Schema Part 2: Datatypes Second Edition, + see http://www.w3.org/TR/2004/REC-xmlschema-2-20041028#regexs"; + type enumeration{ + enum posix { + description + "Translate XSD XML Schema regexp:s to Posix regexp. This is + not a complete translation, but can be considered good-enough + for Yang use-cases as defined by openconfig and yang-models + for example."; + } + enum libxml2 { + description + "Use libxml2 XSD XML Schema regexp engine. This is a complete + XSD regexp engine.. + Requires libxml2 to be available at configure time + (HAVE_LIBXML2 should be set)"; + } + } + } + typedef priv_mode{ + description + "Privilege mode, used for dropping (or not) priveleges to a non-provileged + user after initialization"; + type enumeration{ + enum none { + description + "Make no drop/change in privileges."; + } + enum drop_perm { + description + "After initialization, drop privileges permanently to a uid"; + } + enum drop_temp { + description + "After initialization, drop privileges temporarily to a euid"; + } + } + } + typedef nacm_cred_mode{ + description + "How NACM user should be matched with unix socket peer credentials. + This means nacm user must match socket peer user accessing the + backend socket. For IP sockets only mode none makes sense."; + type enumeration{ + enum none { + description + "Dont match NACM user to any user credentials. Any user can pose + as any other user. Set this for IP sockets, or dont use NACM."; + } + enum exact { + description + "Exact match between NACM user and unix socket peer user. + Except for root user that can pose as any user."; + } + enum except { + description + "Exact match between NACM user and unix socket peer user, except + for root and www user (restconf)."; + } + } + } + + container clixon-config { + leaf-list CLICON_FEATURE { + description + "Supported features as used by YANG feature/if-feature + value is: :, where and + are either names, or the special character '*'. + *:* means enable all features + :* means enable all features in the specified module + *: means enable the specific feature in all modules"; + type string; + } + leaf CLICON_CONFIGFILE{ + type string; + description + "Location of configuration-file for default values (this file). + Default is CLIXON_DEFAULT_CONFIG=/usr/local/etc/clicon.xml + set in configure. Note that due to bootstrapping, a default + value here does not work."; + } + leaf-list CLICON_YANG_DIR { + ordered-by user; + type string; + description + "Yang directory path for finding module and submodule files. + A list of these options should be in the configuration. + When loading a Yang module, Clixon searches this list in the order + they appear. Ensure that YANG_INSTALLDIR(default + /usr/local/share/clixon) is present in the path"; + } + leaf CLICON_YANG_MAIN_FILE { + type string; + description + "If specified load a yang module in a specific absolute filename. + This corresponds to the -y command-line option in most CLixon + programs."; + } + leaf CLICON_YANG_MAIN_DIR { + type string; + description + "If given, load all modules in this directory (all .yang files) + See also CLICON_YANG_DIR which specifies a path of dirs"; + } + leaf CLICON_YANG_MODULE_MAIN { + type string; + description + "Option used to construct initial yang file: + [@]"; + } + leaf CLICON_YANG_MODULE_REVISION { + type string; + description + "Option used to construct initial yang file: + [@]. + Used together with CLICON_YANG_MODULE_MAIN"; + } + leaf CLICON_YANG_REGEXP { + type regexp_mode; + default posix; + description + "The regular expression engine Clixon uses in its validation of + Yang patterns, and in the CLI. + There is a 'good-enough' posix translation mode and a complete + libxml2 mode"; + } + leaf CLICON_BACKEND_DIR { + type string; + description + "Location of backend .so plugins. Load all .so + plugins in this dir as backend plugins"; + } + leaf CLICON_BACKEND_REGEXP { + type string; + description + "Regexp of matching backend plugins in CLICON_BACKEND_DIR"; + default "(.so)$"; + } + leaf CLICON_NETCONF_DIR { + type string; + description "Location of netconf (frontend) .so plugins"; + } + leaf CLICON_RESTCONF_DIR { + type string; + description + "Location of restconf (frontend) .so plugins. Load all .so + plugins in this dir as restconf code plugins"; + } + leaf CLICON_RESTCONF_PATH { + type string; + default "/www-data/fastcgi_restconf.sock"; + description + "FastCGI unix socket. Should be specified in webserver + Eg in nginx: fastcgi_pass unix:/www-data/clicon_restconf.sock"; + } + leaf CLICON_RESTCONF_PRETTY { + type boolean; + default true; + description + "Restconf return value pretty print. + Restconf clients may add HTTP header: + Accept: application/yang-data+json, or + Accept: application/yang-data+xml + to get return value in XML or JSON. + RFC 8040 examples print XML and JSON in pretty-printed form. + Setting this value to false makes restconf return not pretty-printed + which may be desirable for performance or tests"; + } + leaf CLICON_CLI_DIR { + type string; + description + "Directory containing frontend cli loadable plugins. Load all .so + plugins in this directory as CLI object plugins"; + } + leaf CLICON_CLISPEC_DIR { + type string; + description + "Directory containing frontend cligen spec files. Load all .cli + files in this directory as CLI specification files. + See also CLICON_CLISPEC_FILE."; + } + leaf CLICON_CLISPEC_FILE { + type string; + description + "Specific frontend cligen spec file as aletrnative or complement + to CLICON_CLISPEC_DIR. Also available as -c in clixon_cli."; + } + leaf CLICON_CLI_MODE { + type string; + default "base"; + description + "Startup CLI mode. This should match a CLICON_MODE variable set in + one of the clispec files"; + } + leaf CLICON_CLI_GENMODEL { + type int32; + default 1; + description + "If set, generate CLI specification for CLI completion of + loaded Yang modules. This CLI tree can be accessed in CLI + spec files using the tree reference syntax (eg @datamodel). + See also CLICON_CLI_MODEL_TREENAME. + (consider boolean)"; + } + leaf CLICON_CLI_MODEL_TREENAME { + type string; + default "datamodel"; + description + "If set, CLI specs can reference the + model syntax using this reference. + Example: set @datamodel, cli_set();"; + } + leaf CLICON_CLI_GENMODEL_COMPLETION { + type int32; + default 1; + description "Generate code for CLI completion of existing db symbols. + (consider boolean)"; + } + leaf CLICON_CLI_GENMODEL_TYPE { + type cli_genmodel_type; + default "VARS"; + description "How to generate and show CLI syntax: VARS|ALL"; + } + leaf CLICON_CLI_VARONLY { + type int32; + default 1; + description + "Dont include keys in cvec in cli vars callbacks, + ie a & k in 'a k ' ignored + (consider boolean)"; + } + leaf CLICON_CLI_LINESCROLLING { + type int32; + default 1; + description + "Set to 0 if you want CLI to wrap to next line. + Set to 1 if you want CLI to scroll sideways when approaching + right margin"; + } + leaf CLICON_CLI_TAB_MODE { + type int8; + default 0; + description + "Set CLI tab mode. This is actually a bitfield of three + combinations: + bit 1: 0: shows short info of available commands + 1: has same output as , ie line per command + bit 2: 0: On , select a command over a if both exist + 1: Commands and vars have same preference. + bit 3: 0: On , never complete more than one level per + 1: Complete all levels at once if possible. + "; + } + leaf CLICON_CLI_UTF8 { + type int8; + default 0; + description + "Set to 1 to enable CLIgen UTF-8 experimental mode. + Note that this feature is EXPERIMENTAL and may not properly handle + scrolling, control characters, etc + (consider boolean)"; + } + leaf CLICON_CLI_HIST_FILE { + type string; + default "~/.clixon_cli_history"; + description + "Name of CLI history file. If not given, history is not saved. + The number of lines is saved is given by CLICON_CLI_HIST_SIZE."; + } + leaf CLICON_CLI_HIST_SIZE { + type int32; + default 300; + description + "Number of lines to save in CLI history. + Also, if CLICON_CLI_HIST_FILE is set, also the size in lines + of the saved history."; + } + leaf CLICON_SOCK_FAMILY { + type string; + default "UNIX"; + description + "Address family for communicating with clixon_backend + (UNIX|IPv4). IPv6 not yet implemented. + Note that UNIX socket makes credential check as follows: + (1) client needs rw access to the socket + (2) NACM credentials can be checked according to CLICON_NACM_CREDENTIALS + Warning: IPv4 and IPv6 sockets have no credential mechanism. + "; + } + leaf CLICON_SOCK { + type string; + mandatory true; + description + "If family above is AF_UNIX: Unix socket for communicating + with clixon_backend. If family is AF_INET: IPv4 address"; + } + leaf CLICON_SOCK_PORT { + type int32; + default 4535; + description + "Inet socket port for communicating with clixon_backend + (only IPv4|IPv6)"; + } + leaf CLICON_SOCK_GROUP { + type string; + default "clicon"; + description + "Group membership to access clixon_backend unix socket and gid for + deamon"; + } + leaf CLICON_BACKEND_USER { + type string; + description + "User name for backend (both foreground and daemonized). + If you set this value the backend if started as root will lower + the privileges after initialization. + The ownership of files created by the backend will also be set to this + user (eg datastores). + It also sets the backend unix socket owner to this user, but its group + is set by CLICON_SOCK_GROUP. + See also CLICON_PRIVILEGES setting"; + } + leaf CLICON_BACKEND_PRIVILEGES { + type priv_mode; + default none; + description + "Backend privileges mode. + If CLICON_BACKEND_USER user is set, mode can be set to drop_perm or + drop_temp."; + } + leaf CLICON_BACKEND_PIDFILE { + type string; + mandatory true; + description "Process-id file of backend daemon"; + } + leaf CLICON_AUTOCOMMIT { + type int32; + default 0; + description + "Set if all configuration changes are committed automatically + on every edit change. Explicit commit commands unnecessary + (consider boolean)"; + } + leaf CLICON_XMLDB_DIR { + type string; + mandatory true; + description + "Directory where \"running\", \"candidate\" and \"startup\" are placed."; + } + leaf CLICON_DATASTORE_CACHE { + type datastore_cache; + default cache; + description + "Clixon datastore cache behaviour. There are three values: no cache, + cache with copy, or cache without copy."; + } + leaf CLICON_XMLDB_FORMAT { + type datastore_format; + default xml; + description "XMLDB datastore format."; + } + leaf CLICON_XMLDB_PRETTY { + type boolean; + default true; + description + "XMLDB datastore pretty print. + If set, insert spaces and line-feeds making the XML/JSON human + readable. If not set, make the XML/JSON more compact."; + } + leaf CLICON_XMLDB_MODSTATE { + type boolean; + default false; + description + "If set, tag datastores with RFC 7895 YANG Module Library + info. When loaded at startup, a check is made if the system + yang modules match"; + } + leaf CLICON_XML_CHANGELOG { + type boolean; + default false; + description "If true enable automatic upgrade using yang clixon + changelog."; + } + leaf CLICON_XML_CHANGELOG_FILE { + type string; + description "Name of file with module revision changelog. + If CLICON_XML_CHANGELOG is true, Clixon + reads the module changelog from this file."; + } + leaf CLICON_STARTUP_MODE { + type startup_mode; + description "Which method to boot/start clicon backend"; + } + leaf CLICON_TRANSACTION_MOD { + type boolean; + default false; + description "If set, modifications in validation and commit + callbacks are written back into the datastore"; + } + leaf CLICON_NACM_MODE { + type nacm_mode; + default disabled; + description "RFC8341 network access configuration control model + (NACM) mode: disabled, in regular (internal) config + or separate external file given by CLICON_NACM_FILE"; + } + leaf CLICON_NACM_FILE { + type string; + description "RFC8341 NACM external configuration file"; + } + leaf CLICON_NACM_CREDENTIALS { + type nacm_cred_mode; + default except; + description + "Verify nacm user credentials with unix socket peer cred. + This means nacm user must match unix user accessing the backend + socket. + Except for recovery user and www user (for restconf)"; + } + leaf CLICON_NACM_RECOVERY_USER { + type string; + default "_nacm_recovery"; + description + "RFC8341 defines a 'recovery session' as outside the scope. Clixon + defines this user as having special admin rights to exempt from + all access control enforcements. + Note setting of CLICON_NACM_CREDENTIALS is important, if set to + exact for example, this user must exist and be used, otherwise + another user (such as root or www) can pose as it."; + } + leaf CLICON_MODULE_LIBRARY_RFC7895 { + type boolean; + default true; + description "Enable RFC 7895 YANG Module library support as state + data. If enabled, module info will appear when doing + netconf get or restconf GET"; + } + leaf CLICON_MODULE_SET_ID { + type string; + default "0"; + description "If RFC 7895 YANG Module library enabled: + Contains a server-specific identifier representing + the current set of modules and submodules. The + server MUST change the value of this leaf if the + information represented by the 'module' list instances + has changed."; + } + leaf CLICON_STREAM_DISCOVERY_RFC5277 { + type boolean; + default false; + description "Enable event stream discovery as described in RFC 5277 + sections 3.2. If enabled, available streams will appear + when doing netconf get or restconf GET"; + } + leaf CLICON_STREAM_DISCOVERY_RFC8040 { + type boolean; + default false; + description + "Enable monitoring information for the RESTCONF protocol from RFC 8040"; + } + leaf CLICON_STREAM_PATH { + type string; + default "streams"; + description "Stream path appended to CLICON_STREAM_URL to form + stream subscription URL."; + } + leaf CLICON_STREAM_URL { + type string; + default "https://localhost"; + description "Prepend this to CLICON_STREAM_PATH to form URL. + See RFC 8040 Sec 9.3 location leaf: + 'Contains a URL that represents the entry point for + establishing notification delivery via server-sent events.' + Prepend this constant to name of stream. + Example: https://localhost/streams/NETCONF. Note this is the + external URL, not local behind a reverse-proxy. + Note that -s command-line option to clixon_restconf + should correspond to last path of url (eg 'streams')"; + } + leaf CLICON_STREAM_PUB { + type string; + description "For stream publish using eg nchan, the base address + to publish to. Example value: http://localhost/pub + Example: stream NETCONF would then be pushed to + http://localhost/pub/NETCONF. + Note this may be a local/provate URL behind reverse-proxy. + If not given, do NOT enable stream publishing using NCHAN."; + } + leaf CLICON_STREAM_RETENTION { + type uint32; + default 3600; + units s; + description "Retention for stream replay buffers in seconds, ie how much + data to store before dropping. 0 means no retention"; + + } + + } +}