README.markdown

   1 [![CI Status][4]][1]
   2 [![Dependency Status][5]][2]
   3
   4 # OpenDaylight
   5
   6 #### Table of Contents
   7
   8 1. [Overview](#overview)
   9 2. [Module Description](#module-description)
  10 3. [Setup](#setup)
  11   - [What `opendaylight` affects](#what-opendaylight-affects)
  12   - [Beginning with `opendaylight`](#beginning-with-opendaylight)
  13 4. [Usage](#usage)
  14   - [Karaf Features](#karaf-features)
  15   - [Install Method](#install-method)
  16   - [RPM Repo](#rpm-repo)
  17   - [Ports](#ports)
  18   - [Log Verbosity](#log-verbosity)
  19   - [Enabling ODL OVSDB L3](#enabling-odl-ovsdb-l3)
  20   - [Enabling ODL OVSDB HA](#enabling-odl-ovsdb-ha)
  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][7].
  30
  31 ## Module Description
  32
  33 Deploys OpenDaylight to various OSs either via an RPM or directly from the
  34 ODL tarball release artifact.
  35
  36 All OpenDaylight configuration should be handled through the ODL Puppet
  37 module's [params](#parameters). If you need a new knob, [please raise an
  38 Issue][8].
  39
  40 The master branch installs OpenDaylight from the latest testing RPM repository
  41 by default. There are stable/<release> branches that install OpenDaylight
  42 releases and service releases, like Beryllium or Beryllium SR3.
  43
  44 ## Setup
  45
  46 ### What `opendaylight` affects
  47
  48 - Installs Java, which is required by ODL.
  49 - Creates `odl:odl` user:group if they don't already exist.
  50 - Installs [OpenDaylight][7].
  51 - Installs a [systemd unitfile][9] or [Upstart config file][10] for
  52   OpenDaylight.
  53 - Manipulates OpenDaylight's configuration files according to the params
  54   passed to the `::opendaylight` class.
  55 - Starts the `opendaylight` systemd or Upstart service.
  56
  57 ### Beginning with `opendaylight`
  58
  59 Getting started with the OpenDaylight Puppet module is as simple as declaring
  60 the `::opendaylight` class.
  61
  62 The [vagrant-opendaylight][11] project provides an easy way to experiment
  63 with [applying the ODL Puppet module][12] to CentOS 7, Fedora 22 and Fedora
  64 23 Vagrant boxes.
  65
  66 ```
  67 [~/vagrant-opendaylight]$ vagrant status
  68 Current machine states:
  69
  70 cent7                     not created (libvirt)
  71 cent7_rpm_he_sr4          not created (libvirt)
  72 cent7_rpm_li_sr2          not created (libvirt)
  73 cent7_rpm_be              not created (libvirt)
  74 cent7_ansible             not created (libvirt)
  75 cent7_ansible_be          not created (libvirt)
  76 cent7_ansible_path        not created (libvirt)
  77 cent7_pup_rpm             not created (libvirt)
  78 cent7_pup_custom_logs     not created (libvirt)
  79 cent7_pup_tb              not created (libvirt)
  80 f22_rpm_li                not created (libvirt)
  81 f22_ansible               not created (libvirt)
  82 f22_pup_rpm               not created (libvirt)
  83 f23_rpm_li                not created (libvirt)
  84 f23_rpm_li_sr1            not created (libvirt)
  85 f23_rpm_li_sr2            not created (libvirt)
  86 f23_rpm_li_sr3            not created (libvirt)
  87 f23_rpm_be                not created (libvirt)
  88 f23_ansible               not created (libvirt)
  89 f23_pup_rpm               not created (libvirt)
  90
  91 [~/vagrant-opendaylight]$ vagrant up cent7_pup_rpm
  92 # A CentOS 7 VM is created and configured using the ODL Puppet mod's defaults
  93 [~/vagrant-opendaylight]$ vagrant ssh cent7_pup_rpm
  94 [vagrant@localhost ~]$ sudo systemctl is-active opendaylight
  95 active
  96 ```
  97
  98 ## Usage
  99
 100 The most basic usage, passing no parameters to the OpenDaylight class, will
 101 install and start OpenDaylight with a default configuration.
 102
 103 ```puppet
 104 class { 'opendaylight':
 105 }
 106 ```
 107
 108 ### Karaf Features
 109
 110 To set extra Karaf features to be installed at OpenDaylight start time, pass
 111 them in a list to the `extra_features` param. The extra features you pass will
 112 typically be driven by the requirements of your ODL install. You'll almost
 113 certainly need to pass some.
 114
 115 ```puppet
 116 class { 'opendaylight':
 117   extra_features => ['odl-ovsdb-plugin', 'odl-ovsdb-openstack'],
 118 }
 119 ```
 120
 121 OpenDaylight normally installs a default set of Karaf features at boot. They
 122 are recommended, so the ODL Puppet mod defaults to installing them. This can
 123 be customized by overriding the `default_features` param. You shouldn't
 124 normally need to do so.
 125
 126 ```puppet
 127 class { 'opendaylight':
 128   default_features => ['config', 'standard', 'region', 'package', 'kar', 'ssh', 'management'],
 129 }
 130 ```
 131
 132 ### Install Method
 133
 134 The `install_method` param, and the associated `tarball_url` and `unitfile_url`
 135 params, are intended for use by developers who need to install a custom-built
 136 version of OpenDaylight, or for automated build processes that need to consume
 137 a tarball build artifact.
 138
 139 It's recommended that most people use the default RPM-based install.
 140
 141 If you do need to install from a tarball, simply pass `tarball` as the value
 142 for `install_method` and optionally pass the URL to your tarball via the
 143 `tarball_url` param. The default value for `tarball_url` points at
 144 OpenDaylight's latest release. The `unitfile_url` param points at the
 145 OpenDaylight systemd .service file used by the RPM and should (very likely)
 146 not need to be overridden.
 147
 148 ```puppet
 149 class { 'opendaylight':
 150   install_method => 'tarball',
 151   tarball_url    => '<URL to your custom tarball>',
 152   unitfile_url   => '<URL to your custom unitfile>',
 153 }
 154 ```
 155
 156 ### RPM Repo
 157
 158 The `rpm_repo` param can be used to configure which RPM repository
 159 OpenDaylight is installed from.
 160
 161 ```puppet
 162 class { 'opendaylight':
 163   rpm_repo => 'opendaylight-40-release',
 164 }
 165 ```
 166
 167 The naming convention follows the naming convention of the CentOS Community
 168 Build System, which is where upstream ODL hosts its RPMs. The
 169 `opendaylight-40-release` example above would install OpenDaylight Beryllium
 170 4.0.0 from the [nfv7-opendaylight-40-release][18] repo. Repo names ending in
 171 `-release` will always contain well-tested, officially released versions of
 172 OpenDaylight. Repos ending in `-testing` contain frequent, but unstable and
 173 unofficial, releases. The ODL version given in repo names shows which major
 174 and minor version it is pinned to. The `opendaylight-40-release` repo will
 175 always provide OpenDaylight Beryllium 4.0, whereas `opendaylight-4-release`
 176 will provide the latest release with major version 4 (which could include
 177 Service Releases, like SR2 4.2).
 178
 179 For a full list of OpenDaylight releases and their CBS repos, see the
 180 [OpenDaylight Deployment wiki][19].
 181
 182 This is only read when `install_method` is `rpm`.
 183
 184 ### Ports
 185
 186 To change the port on which OpenDaylight's northbound listens for REST API
 187 calls, use the `odl_rest_port` param.
 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 ### Enabling 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 ##### `tarball_url`
 391
 392 Specifies the ODL tarball to use when installing via the tarball install
 393 method.
 394
 395 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'`
 396
 397 Valid options: A valid URL to an ODL tarball as a string.
 398
 399 ##### `unitfile_url`
 400
 401 Specifies the ODL systemd .service file to use when installing via the tarball
 402 install method.
 403
 404 It's very unlikely that you'll need to override this.
 405
 406 Default: `'https://github.com/dfarrell07/opendaylight-systemd/archive/master/opendaylight-unitfile.tar.gz'`
 407
 408 Valid options: A valid URL to an ODL systemd .service file (archived in a
 409 tarball) as a string.
 410
 411 ##### `security_group_mode`
 412
 413 Specifies the mode to use for security groups.
 414
 415 Default: `stateful`
 416
 417 Valid options: `transparent`, `learn`, `statless`
 418
 419 ## Limitations
 420
 421 - Tested on Fedora 22, 23, CentOS 7 and Ubuntu 14.04.
 422 - CentOS 7 is currently the most stable OS option.
 423 - The RPM install method is likely more reliable than the tarball install
 424   method.
 425
 426 ## Development
 427
 428 We welcome contributions and work to make them easy!
 429
 430 See [CONTRIBUTING.markdown][14] for details about how to contribute to the
 431 OpenDaylight Puppet module.
 432
 433 ## Release Notes/Contributors
 434
 435 See the [CHANGELOG][15] or our [git tags][16] for information about releases.
 436 See our [git commit history][17] for contributor information.
 437
 438 [1]: https://travis-ci.org/dfarrell07/puppet-opendaylight
 439
 440 [2]: https://gemnasium.com/dfarrell07/puppet-opendaylight
 441
 442 [4]: https://travis-ci.org/dfarrell07/puppet-opendaylight.svg
 443
 444 [5]: https://gemnasium.com/dfarrell07/puppet-opendaylight.svg
 445
 446 [7]: http://www.opendaylight.org/
 447
 448 [8]: https://github.com/dfarrell07/puppet-opendaylight/blob/master/CONTRIBUTING.markdown#issues
 449
 450 [9]: https://github.com/dfarrell07/opendaylight-systemd/
 451
 452 [10]: https://github.com/dfarrell07/puppet-opendaylight/blob/master/files/upstart.odl.conf
 453
 454 [11]: https://github.com/dfarrell07/vagrant-opendaylight/
 455
 456 [12]: https://github.com/dfarrell07/vagrant-opendaylight/tree/master/manifests
 457
 458 [13]: https://github.com/dfarrell07/puppet-opendaylight/issues/63
 459
 460 [14]: https://github.com/dfarrell07/puppet-opendaylight/blob/master/CONTRIBUTING.markdown
 461
 462 [15]: https://github.com/dfarrell07/puppet-opendaylight/blob/master/CHANGELOG
 463
 464 [16]: https://github.com/dfarrell07/puppet-opendaylight/releases
 465
 466 [17]: https://github.com/dfarrell07/puppet-opendaylight/commits/master
 467
 468 [18]&#x3A; <http://cbs.centos.org/repos/nfv7-opendaylight-40-release/x86_64/os/Packages/> OpenDaylight Beryllium CentOS CBS repo
 469 [19]&#x3A; <https://wiki.opendaylight.org/view/Deployment#RPM> OpenDaylight RPMs and their repos