README.markdown

   1 [![CI Status][4]][1]
   2 [![Dependency Status][5]][2]
   3
   4 # OpenDaylight
   5
   6 #### Table of Contents
   7 1. [Overview](#overview)
   8 1. [Module Description](#module-description)
   9 1. [Setup](#setup)
  10   * [What `opendaylight` affects](#what-opendaylight-affects)
  11   * [Beginning with `opendaylight`](#beginning-with-opendaylight)
  12 1. [Usage](#usage)
  13   * [Karaf Features](#karaf-features)
  14   * [Install Method](#install-method)
  15   * [RPM Repo](#rpm-repo)
  16   * [Ports](#ports)
  17   * [Log Verbosity](#log-verbosity)
  18   * [Enabling ODL OVSDB L3](#enabling-odl-ovsdb-l3)
  19   * [Enabling ODL OVSDB HA](#enabling-odl-ovsdb-ha)
  20 1. [Reference ](#reference)
  21 1. [Limitations](#limitations)
  22 1. [Development](#development)
  23 1. [Release Notes/Contributors](#release-notescontributors)
  24
  25 ## Overview
  26
  27 Puppet module that installs and configures the [OpenDaylight Software Defined
  28 Networking (SDN) controller][7].
  29
  30 ## Module Description
  31
  32 Deploys OpenDaylight to various OSs either via an RPM or directly from the
  33 ODL tarball release artifact.
  34
  35 All OpenDaylight configuration should be handled through the ODL Puppet
  36 module's [params](#parameters). If you need a new knob, [please raise an
  37 Issue][8].
  38
  39 The master branch installs OpenDaylight from the latest testing RPM repository
  40 by default. There are stable/<release> branches that install OpenDaylight
  41 releases and service releases, like Beryllium or Beryllium SR3.
  42
  43 ## Setup
  44
  45 ### What `opendaylight` affects
  46
  47 * Installs Java, which is required by ODL.
  48 * Creates `odl:odl` user:group if they don't already exist.
  49 * Installs [OpenDaylight][7].
  50 * Installs a [systemd unitfile][9] or [Upstart config file][10] for
  51 OpenDaylight.
  52 * Manipulates OpenDaylight's configuration files according to the params
  53 passed to the `::opendaylight` class.
  54 * Starts the `opendaylight` systemd or Upstart service.
  55
  56 ### Beginning with `opendaylight`
  57
  58 Getting started with the OpenDaylight Puppet module is as simple as declaring
  59 the `::opendaylight` class.
  60
  61 The [vagrant-opendaylight][11] project provides an easy way to experiment
  62 with [applying the ODL Puppet module][12] to CentOS 7, Fedora 22 and Fedora
  63 23 Vagrant boxes.
  64
  65 ```
  66 [~/vagrant-opendaylight]$ vagrant status
  67 Current machine states:
  68
  69 cent7                     not created (libvirt)
  70 cent7_rpm_he_sr4          not created (libvirt)
  71 cent7_rpm_li_sr2          not created (libvirt)
  72 cent7_rpm_be              not created (libvirt)
  73 cent7_ansible             not created (libvirt)
  74 cent7_ansible_be          not created (libvirt)
  75 cent7_ansible_path        not created (libvirt)
  76 cent7_pup_rpm             not created (libvirt)
  77 cent7_pup_custom_logs     not created (libvirt)
  78 cent7_pup_tb              not created (libvirt)
  79 f22_rpm_li                not created (libvirt)
  80 f22_ansible               not created (libvirt)
  81 f22_pup_rpm               not created (libvirt)
  82 f23_rpm_li                not created (libvirt)
  83 f23_rpm_li_sr1            not created (libvirt)
  84 f23_rpm_li_sr2            not created (libvirt)
  85 f23_rpm_li_sr3            not created (libvirt)
  86 f23_rpm_be                not created (libvirt)
  87 f23_ansible               not created (libvirt)
  88 f23_pup_rpm               not created (libvirt)
  89
  90 [~/vagrant-opendaylight]$ vagrant up cent7_pup_rpm
  91 # A CentOS 7 VM is created and configured using the ODL Puppet mod's defaults
  92 [~/vagrant-opendaylight]$ vagrant ssh cent7_pup_rpm
  93 [vagrant@localhost ~]$ sudo systemctl is-active opendaylight
  94 active
  95 ```
  96
  97 ## Usage
  98
  99 The most basic usage, passing no parameters to the OpenDaylight class, will
 100 install and start OpenDaylight with a default configuration.
 101
 102 ```puppet
 103 class { 'opendaylight':
 104 }
 105 ```
 106
 107 ### Karaf Features
 108
 109 To set extra Karaf features to be installed at OpenDaylight start time, pass
 110 them in a list to the `extra_features` param. The extra features you pass will
 111 typically be driven by the requirements of your ODL install. You'll almost
 112 certainly need to pass some.
 113
 114 ```puppet
 115 class { 'opendaylight':
 116   extra_features => ['odl-ovsdb-plugin', 'odl-ovsdb-openstack'],
 117 }
 118 ```
 119
 120 OpenDaylight normally installs a default set of Karaf features at boot. They
 121 are recommended, so the ODL Puppet mod defaults to installing them. This can
 122 be customized by overriding the `default_features` param. You shouldn't
 123 normally need to do so.
 124
 125 ```puppet
 126 class { 'opendaylight':
 127   default_features => ['config', 'standard', 'region', 'package', 'kar', 'ssh', 'management'],
 128 }
 129 ```
 130
 131 ### Install Method
 132
 133 The `install_method` param, and the associated `tarball_url` and `unitfile_url`
 134 params, are intended for use by developers who need to install a custom-built
 135 version of OpenDaylight, or for automated build processes that need to consume
 136 a tarball build artifact.
 137
 138 It's recommended that most people use the default RPM-based install.
 139
 140 If you do need to install from a tarball, simply pass `tarball` as the value
 141 for `install_method` and optionally pass the URL to your tarball via the
 142 `tarball_url` param. The default value for `tarball_url` points at
 143 OpenDaylight's latest release. The `unitfile_url` param points at the
 144 OpenDaylight systemd .service file used by the RPM and should (very likely)
 145 not need to be overridden.
 146
 147 ```puppet
 148 class { 'opendaylight':
 149   install_method => 'tarball',
 150   tarball_url    => '<URL to your custom tarball>',
 151   unitfile_url   => '<URL to your custom unitfile>',
 152 }
 153 ```
 154
 155 ### RPM Repo
 156
 157 The `rpm_repo` param can be used to configure which RPM repository
 158 OpenDaylight is installed from.
 159
 160 ```puppet
 161 class { 'opendaylight':
 162   rpm_repo => 'opendaylight-40-release',
 163 }
 164 ```
 165
 166 The naming convention follows the naming convention of the CentOS Community
 167 Build System, which is where upstream ODL hosts its RPMs. The
 168 `opendaylight-40-release` example above would install OpenDaylight Beryllium
 169 4.0.0 from the [nfv7-opendaylight-40-release][18] repo. Repo names ending in
 170 `-release` will always contain well-tested, officially released versions of
 171 OpenDaylight. Repos ending in `-testing` contain frequent, but unstable and
 172 unofficial, releases. The ODL version given in repo names shows which major
 173 and minor version it is pinned to. The `opendaylight-40-release` repo will
 174 always provide OpenDaylight Beryllium 4.0, whereas `opendaylight-4-release`
 175 will provide the latest release with major version 4 (which could include
 176 Service Releases, like SR2 4.2).
 177
 178 For a full list of OpenDaylight releases and their CBS repos, see the
 179 [OpenDaylight Deployment wiki][19].
 180
 181 This is only read when `install_method` is `rpm`.
 182
 183 ### Ports
 184
 185 To change the port on which OpenDaylight's northbound listens for REST API
 186 calls, use the `odl_rest_port` param.
 187
 188
 189 ```puppet
 190 class { 'opendaylight':
 191   odl_rest_port => '8080',
 192 }
 193 ```
 194
 195 ### Log Verbosity
 196
 197 It's possible to define custom logger verbosity levels via the `log_levels`
 198 param.
 199
 200 ```puppet
 201 class { 'opendaylight':
 202   log_levels => { 'org.opendaylight.ovsdb' => 'TRACE', 'org.opendaylight.ovsdb.lib' => 'INFO' },
 203 }
 204 ```
 205
 206 ### Enabling ODL OVSDB L3
 207
 208 To enable the ODL OVSDB L3, use the `enable_l3` flag. It's disabled by default.
 209
 210 ```puppet
 211 class { 'opendaylight':
 212   enable_l3 => true,
 213 }
 214 ```
 215
 216 ### Enable ODL OVSDB HA
 217
 218 To enable ODL OVSDB HA, use the `enable_ha` flag. It's disabled by default.
 219
 220 When `enable_ha` is set to true the `ha_node_ips` should be populated with the
 221 IP addresses that ODL will listen on for each node in the OVSDB HA cluster and
 222 `ha_node_index` should be set with the index of the IP address from
 223 `ha_node_ips` for the particular node that puppet is configuring as part of the
 224 HA cluster.
 225
 226 ```puppet
 227 class { 'opendaylight':
 228   enable_ha     => true,
 229   ha_node_ips   => ['10.10.10.1', '10.10.10.1', '10.10.10.3'],
 230   ha_node_index => 0,
 231 }
 232 ```
 233
 234 ## Reference
 235
 236 ### Classes
 237
 238 #### Public classes
 239
 240 * `::opendaylight`: Main entry point to the module. All ODL knobs should be
 241 managed through its params.
 242
 243 #### Private classes
 244
 245 * `::opendaylight::params`: Contains default `opendaylight` class param values.
 246 * `::opendaylight::install`: Installs ODL from an RPM or tarball.
 247 * `::opendaylight::config`: Manages ODL config, including Karaf features and
 248 REST port.
 249 * `::opendaylight::service`: Starts the OpenDaylight service.
 250
 251 ### `::opendaylight`
 252
 253 #### Parameters
 254
 255 ##### `default_features`
 256
 257 Sets the Karaf features to install by default. These should not normally need
 258 to be overridden.
 259
 260 Default: `['config', 'standard', 'region', 'package', 'kar', 'ssh', 'management']`
 261
 262 Valid options: A list of Karaf feature names as strings.
 263
 264 ##### `extra_features`
 265
 266 Specifies Karaf features to install in addition to the defaults listed in
 267 `default_features`.
 268
 269 You will likely need to customize this to your use-case.
 270
 271 Default: `[]`
 272
 273 Valid options: A list of Karaf feature names as strings.
 274
 275 ##### `install_method `
 276
 277 Specifies the install method by which to install OpenDaylight.
 278
 279 The RPM install method is less complex, more frequently consumed and
 280 recommended.
 281
 282 Default: `'rpm'`
 283
 284 Valid options: The strings `'tarball'` or `'rpm'`.
 285
 286 ##### `odl_rest_port `
 287
 288 Specifies the port for the ODL northbound REST interface to listen on.
 289
 290 Default: `'8080'`
 291
 292 Valid options: A valid port number as a string or integer.
 293
 294 ##### `log_levels`
 295
 296 Custom OpenDaylight logger verbosity configuration.
 297
 298 Default: `{}`
 299
 300 Valid options: A hash of loggers to log levels.
 301
 302 ```
 303 { 'org.opendaylight.ovsdb' => 'TRACE', 'org.opendaylight.ovsdb.lib' => 'INFO' }
 304 ```
 305
 306 Valid log levels are TRACE, DEBUG, INFO, WARN, and ERROR.
 307
 308 The above example would add the following logging configuration to
 309 `/opt/opendaylight/etc/org.ops4j.pax.logging.cfg`.
 310
 311 ```
 312 # Log level config added by puppet-opendaylight
 313 log4j.logger.org.opendaylight.ovsdb = TRACE
 314
 315 # Log level config added by puppet-opendaylight
 316 log4j.logger.org.opendaylight.ovsdb.lib = INFO
 317 ```
 318
 319 To view loggers and their verbosity levels, use `log:list` at the ODL Karaf shell.
 320
 321 ```
 322 opendaylight-user@root>log:list
 323 Logger                     | Level
 324 ----------------------------------
 325 ROOT                       | INFO
 326 org.opendaylight.ovsdb     | TRACE
 327 org.opendaylight.ovsdb.lib | INFO
 328 ```
 329
 330 The main log output file is `/opt/opendaylight/data/log/karaf.log`.
 331
 332 ##### `enable_l3`
 333
 334 Enable or disable ODL OVSDB L3 forwarding.
 335
 336 Default: `'no'`
 337
 338 Valid options: The strings `'yes'` or `'no'` or boolean values `true` and `false`.
 339
 340 The ODL OVSDB L3 config in `/opt/opendaylight/etc/custom.properties` is set to
 341 the value of the `enable_l3` param.
 342
 343 A manifest like
 344
 345 ```puppet
 346 class { 'opendaylight':
 347   enable_l3 => true,
 348 }
 349 ```
 350
 351 Would would result in
 352
 353 ```
 354 ovsdb.l3.fwd.enabled=yes
 355 ovsdb.l3.arp.responder.disabled=no
 356 ```
 357
 358 ##### `enable_ha`
 359
 360 Enable or disable ODL OVSDB High Availablity.
 361
 362 Default: `false`
 363
 364 Valid options: The boolean values `true` and `false`.
 365
 366 Requires: `ha_node_ips`, `ha_node_index`
 367
 368 The ODL OVSDB Clustering and Jolokia XML for HA are configured and enabled.
 369
 370 ##### `ha_node_ips`
 371
 372 Specifies the IPs that are part of the HA cluster enabled by `enable_ha`.
 373
 374 Default: []
 375
 376 Valid options: An array of IP addresses `['10.10.10.1', '10.10.10.1', '10.10.10.3']`.
 377
 378 Required by: `enable_ha`
 379
 380 ##### `ha_node_index`
 381
 382 Specifies the index of the IP for the node being configured from the array `ha_node_ips`.
 383
 384 Default: ''
 385
 386 Valid options: Index of a member of the array `ha_node_ips`: `0`.
 387
 388 Required by: `enable_ha`, `ha_node_ips`
 389
 390
 391 ##### `tarball_url`
 392
 393 Specifies the ODL tarball to use when installing via the tarball install
 394 method.
 395
 396 Default: `'https://nexus.opendaylight.org/content/repositories/opendaylight.release/org/opendaylight/integration/distribution-karaf/0.3.2-Lithium-SR2/distribution-karaf-0.3.2-Lithium-SR2.tar.gz'`
 397
 398 Valid options: A valid URL to an ODL tarball as a string.
 399
 400 ##### `unitfile_url`
 401
 402 Specifies the ODL systemd .service file to use when installing via the tarball
 403 install method.
 404
 405 It's very unlikely that you'll need to override this.
 406
 407 Default: `'https://github.com/dfarrell07/opendaylight-systemd/archive/master/opendaylight-unitfile.tar.gz'`
 408
 409 Valid options: A valid URL to an ODL systemd .service file (archived in a
 410 tarball) as a string.
 411
 412 ##### `security_group_mode`
 413
 414 Specifies the mode to use for security groups.
 415
 416 Default: `stateful`
 417
 418 Valid options: `transparent`, `learn`, `statless`
 419
 420 ## Limitations
 421
 422 * Tested on Fedora 22, 23, CentOS 7 and Ubuntu 14.04.
 423 * CentOS 7 is currently the most stable OS option.
 424 * The RPM install method is likely more reliable than the tarball install
 425 method.
 426
 427 ## Development
 428
 429 We welcome contributions and work to make them easy!
 430
 431 See [CONTRIBUTING.markdown][14] for details about how to contribute to the
 432 OpenDaylight Puppet module.
 433
 434 ## Release Notes/Contributors
 435
 436 See the [CHANGELOG][15] or our [git tags][16] for information about releases.
 437 See our [git commit history][17] for contributor information.
 438
 439
 440 [1]: https://travis-ci.org/dfarrell07/puppet-opendaylight
 441 [2]: https://gemnasium.com/dfarrell07/puppet-opendaylight
 442 [4]: https://travis-ci.org/dfarrell07/puppet-opendaylight.svg
 443 [5]: https://gemnasium.com/dfarrell07/puppet-opendaylight.svg
 444 [7]: http://www.opendaylight.org/
 445 [8]: https://github.com/dfarrell07/puppet-opendaylight/blob/master/CONTRIBUTING.markdown#issues
 446 [9]: https://github.com/dfarrell07/opendaylight-systemd/
 447 [10]: https://github.com/dfarrell07/puppet-opendaylight/blob/master/files/upstart.odl.conf
 448 [11]: https://github.com/dfarrell07/vagrant-opendaylight/
 449 [12]: https://github.com/dfarrell07/vagrant-opendaylight/tree/master/manifests
 450 [13]: https://github.com/dfarrell07/puppet-opendaylight/issues/63
 451 [14]: https://github.com/dfarrell07/puppet-opendaylight/blob/master/CONTRIBUTING.markdown
 452 [15]: https://github.com/dfarrell07/puppet-opendaylight/blob/master/CHANGELOG
 453 [16]: https://github.com/dfarrell07/puppet-opendaylight/releases
 454 [17]: https://github.com/dfarrell07/puppet-opendaylight/commits/master
 455 [18]: http://cbs.centos.org/repos/nfv7-opendaylight-40-release/x86_64/os/Packages/ OpenDaylight Beryllium CentOS CBS repo
 456 [19]: https://wiki.opendaylight.org/view/Deployment#RPM OpenDaylight RPMs and their repos