The netconfd-pro server reports protocol operation errors using the <rpc-error> structure defined in RFC 6241
This data structure is used to report 1 error and contains the following fields (NOTE: customizable fields are highlighted):
- error-type: type of error (transport, rpc, protocol, application)
- error-tag: standard error reason tag
- error-severity: error or warning
- error-app-tag: configurable application error tag
- error-path: XPath expression identifying node that caused the error
- error-message: configurable human-readable error message
- error-info: container of standard and configurable extra error information
Setting the error-message Language
The language used for the error-message field can be set on the server using the --errmsg-lang CLI parameter.
The error messages in languages other than English must be pre-configured using the CLI parameters and YANG extensions described below.
The default error-message language is English ("en").
leaf errmsg-lang {
type string {
length "1 .. 7";
}
default "en";
description
"Specifies the language code for the error-message
language. This is only relevant if there are errmsg
parameters for multiple languages loaded in the program.
This value should use the ISO-639-1 code.
";
}The error-message field can be customized 3 different ways by the server:
- Standard YANG error-message statements
- Object-specific dynamic error messages
- Error number specific static error messages
1) Standard YANG Error Messages
The YANG error-message statement can be used inside the following statements, to create custom static error messages for a specific object.
- must-stmt: generated if must-stmt test fails (returns false)
- range-stmt: generated if a value is not in range
- length-stmt: generated if a string is the wrong length
- pattern-stmt: generated if a string does not match the pattern
Example:
container interface {
leaf ifType {
type enumeration {
enum ethernet;
enum atm;
}
}
leaf ifMTU {
type uint32;
}
must 'ifType != "ethernet" or ifMTU = 1500' {
error-message "An Ethernet MTU must be 1500";
}
must 'ifType != "atm" or'
+ ' (ifMTU <= 17966 and ifMTU >= 64)' {
error-message "An ATM MTU must be 64 .. 17966";
}
}2) Dynamic Object Specific Error Messages
Dynamic error messages can include parameters that are replaced at run-time with their current values, from the request message or the target configuration datastore.
The YumaWorks YANG extension "ywx:errmsg" is used to specify an error message for a YANG configuration data node object. This extension can be used either inline within the YANG module containing the object definition, or with an "annotation" file external to the source YANG module.
This extension has 4 sub-statements to specify parameters and filters for the errmsg statement.
- errmsg:
- errmsg-parm: Specify a dynamic error message parameter
- errmsg-tag: Specify an error-tag filter
- errmsg-apptag: Specify an error-app-tag filter
- errmsg-lang: Specify an error-message language filter
The ywx:errmsg Extension
extension errmsg {
description
"Used within a data node statement to define
a custom error-message filed within an 'rpc-error'
or 'error' structure for some or all error conditions.
The string format is restricted to plain text with
the exception of the 2 character sequence '%s'.
This special sequence will be replaced in the
dynamic error message generation if an errmsg-parm
statement is found to match the escape sequence.
If this extension statement has no sub-statements,
then it matches all errors for the object.
If 'errmsg-tag' sub-statements are found, then
this entry will match only those error-tag values.
If 'errmsg-apptag' sub-statements are found, then
this entry will match only those error-app-tag values.
The 'basestr' argument must be formatted string.
If any parameters are specified, then the corresponding
'errmsg-parm' extension statements must be encoded within
this errmsg statement.
Multiple errmsg statements can be present in the same
data node statement. They will be processed in order
and the first matching statement will be used to
generate the error-message value.
Example:
leaf my-network-id {
type int32;
ywx:errmsg 'Not a valid network ID for interface %s' {
ywx:errmsg-parm '../../if:name';
ywx:errmsg-apptag 'network-error';
}
}
";
argument basestr;
}The ywx:errmsg-parm Extension
extension errmsg-parm {
description
"Used within an errmsg statement to define
a parameter for expansion within the errmsg basestr.
There should be the correct number of expected parameters
for the corresponding 'basestr' format string.
The 'parmstr' argument must be an XPath path expression.
The context node will be the data node containing the
errmsg statement.
";
argument parmstr;
}The ywx:errmsg-tag Extension
extension errmsg-tag {
description
"Used within an errmsg statement to define an
error-tag value that will filter this errmsg.
Multiple errmsg-tag and/or errmsg-apptag values
form a conceptual OR expression.
The 'tagstr' argument must be the error-tag value
that will be matched.
";
argument tagstr;
}The ywx:errmsg-apptag Extension
extension errmsg-apptag {
description
"Used within an errmsg statement to define an
error-app-tag value that will filter this errmsg.
Multiple errmsg-tag and/or errmsg-apptag values
form a conceptual OR expression.
The 'apptagstr' argument must be the error-app-tag
value that will be matched.
";
argument apptagstr;
}The ywx:errmsg-lang Extension
extension errmsg-lang {
description
"Used within an errmsg statement to define the
language code value that will filter this errmsg.
Only one errmsg-lang statement may appear within
an errmsg statement. The 'langstr' value will
be compared to the 'errmsg-lang' CLI variable setting.
If the strings are the same, the entry is used.
If this statement is not present, then the errmsg entry
will be used regardless of the 'errmsg-lang' CLI variable
setting.
The 'langstr' argument must be the language code
value that will be matched.
";
argument langstr;
}Example using Inline YANG Module
leaf test3 {
type string;
ywx:errmsg "This is %s the %s operation-failed %s msg" {
ywx:errmsg-parm "../b";
ywx:errmsg-parm "../test1";
ywx:errmsg-parm ".";
ywx:errmsg-lang "en";
}
ywx:errmsg "C'est %s l'opération %s a échoué %s msg" {
ywx:errmsg-parm "../b";
ywx:errmsg-parm "../test1";
ywx:errmsg-parm ".";
ywx:errmsg-lang "fr";
}
}Example using an Annotation File
module errmsg-if {
namespace "http://netconfcentral.org/ns/errmsg-if";
prefix "em";
import yumaworks-extensions { prefix ywx; }
import ietf-interfaces { prefix if; }
revision 2018-04-12 {
description "Initial revision.";
}
deviation /if:interfaces/if:interface/if:type {
deviate add {
ywx:errmsg "This is the name %s and type %s of the interface" {
ywx:errmsg-parm "../name";
ywx:errmsg-parm ".";
ywx:errmsg-lang "en";
}
}
}
}3) Static Error Number Specific Error Messages
The server uses the internal data type status_t (found in status_enum.h) to define the error-number values used by the server.
There are built-in static error messages (found in status.c) for each error-number.
These error-numbers are defined in ranges:
- Errors: 1 to 999
- Warnings: 1000 to 1999
- Info: 2000 to 2999
The --errmsg CLI Parameter
The CLI parameter --errmsg is used to define a static error-message string.
This parameter can be used multiple times. Each instance specifies an error message for 1 error-number and 1 error language.
leaf-list errmsg {
type string;
description
"Specifies a replacement string for a specific error number.
Can specify error message for 1 specific language.
The 'num' component must match the <error-number>
found in status_enum.h. New error enums are always added
at the end of the list, so the numbers will not change.
The 'lang' component should use the ISO-639-1 code
Max length is 7 characters.
The string has the format: '<num>:<lang>:error string'
where:
<num> = error number to use for error message
<lang> = language code (en for English)
error string = error string text
Example:
Replace error 117 (ERR_WB_WRITE_FAILED) 'db write failed'
errmsg='117:en:The database could not be written'
";
}Examples
errmsg "14:en:internal read-write lock error" errmsg "14:fr:erreur interne de verrouillage de lecture-écriture" errmsg "14:de:interner Lese- / Schreibsperrfehler" errmsg "14:ru:внутренняя ошибка блокировки чтения и записи"
Procedure to Generate errmsg Parameters with Google Translate
The directory /usr/share/yumapro/util/errmsg-lang contains some sample errmsg configuration files for specific languages.
The python program /usr/share/yumapro/util/errmsg-tr.py can be used to generate these files. The output can be edited (or generated by hand if desired)
The config files in this directory contain error-message values for different languages. The Google Translate API is used to generate the error message strings. > sudo pip install googletrans Each configuration file contains the errmsg parameters for one language. The language codes are defined by ISO-639-1 The codes allowed by Google translate are listed here: https://cloud.google.com/translate/docs/languages The file naming convention is errmsg-<lang>.conf To create a new language-specific error-message file: 1) generate err.txt > yangdump-pro --lang-errors > err.txt At this point the err.txt file contains all the default English errmsg strings. This file can be edited to change the default strings, if desired. 2) run errmsg-tr.py (from netconf/util dir) > python errmsg-tr.py err.txt <lang> Example: Russian > python errmsg-tr.py err.txt ru (Will create file errmsg-ru.conf) Example: French > python errmsg-tr.py err.txt fr (Will create file errmsg-fr.conf)