manuals/developer-guide/src/main/asciidoc/controller/config-logback.adoc

   1 // FIXME: Probably deprecated
   2 // https://wiki.opendaylight.org/view/OpenDaylight_Controller:Config:Examples:Logback#Logback_configuration:_Netconf
   3 === OpenDaylight Controller Configuration: Logback Examples
   4 ==== Logback Configuration Example
   5
   6 The Logback logger configuration is part of the config subsystem. This module allows changes to the Logback configuration at runtime. It is used here as an example to demonstrate the YANG to Java code generator and to show how the configuration transaction works.
   7
   8 ==== Java code generation
   9 The logging configuration YANG module definition can be found in the config-logging.yang file. The code is generated by the yang-maven-plugin and yang-jmx-generator-plugin. The output java files are located as defined in the plugin configuration, where additional configuration parameters can be set. The logback module is defined as identity, with the base "config:module-type"; it does not provide or depend on any service interface.
  10 ----
  11 identity logback {
  12     description
  13         "Actual state of logback configuration.";
  14     base config:module-type;
  15     config:java-name-prefix Logback;
  16 }
  17 ----
  18 The next logback module attributes are defined in the "/config:modules/config:module/config:configuration" augment as the snippet below shows.
  19 ----
  20 augment "/config:modules/config:module/config:configuration" {
  21     case logback {
  22         when "/config:modules/config:module/config:type = 'logback'";
  23
  24         list console-appenders {
  25
  26             leaf encoder-pattern {
  27                 type string;
  28                 mandatory true;
  29             }
  30
  31             leaf threshold-filter {
  32                 type string;
  33                 default 'ALL';
  34             }
  35
  36             leaf name {
  37                 type string;;
  38                 mandatory true;
  39             }
  40             config:java-name-prefix ConsoleAppenderTO;
  41         }
  42          ...
  43 ----
  44 Now LogbackModule and LogbackModuleFactory can be generated. In fact, three more java files related to this module will be generated. By the augment definition, TypeObjects too are generated (that is to say, ConsoleAppenderTO). They are regular java classes with getters and setters for arguments defined as leaves.
  45
  46 * *LogbackModuleMXBean* is the interface containing getters and setters for attributes defined in the configuration augment.
  47 * *AbstractLogbackModule* is the abstract java class, which implements Module, RuntimeBeanRegistratorAwareModule, and LogbackModuleMXBean. It contains almost all functionality, except validate and createInstance methods.
  48 * *AbstractLogbackModuleFactory* is the abstract java class responsible for creating module instances. It implements the ModuleFactory interface.
  49 * *LogbackModule* class extends AbstractLogbackModule. It is located in a different place (source/main/java) and can be modified by the user, so that the abstract method is implemented and the validate method is overridden.
  50 * *LogbackModuleFactory* class extends AbstractLogbackModuleFactory and overrides its instantiateModule methods.
  51 Next, the runtime bean is defined in the "/config:modules/config:module/config:state" augment. +
  52 ----
  53 augment "/config:modules/config:module/config:state" {
  54     case logback {
  55         when "/config:modules/config:module/config:type = 'logback'";
  56
  57         rpcx:rpc-context-instance "logback-rpc";
  58
  59         list status {
  60             config:java-name-prefix StatusTO;
  61
  62             leaf level {
  63                 type string;
  64             }
  65
  66             leaf message {
  67                 type string;
  68             }
  69
  70             leaf date {
  71                 type uint32;
  72             }
  73         }
  74     }
  75 }
  76 ----
  77 * The *Generator* plugin creates another set of java files.
  78 * *LogbackRuntimeMXBean* is the interface extending RuntimeBean. It contains the getter method for the argument defined in the augment.
  79 * *LogbackRuntimeRegistrator* class serves as the registrator for runtime beans.
  80 * *LogbackRuntimeRegistration* class serves as the registration ticket. An instance is returned after registration.
  81
  82 The Logback config also defines logback-rpc with the reset method. It is also defined in the state augment, owing to the context.
  83 ----
  84 identity logback-rpc;
  85 rpc reset {
  86     input {
  87         uses rpcx:rpc-context-ref {
  88             refine context-instance {
  89                 rpcx:rpc-context-instance logback-rpc;
  90             }
  91         }
  92     }
  93 }
  94 ----
  95 The Reset method is defined in the LogbackRuntimeMXBean interface.
  96
  97 ==== Logback configuration: Jolokia
  98
  99 To create configuration on the running OSGi server: Jolokia (http://www.jolokia.org/) is used as a JMX-HTTP bridge, which listens at http://localhost:8080/controller/nb/v2/jolokia and curl to request over HTTP.
 100
 101 . Start the controller. Find more here: https://wiki.opendaylight.org/view/OpenDaylight_Controller:Pulling,_Hacking,_and_Pushing_the_Code_from_the_CLI
 102 . Request Jolokia:
 103 ----
 104 curl http://localhost:8080/controller/nb/v2/jolokia --user admin:admin
 105 ----
 106 The response must resemble the following: +
 107 ----
 108 {
 109     "timestamp": 1382425537,
 110     "status": 200,
 111     "request": {
 112         "type": "version"
 113     },
 114     "value": {
 115         "protocol": "7.0",
 116         "agent": "1.1.1",
 117         "info": {
 118             "product": "equinox",
 119             "vendor": "Eclipse",
 120             "version": "3.8.1.v20120830-144521"
 121         }
 122     }
 123 }
 124 ----
 125 Jolokia is working.
 126 To configure Logback, first, create a configuration transaction. ConfigResgistryModule offers the operation beginConfig(), and to invoke it:
 127 ----
 128 curl -X POST -H "Content-Type: application/json" -d '{"type":"exec","mbean":"org.opendaylight.controller:type=ConfigRegistry","arguments":[],"operation":"beginConfig"}' http://localhost:8080/controller/nb/v2/jolokia --user admin:admin
 129 ----
 130 The configuration transaction was created. The response received: +
 131 ----
 132 {
 133     "timestamp": 1383034210,
 134     "status": 200,
 135     "request": {
 136         "operation": "beginConfig",
 137         "mbean": "org.opendaylight.controller:type=ConfigRegistry",
 138         "type": "exec"
 139     },
 140     "value": {
 141         "objectName": "org.opendaylight.controller:TransactionName=ConfigTransaction-1-2,type=ConfigTransaction"
 142     }
 143 }
 144 ----
 145 At this stage, the transaction can be aborted, but we want to create the module bean to be configured. In the created ConfigTransaction call createModule method, the module identifier is logback, and the name must be singleton as only one instance of the Logback configuration is needed.
 146 ----
 147 curl -X POST -H "Content-Type: application/json" -d '{"type":"exec","mbean":"org.opendaylight.controller:TransactionName=ConfigTransaction-1-2,type=ConfigTransaction","arguments":["logback","singleton"],"operation":"createModule"}' http://localhost:8080/controller/nb/v2/jolokia --user admin:admin
 148 ----
 149 The LogbackModule bean was created. The response returned:
 150 ----
 151 {
 152     "timestamp": 1383034580,
 153     "status": 200,
 154     "request": {
 155         "operation": "createModule",
 156         "mbean": "org.opendaylight.controller:TransactionName=ConfigTransaction-1-2,type=ConfigTransaction",
 157         "arguments": [
 158             "logback",
 159             "singleton"
 160         ],
 161         "type": "exec"
 162     },
 163     "value": {
 164         "objectName": "org.opendaylight.controller:TransactionName=ConfigTransaction-1-2,instanceName=singleton,moduleFactoryName=logback,type=Module"
 165     }
 166 }
 167 ----
 168 * The configuration bean attributes are set to values obtained from the loggers configuration, with which the server was started. To see attributes, request:
 169 ----
 170 curl -X POST -H "Content-Type: application/json" -d '{"type":"read", "mbean":"org.opendaylight.controller:instanceName=singleton,TransactionName=ConfigTransaction-1-2,type=Module,moduleFactoryName=logback"}' http://localhost:8080/controller/nb/v2/jolokia --user admin:admin
 171 ----
 172 In the response body, the value contains all attributes (CompositeData) and its nested attribute values.
 173 * Now, the proposed configuration can be committed.
 174 ----
 175 curl -X POST -H "Content-Type: application/json" -d '{"type":"exec","mbean":"org.opendaylight.controller:type=ConfigRegistry","arguments":["org.opendaylight.controller:instanceName=singleton,TransactionName=ConfigTransaction-1-2,type=Module,moduleFactoryName=logback"],"operation":"commitConfig"}' http://localhost:8080/controller/nb/v2/jolokia --user admin:admin
 176 ----
 177 The configuration was successfully validated and committed, and the module instance created.
 178 ----
 179 {
 180     "timestamp": 1383034793,
 181     "status": 200,
 182     "request": {
 183         "operation": "commitConfig",
 184         "mbean": "org.opendaylight.controller:type=ConfigRegistry",
 185         "arguments": [
 186             "org.opendaylight.controller:instanceName=singleton,TransactionName=ConfigTransaction-1-2,type=Module,moduleFactoryName=logback"
 187         ],
 188         "type": "exec"
 189     },
 190     "value": {
 191         "newInstances": [
 192             {
 193                 "objectName": "org.opendaylight.controller:instanceName=singleton,moduleFactoryName=logback,type=Module"
 194             }
 195         ],
 196         "reusedInstances": [],
 197         "recreatedInstances": []
 198     }
 199 }
 200 ----
 201 * The runtime bean was registered, and can provide the status information of the configuration and rpc operation reset. To see the status, try requesting:
 202 ----
 203 curl -X POST -H "Content-Type: application/json" -d '{"type":"read","mbean":"org.opendaylight.controller:instanceName=singleton,type=RuntimeBean,moduleFactoryName=logback"}' http://localhost:8080/controller/nb/v2/jolokia --user admin:admin
 204 ----
 205 The entire logback status is in the response body.
 206
 207 * To invoke the rpc method reset:
 208 ----
 209 curl -X POST -H "Content-Type: application/json" -d '{"type":"exec",
 210 "mbean":"org.opendaylight.controller:instanceName=singleton,type=RuntimeBean,moduleFactoryName=logback",
 211 "operation":"reset","arguments":[]}' http://localhost:8080/controller/nb/v2/jolokia --user admin:admin
 212 ----
 213 The answer:
 214 ----
 215 {
 216     "timestamp": 1383035001,
 217     "status": 200,
 218     "request": {
 219         "operation": "reset",
 220         "mbean": "org.opendaylight.controller:instanceName=singleton,moduleFactoryName=logback,type=RuntimeBean",
 221         "type": "exec"
 222     },
 223     "value": null
 224 }
 225 ----
 226 Now, the runtime bean status attribute will be empty:
 227 ----
 228 {
 229     "timestamp": 1383035126,
 230     "status": 200,
 231     "request": {
 232         "mbean": "org.opendaylight.controller:instanceName=singleton,moduleFactoryName=logback,type=RuntimeBean",
 233         "type": "read"
 234     },
 235     "value": {
 236         "StatusTO": []
 237     }
 238 }
 239 ----
 240 ==== Logback configuration: NETCONF
 241
 242 In this case, NETCONF RPCs are used to configure logback. The Netconf server listens at port 8383. To communicate over TCP, telnet is used. More about NETCONF is available at: http://tools.ietf.org/html/rfc6241. Netconf implementation is a part of the Controller - netconf-subsystem. The RPCs of Netconf are XML, and the operations are mapped to JMX operations.
 243 * A server re-start is required. The procedure is the same as above.
 244 * Open a terminal and connect to the server:
 245 ----
 246 telnet localhost 8383
 247 ----
 248 A Hello message received from the server contains the server capabilities and session-id. To establish connection to the client,send a hello message:
 249 ----
 250 <hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 251     <capabilities>
 252         <capability>urn:ietf:params:netconf:base:1.0</capability>
 253     </capabilities>
 254 </hello>
 255 ]]>]]>
 256 ----
 257 * With the connection created, the client and server can communicate. To see the running modules and services, send an RPC to the server:
 258 ----
 259 <rpc id="a" a="64" xmlnx="a:b:c:d" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">
 260     <get-config>
 261         <source>
 262             <running/>
 263         </source>
 264     </get-config>
 265 </rpc>
 266 ]]>]]>
 267 ----
 268
 269 * To configure logback, create a configuration transaction, and create a configuration module. It can be done in one step (in client point of view):
 270 ----
 271 <rpc message-id="a" a="64" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 272     <edit-config>
 273         <target>
 274             <candidate/>
 275         </target>
 276         <default-operation>merge</default-operation>
 277         <config>
 278             <modules xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
 279                 <module>
 280                     <name>singleton</name>
 281                     <type xmlns:logging="urn:opendaylight:params:xml:ns:yang:controller:logback:config">
 282                         logging:logback
 283                     </type>
 284                 </module>
 285             </modules>
 286         </config>
 287     </edit-config>
 288 </rpc>
 289 ]]>]]>
 290 ----
 291
 292 If the configuration worked, the client receives a positive response:
 293
 294 ----
 295 <rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">
 296 <ok/>
 297 </rpc-reply>
 298 ]]>]]>
 299 ----
 300
 301 * The Logback configuration bean attributes contain values loaded from the running Logback configuration. Send a request to the server with an RPC:
 302 ----
 303 <rpc id="a" a="64" xmlnx="a:b:c:d" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">
 304     <get-config>
 305         <source>
 306             <candidate/>
 307         </source>
 308     </get-config>
 309 </rpc>
 310 ]]>]]>
 311 ----
 312
 313 * The reply includes the entire configuration that started the server. Assume that we want to change the RollingFileAppender named opendaylight.log attributes - maxFileSize, filename, and maxHistory. ( attribute of TimeBasedRollingPolicy). The proposed configuration:
 314
 315 ----
 316 <rpc message-id="a" a="64" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 317     <edit-config>
 318         <target>
 319             <candidate/>
 320         </target>
 321         <default-operation>merge</default-operation>
 322         <config>
 323             <modules xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
 324                 <module>
 325                     <name>singleton</name>
 326                     <type xmlns:logging="urn:opendaylight:params:xml:ns:yang:controller:logback:config">
 327                         logging:logback
 328                     </type>
 329                     <rolling-appenders xmlns="urn:opendaylight:params:xml:ns:yang:controller:logback:config">
 330                         <append>true</append>
 331                         <max-file-size>5MB</max-file-size>
 332                         <file-name>logs/opendaylight-new.log</file-name>
 333                         <name>opendaylight.log</name>
 334                         <file-name-pattern>logs/opendaylight.%d.log.zip</file-name-pattern>
 335                         <encoder-pattern>%date{"yyyy-MM-dd HH:mm:ss.SSS z"} [%thread] %-5level %logger{35} - %msg%n</encoder-pattern>
 336                         <clean-history-on-start>false</clean-history-on-start>
 337                         <max-history>7</max-history>
 338                         <rolling-policy-type>TimeBasedRollingPolicy</rolling-policy-type>
 339                     </rolling-appenders>
 340                 </module>
 341             </modules>
 342         </config>
 343     </edit-config>
 344 </rpc>
 345 ]]>]]>
 346 ----
 347 This configuration is merged with the proposed module configuration. If it passes the validation process successfully, an "ok" reply is received.
 348
 349 * The configuration bean is ready to be committed:
 350 ----
 351 <rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">
 352     <commit></commit>
 353 </rpc>
 354 ]]>]]>
 355 ----
 356 If successful, the ok message is received obtained, and the logback configuration is set. To verify, look into the logs directory to find a new log file named opendaylight-new.log
 357
 358 * Correctly close the session with the session-id:
 359 ----
 360 <rpc message-id="2" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 361     <close-session xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"/>
 362 </rpc>
 363 ]]>]]>
 364 ----