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

   1 // https://wiki.opendaylight.org/view/OpenDaylight_Controller:Config:Configuration:Initial
   2
   3 // FIXME: Update this section to provide correct Lithium related information
   4
   5 === Initial Configuration
   6 The Initial configuration of the controller involves two methods.
   7
   8
   9 * Using the etc/custom.properties property file to pass configuration properties to the OSGi bundles besides the config subsystem.
  10 * Using the Configuration Persisters to push the initial configuration for modules managed by the config subsystem.
  11
  12 ==== Using the etc/custom.properties property file
  13
  14 The config.ini property file can be used to provide a set of properties for any OSGi bundle deployed to the controller. It is usually used to configure bundles that are not managed by the config subsystem. For details, see '_etc_custom_properties'.
  15
  16 ==== Using configuration persister
  17
  18 Configuration persister is a default service in the controller, and is started automatically using the OSGi Activator. Its purpose is to load the initial configuration for the config subsystem and store a snapshot for every new configuration state pushed to the config-subsystem from external clients.
  19 For details, see '_configuration_persister'.
  20
  21
  22 ==== etc/custom.properties
  23
  24 Various parts of the system that are not under the configuration subsystem use the file `etc/custom.properties`. Changes to this file apply after a server restart. The tabulation of several important configuration keys and values follows:
  25
  26 [cols="2*", width="75%"]
  27 |===
  28
  29 |Setting | Description
  30 | yangstore.blacklist=.\*controller.model.* | This regular expression (can be OR-ed using pipe character) tells NETCONF to exclude the yang files found in the matching bundle symbolic name from the hello message. This is helpful when dealing with a NETCONF client that has parsing problems.
  31 | netconf.config.persister.* settings  | See '_opendaylight_controller_configuration_initial'.
  32 | netconf.tcp.address=0.0.0.0 netconf.tcp.port=8383 +
  33
  34 netconf.ssh.address=0.0.0.0 netconf.ssh.port=1830 netconf.ssh.pk.path = ./configuration/RSA.pk +
  35
  36 netconf.tcp.client.address=127.0.0.1 netconf.tcp.client.port=8383 | These settings specify the netconf server bindings. IP address 0.0.0.0 is used when all available network interfaces must be used by the netconf server. When starting the ssh server, the user must provide a private key. The actual authentication is done in the user admin module. By default, users admin:admin and netconf:netconf can be used to connect by means of ssh. Since the ssh bridge acts as a proxy, one needs to specify the netconf plaintext TCP address and port. These settings must normally be identical to those specified by netconf.tcp.* .
  37 |===
  38
  39 === Configuration Persister
  40 One way of configuring the controller is to use the configuration persister to push the initial configuration for modules managed by the config subsystem.
  41
  42 ==== Using configuration persister
  43
  44 The configuration persister is a default service in the controller, and is started automatically using the OSGi Activator.
  45 Its purpose: +
  46
  47 * Load the initial configuration for the config subsystem.
  48 * Store a snapshot for every new configuration state pushed to the config-subsystem from external clients. +
  49
  50 It retrieves the base configuration from the config.ini property file, and tries to load the configuration for the config subsystem.
  51 The configuration for the config subsystem is pushed as a set of edit-config netconf rpcs followed by a commit rpc since the config persister acts as a netconf client.
  52
  53 *Configuration persister lifecycle:* +
  54
  55 . Start the config persister service at _config-persister-impl_ bundle startup.
  56 . Retrieve the base configuration of the adapters from the config.ini property file.
  57 . Initialize the backing storage adapters.
  58 . Initialize the netconf client, and connect to the netconf endpoint of the config subsystem.
  59 . Load the initial configuration snapshots from the latest storage adapter.
  60 . Send the edit-config rpc with the initial configuration snapshots.
  61 . Send the commit rpc.
  62 . Listen for any of the following changes to the configuration and persist a snapshot.
  63
  64 *Configuration Persister interactions:* +
  65
  66 .Persister
  67 image::Persister.jpg[width=500]
  68
  69 ==== Current configuration for controller distribution
  70
  71 The _config.ini_ property file contains the following configuration for the configuration persister: +
  72 ----
  73 netconf.config.persister.active=1,2
  74
  75 netconf.config.persister.1.storageAdapterClass=org.opendaylight.controller.config.persist.storage.directory.autodetect.AutodetectDirectoryStorageAdapter
  76
  77 netconf.config.persister.1.properties.directoryStorage=configuration/initial/
  78
  79 netconf.config.persister.1.readonly=true
  80
  81
  82 netconf.config.persister.2.storageAdapterClass=org.opendaylight.controller.config.persist.storage.file.xml.XmlFileStorageAdapter
  83
  84 netconf.config.persister.2.properties.fileStorage=configuration/current/controller.currentconfig.xml
  85
  86 netconf.config.persister.2.properties.numberOfBackups=1
  87 ----
  88
  89 With this configuration, the configuration persister initializes two adapters: +
  90
  91 * **AutodetectDirectoryStorageAdapter** to load the initial configuration files from the _configuration/initial/_ folder. These files will be pushed as the initial configuration for the config subsystem. Since this adapter is Read only, it will not store any configuration snapshot during the controller lifecycle.
  92 * **XmlFileStorageAdapter** to store snapshots of the current configuration after any change in the file _configuration/current/controller.currentconfig.xml_ (Only 1 snapshot backup is kept; every new change overwrites the previous one). +
  93
  94 The initial configuration in the controller distribution consists of 2 files in the  https://wiki.opendaylight.org/view/OpenDaylight_Controller:Config:Configuration:Initial#Persisted_snapshot_format[xml format]. +
  95
  96
  97 * configuration/initial/00-netty.xml: +
  98 [source,xml]
  99 ----
 100 <snapshot>
 101     <required-capabilities>
 102         <capability>urn:opendaylight:params:xml:ns:yang:controller:netty?module=netty&amp;revision=2013-11-19</capability>
 103         <capability>urn:opendaylight:params:xml:ns:yang:controller:netty:eventexecutor?module=netty-event-executor&amp;revision=2013-11-12</capability>
 104         <capability>urn:opendaylight:params:xml:ns:yang:controller:netty:threadgroup?module=threadgroup&amp;revision=2013-11-07</capability>
 105         <capability>urn:opendaylight:params:xml:ns:yang:controller:netty:timer?module=netty-timer&amp;revision=2013-11-19</capability>
 106     </required-capabilities>
 107     <configuration>
 108
 109         <data xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 110             <modules xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
 111                 <module>
 112                     <type xmlns:netty="urn:opendaylight:params:xml:ns:yang:controller:netty:threadgroup">netty:netty-threadgroup-fixed</type>
 113                     <name>global-boss-group</name>
 114                 </module>
 115                 <module>
 116                     <type xmlns:netty="urn:opendaylight:params:xml:ns:yang:controller:netty:threadgroup">netty:netty-threadgroup-fixed</type>
 117                     <name>global-worker-group</name>
 118                 </module>
 119                 <module>
 120                     <type xmlns:netty="urn:opendaylight:params:xml:ns:yang:controller:netty:timer">netty:netty-hashed-wheel-timer</type>
 121                     <name>global-timer</name>
 122                 </module>
 123                 <module>
 124                     <type xmlns:netty="urn:opendaylight:params:xml:ns:yang:controller:netty:eventexecutor">netty:netty-global-event-executor</type>
 125                     <name>global-event-executor</name>
 126                 </module>
 127             </modules>
 128
 129             <services xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
 130                 <service>
 131                     <type xmlns:netty="urn:opendaylight:params:xml:ns:yang:controller:netty">netty:netty-threadgroup</type>
 132                     <instance>
 133                         <name>global-boss-group</name>
 134                         <provider>/modules/module[type='netty-threadgroup-fixed'][name='global-boss-group']</provider>
 135                     </instance>
 136                     <instance>
 137                         <name>global-worker-group</name>
 138                         <provider>/modules/module[type='netty-threadgroup-fixed'][name='global-worker-group']</provider>
 139                     </instance>
 140                 </service>
 141                 <service>
 142                     <type xmlns:netty="urn:opendaylight:params:xml:ns:yang:controller:netty">netty:netty-event-executor</type>
 143                     <instance>
 144                         <name>global-event-executor</name>
 145                         <provider>/modules/module[type='netty-global-event-executor'][name='global-event-executor']</provider>
 146                     </instance>
 147                 </service>
 148                 <service>
 149                     <type xmlns:netty="urn:opendaylight:params:xml:ns:yang:controller:netty">netty:netty-timer</type>
 150                     <instance>
 151                         <name>global-timer</name>
 152                         <provider>/modules/module[type='netty-hashed-wheel-timer'][name='global-timer']</provider>
 153                     </instance>
 154                 </service>
 155             </services>
 156         </data>
 157
 158     </configuration>
 159 </snapshot>
 160 ----
 161 This configuration snapshot instantiates netty utilities, which will be utilized by the controller components that use netty internally. +
 162
 163 *configuration/initial/01-md-sal.xml:* +
 164 ----
 165 <snapshot>
 166
 167     <configuration>
 168
 169         <data xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 170             <modules xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
 171                 <module>
 172                     <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom:impl">prefix:schema-service-singleton</type>
 173                     <name>yang-schema-service</name>
 174                 </module>
 175                 <module>
 176                     <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom:impl">prefix:hash-map-data-store</type>
 177                     <name>hash-map-data-store</name>
 178                 </module>
 179                 <module>
 180                     <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom:impl">prefix:dom-broker-impl</type>
 181                     <name>dom-broker</name>
 182                     <data-store xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom:impl">
 183                         <type xmlns:dom="urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom">dom:dom-data-store</type>
 184                         <!-- to switch to the clustered data store, comment out the hash-map-data-store <name> and uncomment the cluster-data-store one -->
 185                         <name>hash-map-data-store</name>
 186                         <!-- <name>cluster-data-store</name> -->
 187                     </data-store>
 188                 </module>
 189                 <module>
 190                     <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding:impl">prefix:binding-broker-impl</type>
 191                     <name>binding-broker-impl</name>
 192                     <notification-service xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding:impl">
 193                         <type xmlns:binding="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">binding:binding-notification-service</type>
 194                         <name>binding-notification-broker</name>
 195                     </notification-service>
 196                     <data-broker xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding:impl">
 197                         <type xmlns:binding="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">binding:binding-data-broker</type>
 198                         <name>binding-data-broker</name>
 199                     </data-broker>
 200                 </module>
 201                 <module>
 202                     <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding:impl">prefix:runtime-generated-mapping</type>
 203                     <name>runtime-mapping-singleton</name>
 204                 </module>
 205                 <module>
 206                     <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding:impl">prefix:binding-notification-broker</type>
 207                     <name>binding-notification-broker</name>
 208                 </module>
 209                 <module>
 210                     <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding:impl">prefix:binding-data-broker</type>
 211                     <name>binding-data-broker</name>
 212                     <dom-broker xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding:impl">
 213                         <type xmlns:dom="urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom">dom:dom-broker-osgi-registry</type>
 214                         <name>dom-broker</name>
 215                     </dom-broker>
 216                     <mapping-service xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding:impl">
 217                         <type xmlns:binding="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding:impl">binding:binding-dom-mapping-service</type>
 218                         <name>runtime-mapping-singleton</name>
 219                     </mapping-service>
 220                 </module>
 221
 222             </modules>
 223
 224             <services xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
 225                         <service>
 226                                 <type xmlns:dom="urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom">dom:schema-service</type>
 227                                 <instance>
 228                                         <name>yang-schema-service</name>
 229                                         <provider>/modules/module[type='schema-service-singleton'][name='yang-schema-service']</provider>
 230                                 </instance>
 231                         </service>
 232                         <service>
 233                                 <type xmlns:binding="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">binding:binding-notification-service</type>
 234                                 <instance>
 235                                         <name>binding-notification-broker</name>
 236                                         <provider>/modules/module[type='binding-notification-broker'][name='binding-notification-broker']</provider>
 237                                 </instance>
 238                         </service>
 239                         <service>
 240                                 <type xmlns:dom="urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom">dom:dom-data-store</type>
 241                                 <instance>
 242                                         <name>hash-map-data-store</name>
 243                                         <provider>/modules/module[type='hash-map-data-store'][name='hash-map-data-store']</provider>
 244                                 </instance>
 245                         </service>
 246                         <service>
 247                                 <type xmlns:binding="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">binding:binding-broker-osgi-registry</type>
 248                                 <instance>
 249                                         <name>binding-osgi-broker</name>
 250                                         <provider>/modules/module[type='binding-broker-impl'][name='binding-broker-impl']</provider>
 251                                 </instance>
 252                         </service>
 253                         <service>
 254                                 <type xmlns:binding="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">binding:binding-rpc-registry</type>
 255                                 <instance>
 256                                         <name>binding-rpc-broker</name>
 257                                         <provider>/modules/module[type='binding-broker-impl'][name='binding-broker-impl']</provider>
 258                                 </instance>
 259                         </service>
 260                         <service>
 261                                 <type xmlns:binding-impl="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding:impl">binding-impl:binding-dom-mapping-service</type>
 262                                 <instance>
 263                                         <name>runtime-mapping-singleton</name>
 264                                         <provider>/modules/module[type='runtime-generated-mapping'][name='runtime-mapping-singleton']</provider>
 265                                 </instance>
 266                         </service>
 267                         <service>
 268                         <type xmlns:dom="urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom">dom:dom-broker-osgi-registry</type>
 269                                 <instance>
 270                                         <name>dom-broker</name>
 271                                         <provider>/modules/module[type='dom-broker-impl'][name='dom-broker']</provider>
 272                                 </instance>
 273                         </service>
 274                         <service>
 275                                 <type xmlns:binding="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">binding:binding-data-broker</type>
 276                                 <instance>
 277                                         <name>binding-data-broker</name>
 278                                         <provider>/modules/module[type='binding-data-broker'][name='binding-data-broker']</provider>
 279                                 </instance>
 280                         </service>
 281
 282             </services>
 283         </data>
 284
 285     </configuration>
 286
 287     <required-capabilities>
 288         <capability>urn:opendaylight:params:xml:ns:yang:controller:netty:eventexecutor?module=netty-event-executor&amp;revision=2013-11-12</capability>
 289         <capability>urn:opendaylight:params:xml:ns:yang:controller:threadpool?module=threadpool&amp;revision=2013-04-09</capability>
 290         <capability>urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding?module=opendaylight-md-sal-binding&amp;revision=2013-10-28</capability>
 291         <capability>urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom?module=opendaylight-md-sal-dom&amp;revision=2013-10-28</capability>
 292         <capability>urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding:impl?module=opendaylight-sal-binding-broker-impl&amp;revision=2013-10-28</capability>
 293         <capability>urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom:impl?module=opendaylight-sal-dom-broker-impl&amp;revision=2013-10-28</capability>
 294         <capability>urn:opendaylight:params:xml:ns:yang:controller:md:sal:common?module=opendaylight-md-sal-common&amp;revision=2013-10-28</capability>
 295     </required-capabilities>
 296
 297 </snapshot>
 298 ----
 299 This configuration snapshot instantiates md-sal modules.
 300
 301 After the controller is started, all these modules will be instantiated and configured. They can be further referenced from the new modules as dependencies, reconfigured, or even deleted.
 302 These modules are considered to be the base configuration for the controller and the purpose of them being configured automatically is to simplify the process of controller configuration for users, since the base modules will already be ready for use.
 303
 304 === Adding custom initial configuration
 305
 306 There are multiple ways to add the custom initial confguration to the controller distribution:
 307
 308 . Manually create the config file, and put it in the initial configuration folder.
 309 . Reconfigure the running controller using the yuma yangcli tool. The XmlFileStorageAdapter adapter will store the current snapshot, and on the next startup of the controller (assuming it was not rebuilt since), it will load the configuration containing the changes.
 310
 311 ==== Custom initial configuration in bgpcep distribution
 312
 313 The BGPCEP project will serve as an example for adding the custom initial configuration. The bgpcep project contains the custom initial configuration that is based on the initial configuration from the controller. It adds new modules, which depend on MD-SAL and netty modules created with the initial config files of the controller. There are multiple config files in the bgpcep project. Only the 30-programming.xml file located under the programming-parent/controller-config project will be described in this section. This file contains the configuration for an instance of the instruction-scheduler module:
 314
 315 ----
 316 <?xml version="1.0" encoding="UTF-8"?>
 317 <!-- vi: set et smarttab sw=4 tabstop=4: -->
 318 <!--
 319       Copyright (c) 2013 Cisco Systems, Inc. and others.  All rights reserved.
 320
 321  This program and the accompanying materials are made available under the
 322  terms of the Eclipse Public License v1.0 which accompanies this distribution,
 323  and is available at http://www.eclipse.org/legal/epl-v10.html.
 324 -->
 325 <snapshot>
 326         <required-capabilities>
 327                 <capability>urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding?module=opendaylight-md-sal-binding&amp;revision=2013-10-28</capability>
 328                 <capability>urn:opendaylight:params:xml:ns:yang:controller:netty?module=netty&amp;revision=2013-11-19</capability>
 329                 <capability>urn:opendaylight:params:xml:ns:yang:controller:programming:impl?module=config-programming-impl&amp;revision=2013-11-15</capability>
 330                 <capability>urn:opendaylight:params:xml:ns:yang:controller:programming:spi?module=config-programming-spi&amp;revision=2013-11-15</capability>
 331         </required-capabilities>
 332         <configuration>
 333
 334                 <data xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 335                         <modules xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
 336                                 <module>
 337                                         <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:programming:impl">prefix:instruction-scheduler-impl</type>
 338                                         <name>global-instruction-scheduler</name>
 339                                         <data-provider>
 340                                                 <type xmlns:binding="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">binding:binding-data-broker</type>
 341                                                 <name>binding-data-broker</name>
 342                                         </data-provider>
 343                                         <notification-service>
 344                                                 <type xmlns:binding="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">binding:binding-notification-service</type>
 345                                                 <name>binding-notification-broker</name>
 346                                         </notification-service>
 347                                         <rpc-registry>
 348                                                 <type xmlns:binding="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">binding:binding-rpc-registry</type>
 349                                                 <name>binding-rpc-broker</name>
 350                                         </rpc-registry>
 351                                         <timer>
 352                                                 <type xmlns:netty="urn:opendaylight:params:xml:ns:yang:controller:netty">netty:netty-timer</type>
 353                                                 <name>global-timer</name>
 354                                         </timer>
 355                                 </module>
 356                         </modules>
 357
 358                         <services xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
 359                                 <service>
 360                                         <type xmlns:pgmspi="urn:opendaylight:params:xml:ns:yang:controller:programming:spi">pgmspi:instruction-scheduler</type>
 361                                         <instance>
 362                                                 <name>global-instruction-scheduler</name>
 363                                                 <provider>/modules/module[type='instruction-scheduler-impl'][name='global-instruction-scheduler']</provider>
 364                                         </instance>
 365                                 </service>
 366                         </services>
 367                 </data>
 368
 369         </configuration>
 370 </snapshot>
 371 ----
 372 Instruction-scheduler is instantiated as a module of type _instruction-scheduler-impl_ with the name *global-instruction-scheduler:* +
 373 ----
 374 <module>
 375        <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:programming:impl">prefix:instruction-scheduler-impl</type>
 376        <name>global-instruction-scheduler</name>
 377        ...
 378 ----
 379 There is also an alias created for this module instancfe, and the alias is *global-instruction-scheduler* of type _instruction-scheduler_: +
 380 ----
 381 ...
 382 <service>
 383         <type xmlns:pgmspi="urn:opendaylight:params:xml:ns:yang:controller:programming:spi">pgmspi:instruction-scheduler</type>
 384         <instance>
 385                 <name>global-instruction-scheduler</name>
 386                 <provider>/modules/module[type='instruction-scheduler-impl'][name='global-instruction-scheduler']</provider>
 387         </instance>
 388 </service>
 389 ...
 390 ----
 391 The type of the alias is instruction-scheduler. This type refers to a certain service that is implemented by the instruction-scheduler-impl module. With this service type, the global-instruction-scheduler instance can be injected into any other module that requires instruction-scheduler as a dependency.
 392 One module can provide (implement) multiple services, and each of these services can be assigned an alias. This alias can be later used to reference the implementation it is pointing to.
 393 If no alias is assigned by the user, a default alias will be assigned for each provided service.
 394 The default alias is constructed from the name of the module instance with a prefix *ref_* and a possible suffix containing a number to resolve name clashes.
 395 It is recommended that users provide aliases for each service of every module instance, and use these aliases for dependency injection. References to the alias global-instruction-scheduler can be found in subsequent config files in the bgpcep project for example, _32-pcep.xml_ located under the _pcep-parent/pcep-controller-config_ project.
 396
 397 The configuration contains four dependencies on the MD-SAL and the netty modules: +
 398 ----
 399 ...
 400 <data-provider>
 401         <type xmlns:binding="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">binding:binding-data-broker</type>
 402         <name>binding-data-broker</name>
 403 </data-provider>
 404 <notification-service>
 405         <type xmlns:binding="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">binding:binding-notification-service</type>
 406         <name>binding-notification-broker</name>
 407 </notification-service>
 408 <rpc-registry>
 409         <type xmlns:binding="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">binding:binding-rpc-registry</type>
 410         <name>binding-rpc-broker</name>
 411 </rpc-registry>
 412 <timer>
 413         <type xmlns:netty="urn:opendaylight:params:xml:ns:yang:controller:netty">netty:netty-timer</type>
 414         <name>global-timer</name>
 415 </timer>
 416 ...
 417 ----
 418
 419 MD-SAL dependencies: +
 420
 421 * Data-provider dependency
 422 * Notification-service dependency
 423 * Rpc-registry dependency
 424
 425 All MD-SAL dependencies can be found in the https://wiki.opendaylight.org/view/OpenDaylight_Controller:Config:Configuration:Initial#Current_configuration_for_controller_distribution[MD-SAL initial configuration file]. For example, rpc-registry dependency points to an alias binding-rpc-broker of the type binding-rpc-registry. This alias further points to an instance of the binding-broker-impl named binding-broker-impl.
 426 The Yang module that defines the binding-broker-impl module : https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/sal-binding-broker/src/main/yang/opendaylight-binding-broker-impl.yang;a=blob[opendaylight-binding-broker-impl.yang].
 427
 428 *Netty dependencies:* +
 429
 430 * Timer dependency
 431
 432 This configuration expects these dependencies to be already up and ready. It is the responsibility of the configuration subsystem to find the dependency and inject it.
 433 If the configuration of a module points to a non-existing dependency, the configuration subsystem will produce an exception during the validation phase.
 434 Every user-created configuration needs to point to existing dependencies. In the case of multiple initial configuration files that depend on one another, the resolution order can be ensured by the names of the files. Files are sorted by their names in ascending order. This means that every configuration file will have the visibility of modules from all previous configuration files by means of aliases.
 435
 436 NOTE: The configuration provided by initial config files can also be pushed to the controller at runtime using netconf client. The whole configuration located under the data tag needs to be inserted into the config tag in the edit-config rpc. For more information, see https://wiki.opendaylight.org/view/OpenDaylight_Controller:Config:Main#Examples[Examples].
 437
 438 ==== Configuration Persister
 439
 440 As a part of the configuration subsystem, the purpose of the persister is to save and load a permanent copy of a configuration. The Persister interface represents basic operations over a storage - persist configuration and load last config, configuration snapshot is represented as string and set of it's capabilities. StorageAdapter represents an adapter interface to the ConfigProvider - subset of BundleContext, allowing access to the OSGi framework system properties.
 441
 442 ===== Persister implementation
 443
 444 Configuration persister implementation is part of the Controller NETCONF. PersisterAggregator class is the implementation of the Presister interface. The functionality is delegated to the storage adapters. Storage adapters are low level persisters that do the heavy lifting for this class. Instances of storage adapters can be injected directly by means of the constructor, or instantiated from a full name of its class provided in a properties file. There can be many persisters configured, and varying numbers of them can be used.
 445
 446 *Example of presisters configuration:* +
 447 ----
 448 netconf.config.persister.active=2,3
 449  # read startup configuration
 450  netconf.config.persister.1.storageAdapterClass=org.opendaylight.controller.config.persist.storage.directory.xml.XmlDirectoryStorageAdapter
 451  netconf.config.persister.1.properties.fileStorage=configuration/initial/
 452
 453  netconf.config.persister.2.storageAdapterClass=org.opendaylight.controller.config.persist.storage.file.FileStorageAdapter
 454  netconf.config.persister.2.readonly=true
 455  netconf.config.persister.2.properties.fileStorage=configuration/current/controller.config.1.txt
 456
 457  netconf.config.persister.3.storageAdapterClass=org.opendaylight.controller.config.persist.storage.file.FileStorageAdapter
 458  netconf.config.persister.3.properties.fileStorage=configuration/current/controller.config.2.txt
 459  netconf.config.persister.3.properties.numberOfBackups=3
 460 ----
 461
 462 During server startup, ConfigPersisterNotificationHandler requests the last snapshot from the underlying storages. Each storage can respond by giving a snapshot or an absent response. The PersisterAggregator#loadLastConfigs() will search for the first non-absent response from storages ordered backwards as user specified (first '3', then '2'). When a commit notification is received, '2' will be omitted because the read-only flag is set to true, so only '3' will have a chance to persist the new configuration.
 463 If read-only was false, or not specified, both storage adapters would be called in the order specified by 'netconf.config.persister' property.
 464
 465 === Persister Notification Handler
 466
 467 ConfigPersisterNotificationHandler class is responsible for listening for netconf notifications containing the latest committed configuration.
 468 The listener can handle incoming notifications, or delegates the configuration saving or loading to the persister.
 469
 470 ==== Storage Adapter implementations
 471
 472 *XML File Storage* +
 473
 474 The XmlFileStorageAdapter implementation stores configuration in an xml file.
 475
 476 *XML Directory Storage* +
 477
 478 XmlDirectoryStorageAdapter retrieves the initial configuration from a directory. If multiple xml files are present, files are ordered based on the file names and pushed in this order (for example, 00.xml, then 01.xml..) Each file defines its required capabilities, so it will be pushed when those capabilities are advertized by ODL. Writing to this persister is not supported.
 479
 480 *No-Operation Storage* +
 481
 482 NoOpStorageAdapter serves as a dummy implementation of the storage adapter.
 483
 484 *Obsolete storage adapters* +
 485
 486 * File Storage
 487
 488 * FileStorageAdapter implements StorageAdapter, and provides file based configuration persisting.
 489 File path and name is stored as a property and a number of stored backups, expressing the count of the last configurations to be persisted too.
 490 The implementation can handle persisting input configuration, and load the last configuration.
 491
 492 * Directory Storage
 493
 494 * DirectoryStorageAdapter retrieves initial configurations from a directory. If multiple files are present, snapshot and required capabilities will be merged together. See configuration later on this page for details. Writing to this persister is not supported.
 495
 496 * Autodetect Directory Storage
 497
 498 * AutodetectDirectoryStorageAdapter retrieves initial configuration from a directory (exactly as Xml Directory Storage) but supports xml as well as plaintext format for configuration files. Xml and plaintext files can be combined in one directory. Purpose of this persister is to keep backwards compatibility for plaintext configuration files.
 499
 500 IMPORTANT: This functionality will be removed in later releases since Plaintext File/Directory adapters are deprecated, and will be fully replaced by xml storage adapters.
 501
 502 ===== Persisted snapshot format
 503
 504 Configuration snapshots are persisted in xml files for both file and directory adapters. They share the same format: +
 505 ----
 506 <snapshot>
 507     <required-capabilities>
 508         <capability>urn:opendaylight:params:xml:ns:yang:controller:netty?module=netty&amp;revision=2013-11-19</capability>
 509         ...
 510     </required-capabilities>
 511     <configuration>
 512
 513         <data xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 514             <modules xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
 515              ...
 516             </modules>
 517
 518             <services xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
 519              ...
 520             </services>
 521
 522         </data>
 523
 524     </configuration>
 525 </snapshot>
 526 ----
 527 The whole snapshot is encapsulated in the snapshot tag that contains two children elements: +
 528
 529 * The required-capabilities tag contains the list of yang capabilities that are required to push configurations located under the configuration tag. The config persister will not push the configuration before the netconf endpoint for the config subsystem reports all needed capabilities. Every yang model that is referenced within this xml file (as namespace for xml tag) must be referenced as a capability in this list.
 530 * The configuration tag contains the configurations to be pushed to the config subsystem. It is wrapped in a data tag with the base netconf namespace. The whole data tag, with all its child elements, will be inserted into an edit-config rpc as config tag. For more information about the structure of configuration data, see  base yang model for the config subsystem and all the configuration yang files for the controller modules as well as those provided examples. Examples contain multiple explained edit-config rpcs that change the configuration.
 531
 532 NOTE:  XML File adapter adds additional tags to the xml format since it supports multiple snapshots per file.
 533
 534 The xml format for xml file adapter: +
 535 ----
 536 <persisted-snapshots>
 537    <snapshots>
 538       <snapshot>
 539          <required-capabilities>
 540             <capability>urn:opendaylight:params:xml:ns:yang:controller:shutdown:impl?module=shutdown-impl&amp;revision=2013-12-18</capability>
 541          </required-capabilities>
 542          <configuration>
 543             <data xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 544                <modules xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
 545                  ....
 546                </modules>
 547                <services xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
 548                  ...
 549                </services>
 550             </data>
 551          </configuration>
 552       </snapshot>
 553       <snapshot>
 554          <required-capabilities>
 555             <capability>urn:opendaylight:params:xml:ns:yang:controller:shutdown:impl?module=shutdown-impl&amp;revision=2013-12-18</capability>
 556          </required-capabilities>
 557          <configuration>
 558             <data xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 559                <modules xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
 560                  ....
 561                </modules>
 562                <services xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
 563                  ...
 564                </services>
 565             </data>
 566          </configuration>
 567       </snapshot>
 568    </snapshots>
 569 </persisted-snapshots>
 570 ----