README.markdown

   1 # OpenDaylight
   2
   3 #### Table of Contents
   4
   5 1. [Overview](#overview)
   6 2. [Module Description](#module-description)
   7 3. [Setup](#setup)
   8
   9 - [What `opendaylight` affects](#what-opendaylight-affects)
  10 - [Beginning with `opendaylight`](#beginning-with-opendaylight)
  11
  12 4. [Usage](#usage)
  13
  14 - [Karaf Features](#karaf-features)
  15 - [RPM Repo](#rpm-repo)
  16 - [Deb Repo](#deb-repo)
  17 - [Ports](#ports)
  18 - [Log Verbosity](#log-verbosity)
  19 - [Enabling ODL HA](#enabling-odl-ha)
  20
  21 5. [Reference ](#reference)
  22 6. [Limitations](#limitations)
  23 7. [Development](#development)
  24 8. [Release Notes/Contributors](#release-notescontributors)
  25
  26 ## Overview
  27
  28 Puppet module that installs and configures the [OpenDaylight Software Defined
  29 Networking (SDN) controller][1].
  30
  31 ## Module Description
  32
  33 Deploys OpenDaylight to various OSs either via an RPM or a Deb.
  34
  35 All OpenDaylight configuration should be handled through the ODL Puppet
  36 module's [params](#parameters).
  37
  38 By default, the master branch installs OpenDaylight from the latest testing
  39 RPM repository or from the latest stable Deb repository depending on the OS.
  40 The stable/<release> branches install corresponding older ODL versions.
  41
  42 ## Setup
  43
  44 ### What `opendaylight` affects
  45
  46 - Installs Java, which is required by ODL.
  47 - Creates `odl:odl` user:group if they don't already exist.
  48 - Installs [OpenDaylight][1], including a systemd unit file.
  49 - Manipulates OpenDaylight's configuration files according to the params
  50   passed to the `::opendaylight` class.
  51 - Starts the `opendaylight` systemd service.
  52
  53 ### Beginning with `opendaylight`
  54
  55 Getting started with the OpenDaylight Puppet module is as simple as declaring
  56 the `::opendaylight` class.
  57
  58 ## Usage
  59
  60 The most basic usage, passing no parameters to the OpenDaylight class, will
  61 install and start OpenDaylight with a default configuration.
  62
  63 ```puppet
  64 class { 'opendaylight':
  65 }
  66 ```
  67
  68 ### Karaf Features
  69
  70 To set extra Karaf features to be installed at OpenDaylight start time, pass
  71 them in a list to the `extra_features` param. The extra features you pass will
  72 typically be driven by the requirements of your ODL install. You'll almost
  73 certainly need to pass some.
  74
  75 ```puppet
  76 class { 'opendaylight':
  77   extra_features => ['odl-netvirt-openstack'],
  78 }
  79 ```
  80
  81 OpenDaylight normally installs a default set of Karaf features at boot. They
  82 are recommended, so the ODL Puppet mod defaults to installing them. This can
  83 be customized by overriding the `default_features` param. You shouldn't
  84 normally need to do so.
  85
  86 ```puppet
  87 class { 'opendaylight':
  88   default_features => ['config', 'standard', 'region', 'package', 'kar', 'ssh', 'management'],
  89 }
  90 ```
  91
  92 ### RPM Repository
  93
  94 The `rpm_repo` param can be used to configure which RPM repository
  95 OpenDaylight is installed from.
  96
  97 ```puppet
  98 class { 'opendaylight':
  99   rpm_repo => 'opendaylight-61-release',
 100 }
 101 ```
 102
 103 The naming convention follows the naming convention of the CentOS Community
 104 Build System, which is where upstream ODL hosts its RPMs. The
 105 `opendaylight-61-release` example above would install OpenDaylight Carbon SR1
 106 6.1.0 from the [nfv7-opendaylight-61-release][2] repo. Repo names ending in
 107 `-release` will always contain well-tested, officially released versions of
 108 OpenDaylight. Repos ending in `-testing` contain frequent, but unstable and
 109 unofficial, releases. The ODL version given in repo names shows which major
 110 and minor version it is pinned to. The `opendaylight-61-release` repo will
 111 always provide OpenDaylight Carbon SR1 6.1, whereas `opendaylight-4-release`
 112 will provide the latest release with major version 6 (which could include
 113 Service Releases, like SR2 6.2).
 114
 115 For additional information about ODL RPM repos, see the [Integration/Packaging
 116 RPM repositories documentation][3].
 117
 118 This is only read for Red Hat-family operating systems.
 119
 120 ### Deb Repository
 121
 122 The `deb_repo` param can be used to configure which Deb repository
 123 OpenDaylight is installed from.
 124
 125 ```puppet
 126 class { 'opendaylight':
 127   deb_repo => 'ppa:odl-team/carbon',
 128 }
 129 ```
 130
 131 The naming convention is same as the naming convention of Launchpad PPA's,
 132 which is where ODL .debs are hosted. The `ppa:odl-team/carbon` example above
 133 would install OpenDaylight Carbon from the [boron launchpad repo][4].
 134
 135 This is only read for Debian-family operating systems.
 136
 137 ### Ports
 138
 139 To change the port on which OpenDaylight's northbound listens for REST API
 140 calls, use the `odl_rest_port` param.
 141
 142 ```puppet
 143 class { 'opendaylight':
 144   odl_rest_port => '8080',
 145 }
 146 ```
 147
 148 ### Log Verbosity
 149
 150 It's possible to define custom logger verbosity levels via the `log_levels`
 151 param.
 152
 153 ```puppet
 154 class { 'opendaylight':
 155   log_levels => { 'org.opendaylight.ovsdb' => 'TRACE', 'org.opendaylight.ovsdb.lib' => 'INFO' },
 156 }
 157 ```
 158
 159 ### Enabling ODL HA
 160
 161 To enable ODL HA, use the `enable_ha` flag. It's disabled by default.
 162
 163 When `enable_ha` is set to true the `ha_node_ips` should be populated with the
 164 IP addresses that ODL will listen on for each node in the HA cluster and
 165 `odl_bind_ip` should be set with the IP address from `ha_node_ips` configured
 166 for the particular node that puppet is configuring as part of the
 167 HA cluster.
 168
 169 By default a single ODL instance will become the leader for the entire
 170 datastore.  In order to distribute the datastore over multiple ODL instances,
 171 `ha_db_modules` parameter may be specified which will include the modules
 172 desired to separate out from the default shard, along with the Yang namespace
 173 for that module.
 174
 175 ```puppet
 176 class { 'opendaylight':
 177   enable_ha     => true,
 178   ha_node_ips   => ['10.10.10.1', '10.10.10.1', '10.10.10.3'],
 179   odl_bind_ip   => 0,
 180   ha_db_modules => {'default' => false, 'topology' => 'urn:opendaylight:topology'}
 181 }
 182 ```
 183
 184 ## Reference
 185
 186 ### Classes
 187
 188 #### Public classes
 189
 190 - `::opendaylight`: Main entry point to the module. All ODL knobs should be
 191   managed through its params.
 192
 193 #### Private classes
 194
 195 - `::opendaylight::params`: Contains default `opendaylight` class param values.
 196 - `::opendaylight::install`: Installs ODL from an RPM or a Deb.
 197 - `::opendaylight::config`: Manages ODL config, including Karaf features and
 198   REST port.
 199 - `::opendaylight::service`: Starts the OpenDaylight service.
 200
 201 ### `::opendaylight`
 202
 203 #### Parameters
 204
 205 ##### `default_features`
 206
 207 Sets the Karaf features to install by default. These should not normally need
 208 to be overridden.
 209
 210 Default: `['config', 'standard', 'region', 'package', 'kar', 'ssh', 'management']`
 211
 212 Valid options: A list of Karaf feature names as strings.
 213
 214 ##### `extra_features`
 215
 216 Specifies Karaf features to install in addition to the defaults listed in
 217 `default_features`.
 218
 219 You will likely need to customize this to your use-case.
 220
 221 Default: `[]`
 222
 223 Valid options: A list of Karaf feature names as strings.
 224
 225 ##### `odl_rest_port`
 226
 227 Specifies the port for the ODL northbound REST interface to listen on.
 228
 229 Default: `'8080'`
 230
 231 Valid options: A valid port number as a string or integer.
 232
 233 ##### `rpm_repo`
 234
 235 OpenDaylight CentOS CBS repo to install RPM from (opendaylight-6-testing,
 236 opendaylight-6-release, ...).
 237
 238 ##### `deb_repo`
 239
 240 OpenDaylight Launchpad PPA repo to install .deb from (ppa:odl-team/boron,
 241 ppa:odl-team/carbon, ...).
 242
 243 ##### `log_levels`
 244
 245 Custom OpenDaylight logger verbosity configuration.
 246
 247 Default: `{}`
 248
 249 Valid options: A hash of loggers to log levels.
 250
 251 ```
 252 { 'org.opendaylight.ovsdb' => 'TRACE', 'org.opendaylight.ovsdb.lib' => 'INFO' }
 253 ```
 254
 255 Valid log levels are TRACE, DEBUG, INFO, WARN, and ERROR.
 256
 257 The above example would add the following logging configuration to
 258 `/opt/opendaylight/etc/org.ops4j.pax.logging.cfg`.
 259
 260 ```
 261 # Log level config added by puppet-opendaylight
 262 log4j.logger.org.opendaylight.ovsdb = TRACE
 263
 264 # Log level config added by puppet-opendaylight
 265 log4j.logger.org.opendaylight.ovsdb.lib = INFO
 266 ```
 267
 268 To view loggers and their verbosity levels, use `log:list` at the ODL Karaf shell.
 269
 270 ```
 271 opendaylight-user@root>log:list
 272 Logger                     | Level
 273 ----------------------------------
 274 ROOT                       | INFO
 275 org.opendaylight.ovsdb     | TRACE
 276 org.opendaylight.ovsdb.lib | INFO
 277 ```
 278
 279 The main log output file is `/opt/opendaylight/data/log/karaf.log`.
 280
 281 ##### `log_max_size`
 282
 283 Maximum size of OpenDaylight's log file, `/opt/opendaylight/data/log/karaf.log`.
 284
 285 Once this size is reached, the log will be rolled over, with up to
 286 `log_max_rollover` log rollovers preserved in total.
 287
 288 Default: `10GB`
 289
 290 Valid options: A valid size as a string with unit specified.
 291
 292 ##### `log_max_rollover`
 293
 294 Maximum number of OpenDaylight karaf.log rollovers to keep.
 295
 296 Note that if this is set to 1, log rollovers will result in loosing newly
 297 logged data. It's recommended to use values greater than one to prune from
 298 the end of the log.
 299
 300 Default: `2`
 301
 302 Valid options: An integer greater than 0.
 303
 304 ##### `enable_ha`
 305
 306 Enable or disable ODL High Availablity.
 307
 308 Default: `false`
 309
 310 Valid options: The boolean values `true` and `false`.
 311
 312 Requires: `ha_node_ips`, `odl_bind_ip`
 313
 314 The ODL Clustering XML for HA are configured and enabled.
 315
 316 ##### `ha_node_ips`
 317
 318 Specifies the IPs that are part of the HA cluster enabled by `enable_ha`.
 319
 320 Default: \[]
 321
 322 Valid options: An array of IP addresses `['10.10.10.1', '10.10.10.1', '10.10.10.3']`.
 323
 324 Required by: `enable_ha`
 325
 326 ##### `ha_db_modules`
 327
 328 Specifies the modules to use for distributing and sharding the ODL datastore.
 329
 330 Default: `{'default'=> false}`
 331
 332 Valid options: A hash of module and Yang namespace for the module (default has no namespace).
 333
 334 Requires: `enable_ha`
 335
 336 ##### `ha_node_index`
 337
 338 Specifies the index of the IP for the node being configured from the array `ha_node_ips`.
 339
 340 Default: ''
 341
 342 Valid options: Index of a member of the array `ha_node_ips`: `0`.
 343
 344 This parameter is now deprecated and is no longer used.
 345
 346 ##### `snat_mechanism`
 347
 348 Specifies the mechanism to be used for SNAT.
 349
 350 Default: `controller`
 351
 352 Valid options: `conntrack`, `controller`
 353
 354 ##### `vpp_routing_node`
 355
 356 Specifies the routing node for VPP deployment. A non-empty string will create config file
 357 org.opendaylight.groupbasedpolicy.neutron.vpp.mapper.startup.cfg with routing-node set.
 358
 359 Default: `''`
 360
 361 Valid options: A valid host name to a VPP node handling routing.
 362
 363 ##### `java_opts`
 364
 365 Specifies the Java options to run ODL with as a string.
 366
 367 Default: `'-Djava.net.preferIPv4Stack=true'`
 368
 369 Valid options: A string of valid Java options.
 370
 371 ##### `username`
 372
 373 Specifies the username to set for admin role in ODL.
 374
 375 Default: `'admin'`
 376
 377 Valid options: A username string.
 378
 379 ##### `password`
 380
 381 Specifies the password to set for admin role in ODL.
 382
 383 Default: `'admin'`
 384
 385 Valid options: A password string.
 386
 387 ## Limitations
 388
 389 - Tested on CentOS 7 and Ubuntu 16.04.
 390 - Fedora is allowed but not well-tested, no Beaker coverage.
 391
 392 ## Development
 393
 394 We welcome contributions and work to make them easy!
 395
 396 See [CONTRIBUTING.markdown][5] for details about how to contribute to the
 397 OpenDaylight Puppet module.
 398
 399 ## Release Notes
 400
 401 See the [CHANGELOG][6] for information about releases.
 402
 403 [1]: http://www.opendaylight.org/ "OpenDaylight homepage"
 404
 405 [2]: http://cbs.centos.org/repos/nfv7-opendaylight-61-release/x86_64/os/Packages/ "OpenDaylight Carbon SR1 CentOS CBS repo"
 406
 407 [3]: http://docs.opendaylight.org/en/latest/submodules/integration/packaging/docs/rpms.html#repositories "ODL RPM repo docs"
 408
 409 [4]: https://launchpad.net/~odl-team/+archive/ubuntu/carbon "ODL Carbon Deb repo"
 410
 411 [5]: https://git.opendaylight.org/gerrit/gitweb?p=integration/packaging/puppet-opendaylight.git;a=blob;f=CONTRIBUTING.markdown "Contributing docs"
 412
 413 [6]: https://git.opendaylight.org/gerrit/gitweb?p=integration/packaging/puppet-opendaylight.git;a=blob;f=CHANGELOG "Chagelog"