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

   1 // https://wiki.opendaylight.org/view/OpenDaylight_Controller:Config:Examples:User_guide
   2 // FIXME: This should be updated and probably part of user / operations guide
   3 === Configuration examples user guide
   4 ==== Configuring thread pools with yangcli-pro
   5 Requirements: yangcli-pro version 13.04-9.2 or later +
   6
   7 ===== Connecting to plaintext TCP socket and ssh
   8 Currently SSH is exposed by the controller. The network interface and port are configured in configuration/config.ini . The current configuration of netconf is as follows: +
   9 ----
  10 # Netconf startup configuration
  11 #netconf.tcp.address=127.0.0.l
  12 #netconf.tcp.port=8383
  13
  14 netconf.ssh.address=0.0.0.0
  15 netconf.ssh.port=1830
  16 ----
  17 To connect the yangcli-pro client, use the following syntax: +
  18 ----
  19 yangcli-pro --user=admin --password=admin --transport=ssh --ncport=1830 --server=localhost
  20 ----
  21 If the plaintext TCP port is not commented out, one can use the following: +
  22 ----
  23 yangcli-pro --user=a --password=a --transport=tcp --ncport=8383 --server=localhost
  24 ----
  25 Authentication in this case is ignored.
  26
  27 For better debugging, include following arguments: +
  28 ----
  29 --log=/tmp/yuma.log --log-level=debug4 --log-console
  30 ----
  31
  32 NOTE:  When the log file is set, the output will not appear on stdout.
  33
  34 ===== Configuring threadfactory
  35 The threadfactory is a service interface that can be plugged into threadpools, defined in config-threadpool-api (see the https://git.opendaylight.org/gerrit/gitweb?p=controller.git;a=blob;f=opendaylight/config/threadpool-config-api/src/main/yang/threadpool.yang;h=8f3064822be319dfee6fd7c7061c8bee14db268f;hb=refs/heads/master[yang file].
  36 The implementation to be used is called threadfactory-naming. This implementation will set a name for each thread created using a configurable prefix and auto incremented index. See the https://git.opendaylight.org/gerrit/gitweb?p=controller.git;a=blob;f=opendaylight/config/threadpool-config-impl/src/main/yang/threadpool-impl.yang;h=a2366f285a0c0b8682b1093f18fb5ee184c9cde3;hb=refs/heads/master[Yang file].
  37
  38 . Launch yangcli-pro and connect to the server.
  39 . Enter *get-config source=running* to see the current configuration. +
  40 Example output: +
  41 ----
  42 rpc-reply {
  43   data {
  44     modules {
  45       module  binding-broker-singleton {
  46         type binding-impl:binding-broker-impl-singleton
  47         name binding-broker-singleton
  48       }
  49     }
  50     services {
  51       service  md-sal-binding:binding-broker-osgi-registry {
  52         type md-sal-binding:binding-broker-osgi-registry
  53         instance  ref_binding-broker-singleton {
  54           name ref_binding-broker-singleton
  55           provider /modules/module[type='binding-broker-impl-singleton'][name='binding-broker-singleton']
  56         }
  57       }
  58     }
  59   }
  60 }
  61 ----
  62 [start=3]
  63 . Enter the merge /modules/module.
  64 . At the prompt, enter the string value for the leaf <name>. This is the name of the config module. Enter threadfactory-bgp.
  65 . Set the identityref for the leaf <type>. Press Tab to see a list of available module names. Enter threadfactory-naming.
  66 . At the prompt, choose the case statement. Example output:
  67 ----
  68  1: case netty-threadgroup-fixed:
  69        leaf thread-count
  70   2: case netty-hashed-wheel-timer:
  71        leaf tick-duration
  72        leaf ticks-per-wheel
  73        container thread-factory
  74   3: case async-eventbus:
  75        container threadpool
  76   4: case threadfactory-naming:
  77        leaf name-prefix
  78   5: case threadpool-fixed:
  79        leaf max-thread-count
  80        container threadFactory
  81   6: case threadpool-flexible:
  82        leaf max-thread-count
  83        leaf minThreadCount
  84        leaf keepAliveMillis
  85        container threadFactory
  86   7: case threadpool-scheduled:
  87        leaf max-thread-count
  88        container threadFactory
  89   8: case logback:
  90        list file-appenders
  91        list rolling-appenders
  92        list console-appenders
  93        list loggers
  94 ----
  95 In this case, we chose 4. +
  96 [start=7]
  97 . Next fill in the string value for the leaf <name-prefix>. Enter bgp.
  98 : (You should get an OK response from the server.)
  99 [start=8]
 100 . Optionally issue get-config source=candidate to verify the change.
 101 . Issue commit.
 102 . Issue get-config source=running. Example output: +
 103 ----
 104 rpc-reply {
 105   data {
 106     modules {
 107       module  binding-broker-singleton {
 108         type binding-impl:binding-broker-impl-singleton
 109         name binding-broker-singleton
 110       }
 111       module  threadfactory-bgp {
 112         type th-java:threadfactory-naming
 113         name threadfactory-bgp
 114         name-prefix bgp
 115       }
 116     }
 117     services {
 118       service  th:threadfactory {
 119         type th:threadfactory
 120         instance  ref_threadfactory-bgp {
 121           name ref_threadfactory-bgp
 122           provider /modules/module[type='threadfactory-naming'][name='threadfactory-bgp']
 123         }
 124       }
 125       service  md-sal-binding:binding-broker-osgi-registry {
 126         type md-sal-binding:binding-broker-osgi-registry
 127         instance  ref_binding-broker-singleton {
 128           name ref_binding-broker-singleton
 129           provider /modules/module[type='binding-broker-impl-singleton'][name='binding-broker-singleton']
 130         }
 131       }
 132     }
 133   }
 134 }
 135 ----
 136 ==== Configuring fixed threadpool
 137
 138 Service interface threadpool is defined in the config-threadpool-api. The implementation used is called threadpool-fixed that is defined in config-threadpool-impl. This implementation creates a threadpool of fixed size. There are two mandatory attributes: size and dependency on a threadfactory.
 139
 140 . Issue get-config source=running. As you can see in the last step of configuring threadfactory, /services/service, the node associated with it has instance name ref_threadfactory-bgp.
 141 . Issue merge /modules/module.
 142 . Enter the name bgp-threadpool.
 143 . Enter the type threadpool.
 144 . Select the appropriate case statement.
 145 . Enter the value for leaf <max-thread-count>: 100.
 146 . Enter the threadfactory for attribute threadfactory/type. This is with reference to /services/service/type, in other words, the service interface.
 147 . Enter ref_threadfactory-bgp.
 148 Server response must be an OK message.
 149 [start=9]
 150 . Issue commit.
 151 . Issue get-config source=running.
 152 Example output: +
 153 ----
 154 rpc-reply {
 155   data {
 156     modules {
 157       module  binding-broker-singleton {
 158         type binding-impl:binding-broker-impl-singleton
 159         name binding-broker-singleton
 160       }
 161       module  bgp-threadpool {
 162         type th-java:threadpool-fixed
 163         name bgp-threadpool
 164         threadFactory {
 165           type th:threadfactory
 166           name ref_threadfactory-bgp
 167         }
 168         max-thread-count 100
 169       }
 170       module  threadfactory-bgp {
 171         type th-java:threadfactory-naming
 172         name threadfactory-bgp
 173         name-prefix bgp
 174       }
 175     }
 176     services {
 177       service  th:threadpool {
 178         type th:threadpool
 179         instance  ref_bgp-threadpool {
 180           name ref_bgp-threadpool
 181           provider /modules/module[type='threadpool-fixed'][name='bgp-threadpool']
 182         }
 183       }
 184       service  th:threadfactory {
 185         type th:threadfactory
 186         instance  ref_threadfactory-bgp {
 187           name ref_threadfactory-bgp
 188           provider /modules/module[type='threadfactory-naming'][name='threadfactory-bgp']
 189         }
 190       }
 191       service  md-sal-binding:binding-broker-osgi-registry {
 192         type md-sal-binding:binding-broker-osgi-registry
 193         instance  ref_binding-broker-singleton {
 194           name ref_binding-broker-singleton
 195           provider /modules/module[type='binding-broker-impl-singleton'][name='binding-broker-singleton']
 196         }
 197       }
 198     }
 199   }
 200 }
 201 ----
 202 To see the actual netconf messages, use the logging arguments described at the top of this page. To validate that a threadpool has been created, a tool like VisualVM can be used.
 203
 204 ==== Logback configuration - Yuma
 205 This approach to configure logback will utilize a 3rd party cli netconf client from Yuma. We will modify existing console appender in logback and then call reset rpc on logback to clear its status list.
 206
 207 For initial configuration of the controller and startup parameters for yuma, see the threadpool example: https://wiki.opendaylight.org/view/OpenDaylight_Controller:Config:Examples:Threadpool[Threadpool configuration using Yuma].
 208
 209 Start the controller and yuma cli client as in the previous example.
 210
 211 There is no need to initialize the configuration module wrapping logback manually, since it creates a default instance. Therefore you should see the output containing logback configuration after the execution of get-config source=running command in yuma:
 212 ----
 213 rpc-reply {
 214   data {
 215     modules {
 216       module  singleton {
 217         type logging:logback
 218         name singleton
 219         console-appenders {
 220           threshold-filter ERROR
 221           name STDOUT
 222           encoder-pattern '%date{"yyyy-MM-dd HH:mm:ss.SSS z"} [%thread] %-5level %logger{36} - %msg%n'
 223         }
 224         file-appenders {
 225           append true
 226           file-name logs/audit.log
 227           name audit-file
 228           encoder-pattern '%date{"yyyy-MM-dd HH:mm:ss.SSS z"} %msg %n'
 229         }
 230         loggers {
 231           level WARN
 232           logger-name org.opendaylight.controller.logging.bridge
 233         }
 234         loggers {
 235           level INFO
 236           logger-name audit
 237           appenders audit-file
 238         }
 239         loggers {
 240           level ERROR
 241           logger-name ROOT
 242           appenders STDOUT
 243           appenders opendaylight.log
 244         }
 245         loggers {
 246           level INFO
 247           logger-name org.opendaylight
 248         }
 249         loggers {
 250           level WARN
 251           logger-name io.netty
 252         }
 253         rolling-appenders {
 254           append true
 255           max-file-size 10MB
 256           file-name logs/opendaylight.log
 257           name opendaylight.log
 258           file-name-pattern logs/opendaylight.%d.log.zip
 259           encoder-pattern '%date{"yyyy-MM-dd HH:mm:ss.SSS z"} [%thread] %-5level %logger{35} - %msg%n'
 260           clean-history-on-start false
 261           max-history 1
 262           rolling-policy-type TimeBasedRollingPolicy
 263         }
 264       }
 265       module  binding-broker-singleton {
 266         type binding-impl:binding-broker-impl-singleton
 267         name binding-broker-singleton
 268       }
 269     }
 270     services {
 271       service  md-sal-binding:binding-broker-osgi-registry {
 272         type md-sal-binding:binding-broker-osgi-registry
 273         instance  ref_binding-broker-singleton {
 274           name ref_binding-broker-singleton
 275           provider /modules/module[type='binding-broker-impl-singleton'][name='binding-broker-singleton']
 276         }
 277       }
 278     }
 279   }
 280 }
 281 ----
 282
 283 ===== Modifying existing console appender in logback
 284 . Start edit-config with merge option:
 285 ----
 286 merge /modules/module
 287 ----
 288 [start=2]
 289 . For Name of the module, enter *singleton*.
 290 . For Type, enter *logback*.
 291 . Pick the corresponding case statement with the name logback.
 292 We do not want to modify file-appenders, rolling-appenders and loggers lists, so the answer to questions from yuma is N (for no):
 293 ----
 294 Filling optional case /modules/module/configuration/logback:
 295 Add optional list 'file-appenders'?
 296 Enter Y for yes, N for no, or C to cancel: [default: Y]
 297 ----
 298 [start=5]
 299 . As we want to modify console-appenders, the answer to the question from Yuma is Y:
 300 ----
 301 Filling optional case /modules/module/configuration/logback:
 302 Add optional list 'console-appenders'?
 303 Enter Y for yes, N for no, or C to cancel: [default: Y]
 304 ----
 305 [start=6]
 306 . This will start a new configuration process for console appender and we will fill following values:
 307
 308 * <encoder-pattern> %date{"yyyy-MM-dd HH:mm:ss.SSS z"} %msg %n
 309 * <threshold-filter> INFO
 310 * <name> STDOUT
 311 [start=7]
 312 . Answer N to the next question.
 313 ----
 314 Add another list?
 315 Enter Y for yes, N for no, or C to cancel: [default: N]
 316 ----
 317 Notice that we changed the level for threshold-filter for STDOUT console appender from ERROR to INFO. Now issue a commit command to commit the changed configuration, and the response from get-config source=running command should look like this:
 318 ----
 319 rpc-reply {
 320   data {
 321     modules {
 322       module  singleton {
 323         type logging:logback
 324         name singleton
 325         console-appenders {
 326           threshold-filter INFO
 327           name STDOUT
 328           encoder-pattern '%date{"yyyy-MM-dd HH:mm:ss.SSS z"} [%thread] %-5level %logger{36} - %msg%n'
 329         }
 330         file-appenders {
 331           append true
 332           file-name logs/audit.log
 333           name audit-file
 334           encoder-pattern '%date{"yyyy-MM-dd HH:mm:ss.SSS z"} %msg %n'
 335         }
 336         loggers {
 337           level WARN
 338           logger-name org.opendaylight.controller.logging.bridge
 339         }
 340         loggers {
 341           level INFO
 342           logger-name audit
 343           appenders audit-file
 344         }
 345         loggers {
 346           level ERROR
 347           logger-name ROOT
 348           appenders STDOUT
 349           appenders opendaylight.log
 350         }
 351         loggers {
 352           level INFO
 353           logger-name org.opendaylight
 354         }
 355         loggers {
 356           level WARN
 357           logger-name io.netty
 358         }
 359         rolling-appenders {
 360           append true
 361           max-file-size 10MB
 362           file-name logs/opendaylight.log
 363           name opendaylight.log
 364           file-name-pattern logs/opendaylight.%d.log.zip
 365           encoder-pattern '%date{"yyyy-MM-dd HH:mm:ss.SSS z"} [%thread] %-5level %logger{35} - %msg%n'
 366           clean-history-on-start false
 367           max-history 1
 368           rolling-policy-type TimeBasedRollingPolicy
 369         }
 370       }
 371       module  binding-broker-singleton {
 372         type binding-impl:binding-broker-impl-singleton
 373         name binding-broker-singleton
 374       }
 375     }
 376     services {
 377       service  md-sal-binding:binding-broker-osgi-registry {
 378         type md-sal-binding:binding-broker-osgi-registry
 379         instance  ref_binding-broker-singleton {
 380           name ref_binding-broker-singleton
 381           provider /modules/module[type='binding-broker-impl-singleton'][name='binding-broker-singleton']
 382         }
 383       }
 384     }
 385   }
 386 }
 387 ----
 388 ==== Invoking RPCs
 389 *Invoking Reset RPC on logback* +
 390 The configuration module for logback exposes some information about its current state(list of logback status messages). This information can be accessed using get netconf operation or get command from yuma. Example response after issuing get command in yuma:
 391 ----
 392 rpc-reply {
 393   data {
 394     modules {
 395       module  singleton {
 396         type logging:logback
 397         name singleton
 398         status {
 399           message 'Found resource [configuration/logback.xml] at
 400 [file:/.../controller/opendaylight/distribution/opendaylight/target/distribution.opendaylight-
 401 osgipackage/opendaylight/configuration/logback.xml]'
 402           level INFO
 403           date 2479534352
 404         }
 405         status {
 406           message 'debug attribute not set'
 407           level INFO
 408           date 2479534441
 409         }
 410         status {
 411           message 'Will scan for changes in
 412 [[/.../controller/opendaylight/distribution/opendaylight/target/distribution.opendaylight-
 413 osgipackage/opendaylight/configuration/logback.xml]]
 414 every 60 seconds.'
 415           level INFO
 416           date 2479534448
 417         }
 418         status {
 419           message 'Adding ReconfigureOnChangeFilter as a turbo filter'
 420           level INFO
 421           date 2479534448
 422         }
 423  ...
 424 ----
 425 Logback also exposes an rpc called reset that wipes out the list of logback status messages and to invoke an rpc with name reset on module named singleton of type logback, following command needs to be issued in yuma:
 426 ----
 427 reset context-instance="/modules/module[type='logback' and name='singleton']"
 428 ----
 429 After an ok response, issuing get command should produce response with empty logback status message list:
 430 ----
 431 rpc-reply {
 432   data {
 433     modules {
 434       module  singleton {
 435         type logging:logback
 436         name singleton
 437       }
 438     }
 439   }
 440 }
 441 ----
 442 This response confirms successful execution of the reset rpc on logback.
 443
 444 *Invoking shutdown RPC* +
 445 This command entered in yuma will shut down the server. If all bundles do not stop correctly within 10 seconds, it will force the process to exit.
 446 ----
 447 shutdown context-instance="/modules/module[type='shutdown' and name='shutdown']",input-secret="",max-wait-time="10000",reason="reason"
 448 ----