// https://wiki.opendaylight.org/view/OpenDaylight_Controller:Config:Examples:User_guide
// FIXME: This should be updated and probably part of user / operations guide
=== Configuration examples user guide
==== Configuring thread pools with yangcli-pro
Requirements: yangcli-pro version 13.04-9.2 or later +

===== Connecting to plaintext TCP socket and ssh
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: +
----
# Netconf startup configuration
#netconf.tcp.address=127.0.0.l
#netconf.tcp.port=8383

netconf.ssh.address=0.0.0.0
netconf.ssh.port=1830
----
To connect the yangcli-pro client, use the following syntax: +
----
yangcli-pro --user=admin --password=admin --transport=ssh --ncport=1830 --server=localhost
----
If the plaintext TCP port is not commented out, one can use the following: +
----
yangcli-pro --user=a --password=a --transport=tcp --ncport=8383 --server=localhost
----
Authentication in this case is ignored.

For better debugging, include following arguments: +
----
--log=/tmp/yuma.log --log-level=debug4 --log-console
----

NOTE:  When the log file is set, the output will not appear on stdout.

===== Configuring threadfactory
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].
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].

. Launch yangcli-pro and connect to the server.
. Enter *get-config source=running* to see the current configuration. +
Example output: +
----
rpc-reply {
  data {
    modules {
      module  binding-broker-singleton {
        type binding-impl:binding-broker-impl-singleton
        name binding-broker-singleton
      }
    }
    services {
      service  md-sal-binding:binding-broker-osgi-registry {
        type md-sal-binding:binding-broker-osgi-registry
        instance  ref_binding-broker-singleton {
          name ref_binding-broker-singleton
          provider /modules/module[type='binding-broker-impl-singleton'][name='binding-broker-singleton']
        }
      }
    }
  }
}
----
[start=3]
. Enter the merge /modules/module.
. At the prompt, enter the string value for the leaf <name>. This is the name of the config module. Enter threadfactory-bgp.
. Set the identityref for the leaf <type>. Press Tab to see a list of available module names. Enter threadfactory-naming.
. At the prompt, choose the case statement. Example output:
----
 1: case netty-threadgroup-fixed:
       leaf thread-count
  2: case netty-hashed-wheel-timer:
       leaf tick-duration
       leaf ticks-per-wheel
       container thread-factory
  3: case async-eventbus:
       container threadpool
  4: case threadfactory-naming:
       leaf name-prefix
  5: case threadpool-fixed:
       leaf max-thread-count
       container threadFactory
  6: case threadpool-flexible:
       leaf max-thread-count
       leaf minThreadCount
       leaf keepAliveMillis
       container threadFactory
  7: case threadpool-scheduled:
       leaf max-thread-count
       container threadFactory
  8: case logback:
       list file-appenders
       list rolling-appenders
       list console-appenders
       list loggers
----
In this case, we chose 4. +
[start=7]
. Next fill in the string value for the leaf <name-prefix>. Enter bgp.
: (You should get an OK response from the server.)
[start=8]
. Optionally issue get-config source=candidate to verify the change.
. Issue commit.
. Issue get-config source=running. Example output: +
----
rpc-reply {
  data {
    modules {
      module  binding-broker-singleton {
        type binding-impl:binding-broker-impl-singleton
        name binding-broker-singleton
      }
      module  threadfactory-bgp {
        type th-java:threadfactory-naming
        name threadfactory-bgp
        name-prefix bgp
      }
    }
    services {
      service  th:threadfactory {
        type th:threadfactory
        instance  ref_threadfactory-bgp {
          name ref_threadfactory-bgp
          provider /modules/module[type='threadfactory-naming'][name='threadfactory-bgp']
        }
      }
      service  md-sal-binding:binding-broker-osgi-registry {
        type md-sal-binding:binding-broker-osgi-registry
        instance  ref_binding-broker-singleton {
          name ref_binding-broker-singleton
          provider /modules/module[type='binding-broker-impl-singleton'][name='binding-broker-singleton']
        }
      }
    }
  }
}
----
==== Configuring fixed threadpool

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.

. 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.
. Issue merge /modules/module.
. Enter the name bgp-threadpool.
. Enter the type threadpool.
. Select the appropriate case statement.
. Enter the value for leaf <max-thread-count>: 100.
. Enter the threadfactory for attribute threadfactory/type. This is with reference to /services/service/type, in other words, the service interface.
. Enter ref_threadfactory-bgp.
Server response must be an OK message.
[start=9]
. Issue commit.
. Issue get-config source=running.
Example output: +
----
rpc-reply {
  data {
    modules {
      module  binding-broker-singleton {
        type binding-impl:binding-broker-impl-singleton
        name binding-broker-singleton
      }
      module  bgp-threadpool {
        type th-java:threadpool-fixed
        name bgp-threadpool
        threadFactory {
          type th:threadfactory
          name ref_threadfactory-bgp
        }
        max-thread-count 100
      }
      module  threadfactory-bgp {
        type th-java:threadfactory-naming
        name threadfactory-bgp
        name-prefix bgp
      }
    }
    services {
      service  th:threadpool {
        type th:threadpool
        instance  ref_bgp-threadpool {
          name ref_bgp-threadpool
          provider /modules/module[type='threadpool-fixed'][name='bgp-threadpool']
        }
      }
      service  th:threadfactory {
        type th:threadfactory
        instance  ref_threadfactory-bgp {
          name ref_threadfactory-bgp
          provider /modules/module[type='threadfactory-naming'][name='threadfactory-bgp']
        }
      }
      service  md-sal-binding:binding-broker-osgi-registry {
        type md-sal-binding:binding-broker-osgi-registry
        instance  ref_binding-broker-singleton {
          name ref_binding-broker-singleton
          provider /modules/module[type='binding-broker-impl-singleton'][name='binding-broker-singleton']
        }
      }
    }
  }
}
----
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.

==== Logback configuration - Yuma
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.

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].

Start the controller and yuma cli client as in the previous example.

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:
----
rpc-reply {
  data {
    modules {
      module  singleton {
        type logging:logback
        name singleton
        console-appenders {
          threshold-filter ERROR
          name STDOUT
          encoder-pattern '%date{"yyyy-MM-dd HH:mm:ss.SSS z"} [%thread] %-5level %logger{36} - %msg%n'
        }
        file-appenders {
          append true
          file-name logs/audit.log
          name audit-file
          encoder-pattern '%date{"yyyy-MM-dd HH:mm:ss.SSS z"} %msg %n'
        }
        loggers {
          level WARN
          logger-name org.opendaylight.controller.logging.bridge
        }
        loggers {
          level INFO
          logger-name audit
          appenders audit-file
        }
        loggers {
          level ERROR
          logger-name ROOT
          appenders STDOUT
          appenders opendaylight.log
        }
        loggers {
          level INFO
          logger-name org.opendaylight
        }
        loggers {
          level WARN
          logger-name io.netty
        }
        rolling-appenders {
          append true
          max-file-size 10MB
          file-name logs/opendaylight.log
          name opendaylight.log
          file-name-pattern logs/opendaylight.%d.log.zip
          encoder-pattern '%date{"yyyy-MM-dd HH:mm:ss.SSS z"} [%thread] %-5level %logger{35} - %msg%n'
          clean-history-on-start false
          max-history 1
          rolling-policy-type TimeBasedRollingPolicy
        }
      }
      module  binding-broker-singleton {
        type binding-impl:binding-broker-impl-singleton
        name binding-broker-singleton
      }
    }
    services {
      service  md-sal-binding:binding-broker-osgi-registry {
        type md-sal-binding:binding-broker-osgi-registry
        instance  ref_binding-broker-singleton {
          name ref_binding-broker-singleton
          provider /modules/module[type='binding-broker-impl-singleton'][name='binding-broker-singleton']
        }
      }
    }
  }
}
----

===== Modifying existing console appender in logback
. Start edit-config with merge option:
----
merge /modules/module
----
[start=2]
. For Name of the module, enter *singleton*.
. For Type, enter *logback*.
. Pick the corresponding case statement with the name logback.
We do not want to modify file-appenders, rolling-appenders and loggers lists, so the answer to questions from yuma is N (for no):
----
Filling optional case /modules/module/configuration/logback:
Add optional list 'file-appenders'?
Enter Y for yes, N for no, or C to cancel: [default: Y]
----
[start=5]
. As we want to modify console-appenders, the answer to the question from Yuma is Y:
----
Filling optional case /modules/module/configuration/logback:
Add optional list 'console-appenders'?
Enter Y for yes, N for no, or C to cancel: [default: Y]
----
[start=6]
. This will start a new configuration process for console appender and we will fill following values:

* <encoder-pattern> %date{"yyyy-MM-dd HH:mm:ss.SSS z"} %msg %n
* <threshold-filter> INFO
* <name> STDOUT
[start=7]
. Answer N to the next question.
----
Add another list?
Enter Y for yes, N for no, or C to cancel: [default: N]
----
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:
----
rpc-reply {
  data {
    modules {
      module  singleton {
        type logging:logback
        name singleton
        console-appenders {
          threshold-filter INFO
          name STDOUT
          encoder-pattern '%date{"yyyy-MM-dd HH:mm:ss.SSS z"} [%thread] %-5level %logger{36} - %msg%n'
        }
        file-appenders {
          append true
          file-name logs/audit.log
          name audit-file
          encoder-pattern '%date{"yyyy-MM-dd HH:mm:ss.SSS z"} %msg %n'
        }
        loggers {
          level WARN
          logger-name org.opendaylight.controller.logging.bridge
        }
        loggers {
          level INFO
          logger-name audit
          appenders audit-file
        }
        loggers {
          level ERROR
          logger-name ROOT
          appenders STDOUT
          appenders opendaylight.log
        }
        loggers {
          level INFO
          logger-name org.opendaylight
        }
        loggers {
          level WARN
          logger-name io.netty
        }
        rolling-appenders {
          append true
          max-file-size 10MB
          file-name logs/opendaylight.log
          name opendaylight.log
          file-name-pattern logs/opendaylight.%d.log.zip
          encoder-pattern '%date{"yyyy-MM-dd HH:mm:ss.SSS z"} [%thread] %-5level %logger{35} - %msg%n'
          clean-history-on-start false
          max-history 1
          rolling-policy-type TimeBasedRollingPolicy
        }
      }
      module  binding-broker-singleton {
        type binding-impl:binding-broker-impl-singleton
        name binding-broker-singleton
      }
    }
    services {
      service  md-sal-binding:binding-broker-osgi-registry {
        type md-sal-binding:binding-broker-osgi-registry
        instance  ref_binding-broker-singleton {
          name ref_binding-broker-singleton
          provider /modules/module[type='binding-broker-impl-singleton'][name='binding-broker-singleton']
        }
      }
    }
  }
}
----
==== Invoking RPCs
*Invoking Reset RPC on logback* +
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:
----
rpc-reply {
  data {
    modules {
      module  singleton {
        type logging:logback
        name singleton
        status {
          message 'Found resource [configuration/logback.xml] at
[file:/.../controller/opendaylight/distribution/opendaylight/target/distribution.opendaylight-
osgipackage/opendaylight/configuration/logback.xml]'
          level INFO
          date 2479534352
        }
        status {
          message 'debug attribute not set'
          level INFO
          date 2479534441
        }
        status {
          message 'Will scan for changes in
[[/.../controller/opendaylight/distribution/opendaylight/target/distribution.opendaylight-
osgipackage/opendaylight/configuration/logback.xml]]
every 60 seconds.'
          level INFO
          date 2479534448
        }
        status {
          message 'Adding ReconfigureOnChangeFilter as a turbo filter'
          level INFO
          date 2479534448
        }
 ...
----
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:
----
reset context-instance="/modules/module[type='logback' and name='singleton']"
----
After an ok response, issuing get command should produce response with empty logback status message list:
----
rpc-reply {
  data {
    modules {
      module  singleton {
        type logging:logback
        name singleton
      }
    }
  }
}
----
This response confirms successful execution of the reset rpc on logback.

*Invoking shutdown RPC* +
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.
----
shutdown context-instance="/modules/module[type='shutdown' and name='shutdown']",input-secret="",max-wait-time="10000",reason="reason"
----