README.markdown

   1 [![CI Status][4]][1]
   2 [![Dependency Status][5]][2]
   3 [![Project Chatroom][6]][3]
   4
   5 # OpenDaylight
   6
   7 #### Table of Contents
   8 1. [Overview](#overview)
   9 1. [Module Description](#module-description)
  10 1. [Setup](#setup)
  11   * [What `opendaylight` affects](#what-opendaylight-affects)
  12   * [Beginning with `opendaylight`](#beginning-with-opendaylight)
  13 1. [Usage](#usage)
  14   * [Karaf Features](#karaf-features)
  15   * [Install Method](#install-method)
  16   * [Ports](#ports)
  17   * [Log Verbosity](#log-verbosity)
  18   * [Enabling ODL OVSDB L3](#enabling-odl-ovsdb-l3)
  19 1. [Reference ](#reference)
  20 1. [Limitations](#limitations)
  21 1. [Development](#development)
  22 1. [Release Notes/Contributors](#release-notescontributors)
  23
  24 ## Overview
  25
  26 Puppet module that installs and configures the [OpenDaylight Software Defined
  27 Networking (SDN) controller][7].
  28
  29 ## Module Description
  30
  31 Deploys OpenDaylight to various OSs either via an RPM or directly from the
  32 ODL tarball release artifact.
  33
  34 All OpenDaylight configuration should be handled through the ODL Puppet
  35 module's [params](#parameters). If you need a new knob, [please raise an
  36 Issue][8].
  37
  38 Both supported [install methods](#install-method) default to the latest
  39 stable OpenDaylight release, which is currently [a Beryllium ERP][18].
  40
  41 ## Setup
  42
  43 ### What `opendaylight` affects
  44
  45 * Installs Java, which is required by ODL.
  46 * Creates `odl:odl` user:group if they don't already exist.
  47 * Installs [OpenDaylight][7].
  48 * Installs a [systemd unitfile][9] or [Upstart config file][10] for
  49 OpenDaylight.
  50 * Manipulates OpenDaylight's configuration files according to the params
  51 passed to the `::opendaylight` class.
  52 * Starts the `opendaylight` systemd or Upstart service.
  53
  54 ### Beginning with `opendaylight`
  55
  56 Getting started with the OpenDaylight Puppet module is as simple as declaring
  57 the `::opendaylight` class.
  58
  59 The [vagrant-opendaylight][11] project provides an easy way to experiment
  60 with [applying the ODL Puppet module][12] to CentOS 7, Fedora 22 and Fedora
  61 23 Vagrant boxes.
  62
  63 ```
  64 [~/vagrant-opendaylight]$ vagrant status
  65 Current machine states:
  66
  67 cent7                     not created (libvirt)
  68 cent7_rpm_he_sr4          not created (libvirt)
  69 cent7_rpm_li_sr2          not created (libvirt)
  70 cent7_rpm_be              not created (libvirt)
  71 cent7_ansible             not created (libvirt)
  72 cent7_ansible_be          not created (libvirt)
  73 cent7_ansible_path        not created (libvirt)
  74 cent7_pup_rpm             not created (libvirt)
  75 cent7_pup_custom_logs     not created (libvirt)
  76 cent7_pup_tb              not created (libvirt)
  77 f22_rpm_li                not created (libvirt)
  78 f22_ansible               not created (libvirt)
  79 f22_pup_rpm               not created (libvirt)
  80 f23_rpm_li                not created (libvirt)
  81 f23_rpm_li_sr1            not created (libvirt)
  82 f23_rpm_li_sr2            not created (libvirt)
  83 f23_rpm_li_sr3            not created (libvirt)
  84 f23_rpm_be                not created (libvirt)
  85 f23_ansible               not created (libvirt)
  86 f23_pup_rpm               not created (libvirt)
  87
  88 [~/vagrant-opendaylight]$ vagrant up cent7_pup_rpm
  89 # A CentOS 7 VM is created and configured using the ODL Puppet mod's defaults
  90 [~/vagrant-opendaylight]$ vagrant ssh cent7_pup_rpm
  91 [vagrant@localhost ~]$ sudo systemctl is-active opendaylight
  92 active
  93 ```
  94
  95 ## Usage
  96
  97 The most basic usage, passing no parameters to the OpenDaylight class, will
  98 install and start OpenDaylight with a default configuration.
  99
 100 ```puppet
 101 class { 'opendaylight':
 102 }
 103 ```
 104
 105 ### Karaf Features
 106
 107 To set extra Karaf features to be installed at OpenDaylight start time, pass
 108 them in a list to the `extra_features` param. The extra features you pass will
 109 typically be driven by the requirements of your ODL install. You'll almost
 110 certainly need to pass some.
 111
 112 ```puppet
 113 class { 'opendaylight':
 114   extra_features => ['odl-ovsdb-plugin', 'odl-ovsdb-openstack'],
 115 }
 116 ```
 117
 118 OpenDaylight normally installs a default set of Karaf features at boot. They
 119 are recommended, so the ODL Puppet mod defaults to installing them. This can
 120 be customized by overriding the `default_features` param. You shouldn't
 121 normally need to do so.
 122
 123 ```puppet
 124 class { 'opendaylight':
 125   default_features => ['config', 'standard', 'region', 'package', 'kar', 'ssh', 'management'],
 126 }
 127 ```
 128
 129 ### Install Method
 130
 131 The `install_method` param, and the associated `tarball_url` and `unitfile_url`
 132 params, are intended for use by developers who need to install a custom-built
 133 version of OpenDaylight, or for automated build processes that need to consume
 134 a tarball build artifact.
 135
 136 It's recommended that most people use the default RPM-based install.
 137
 138 If you do need to install from a tarball, simply pass `tarball` as the value
 139 for `install_method` and optionally pass the URL to your tarball via the
 140 `tarball_url` param. The default value for `tarball_url` points at
 141 OpenDaylight's latest release. The `unitfile_url` param points at the
 142 OpenDaylight systemd .service file used by the RPM and should (very likely)
 143 not need to be overridden.
 144
 145 ```puppet
 146 class { 'opendaylight':
 147   install_method => 'tarball',
 148   tarball_url    => '<URL to your custom tarball>',
 149   unitfile_url   => '<URL to your custom unitfile>',
 150 }
 151 ```
 152
 153 ### Ports
 154
 155 To change the port on which OpenDaylight's northbound listens for REST API
 156 calls, use the `odl_rest_port` param.
 157
 158
 159 ```puppet
 160 class { 'opendaylight':
 161   odl_rest_port => '8080',
 162 }
 163 ```
 164
 165 ### Log Verbosity
 166
 167 It's possible to define custom logger verbosity levels via the `log_levels`
 168 param.
 169
 170 ```puppet
 171 class { 'opendaylight':
 172   log_levels => { 'org.opendaylight.ovsdb' => 'TRACE', 'org.opendaylight.ovsdb.lib' => 'INFO' },
 173 }
 174 ```
 175
 176 ### Enabling ODL OVSDB L3
 177
 178 To enable the ODL OVSDB L3, use the `enable_l3` flag. It's disabled by default.
 179
 180 ```puppet
 181 class { 'opendaylight':
 182   enable_l3 => 'yes',
 183 }
 184 ```
 185
 186 ## Reference
 187
 188 ### Classes
 189
 190 #### Public classes
 191
 192 * `::opendaylight`: Main entry point to the module. All ODL knobs should be
 193 managed through its params.
 194
 195 #### Private classes
 196
 197 * `::opendaylight::params`: Contains default `opendaylight` class param values.
 198 * `::opendaylight::install`: Installs ODL from an RPM or tarball.
 199 * `::opendaylight::config`: Manages ODL config, including Karaf features and
 200 REST port.
 201 * `::opendaylight::service`: Starts the OpenDaylight service.
 202
 203 ### `::opendaylight`
 204
 205 #### Parameters
 206
 207 ##### `default_features`
 208
 209 Sets the Karaf features to install by default. These should not normally need
 210 to be overridden.
 211
 212 Default: `['config', 'standard', 'region', 'package', 'kar', 'ssh', 'management']`
 213
 214 Valid options: A list of Karaf feature names as strings.
 215
 216 ##### `extra_features`
 217
 218 Specifies Karaf features to install in addition to the defaults listed in
 219 `default_features`.
 220
 221 You will likely need to customize this to your use-case.
 222
 223 Default: `[]`
 224
 225 Valid options: A list of Karaf feature names as strings.
 226
 227 ##### `install_method `
 228
 229 Specifies the install method by which to install OpenDaylight.
 230
 231 The RPM install method is less complex, more frequently consumed and
 232 recommended.
 233
 234 Default: `'rpm'`
 235
 236 Valid options: The strings `'tarball'` or `'rpm'`.
 237
 238 ##### `odl_rest_port `
 239
 240 Specifies the port for the ODL northbound REST interface to listen on.
 241
 242 Default: `'8080'`
 243
 244 Valid options: A valid port number as a string or integer.
 245
 246 ##### `log_levels`
 247
 248 Custom OpenDaylight logger verbosity configuration.
 249
 250 Default: `{}`
 251
 252 Valid options: A hash of loggers to log levels.
 253
 254 ```
 255 { 'org.opendaylight.ovsdb' => 'TRACE', 'org.opendaylight.ovsdb.lib' => 'INFO' }
 256 ```
 257
 258 Valid log levels are TRACE, DEBUG, INFO, WARN, and ERROR.
 259
 260 The above example would add the following logging configuration to
 261 `/opt/opendaylight/etc/org.ops4j.pax.logging.cfg`.
 262
 263 ```
 264 # Log level config added by puppet-opendaylight
 265 log4j.logger.org.opendaylight.ovsdb = TRACE
 266
 267 # Log level config added by puppet-opendaylight
 268 log4j.logger.org.opendaylight.ovsdb.lib = INFO
 269 ```
 270
 271 To view loggers and their verbosity levels, use `log:list` at the ODL Karaf shell.
 272
 273 ```
 274 opendaylight-user@root>log:list
 275 Logger                     | Level
 276 ----------------------------------
 277 ROOT                       | INFO
 278 org.opendaylight.ovsdb     | TRACE
 279 org.opendaylight.ovsdb.lib | INFO
 280 ```
 281
 282 The main log output file is `/opt/opendaylight/data/log/karaf.log`.
 283
 284 ##### `enable_l3`
 285
 286 Enable or disable ODL OVSDB L3 forwarding.
 287
 288 Default: `'no'`
 289
 290 Valid options: The strings 'yes' or 'no'.
 291
 292 Boolean values are not currently supported, but that feature may be added.
 293
 294 The ODL OVSDB L3 config in `/opt/opendaylight/etc/custom.properties` is set to
 295 the value of the `enable_l3` param.
 296
 297 A manifest like
 298
 299 ```puppet
 300 class { 'opendaylight':
 301   enable_l3 => 'yes',
 302 }
 303 ```
 304
 305 Would would result in
 306
 307 ```
 308 ovsdb.l3.fwd.enabled=yes
 309 ```
 310
 311 ##### `tarball_url`
 312
 313 Specifies the ODL tarball to use when installing via the tarball install
 314 method.
 315
 316 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'`
 317
 318 Valid options: A valid URL to an ODL tarball as a string.
 319
 320 ##### `unitfile_url`
 321
 322 Specifies the ODL systemd .service file to use when installing via the tarball
 323 install method.
 324
 325 It's very unlikely that you'll need to override this.
 326
 327 Default: `'https://github.com/dfarrell07/opendaylight-systemd/archive/master/opendaylight-unitfile.tar.gz'`
 328
 329 Valid options: A valid URL to an ODL systemd .service file (archived in a
 330 tarball) as a string.
 331
 332 ## Limitations
 333
 334 * Tested on Fedora 22, 23, CentOS 7 and Ubuntu 14.04.
 335 * CentOS 7 is currently the most stable OS option.
 336 * The RPM install method is likely more reliable than the tarball install
 337 method.
 338
 339 ## Development
 340
 341 We welcome contributions and work to make them easy!
 342
 343 See [CONTRIBUTING.markdown][14] for details about how to contribute to the
 344 OpenDaylight Puppet module.
 345
 346 ## Release Notes/Contributors
 347
 348 See the [CHANGELOG][15] or our [git tags][16] for information about releases.
 349 See our [git commit history][17] for contributor information.
 350
 351
 352 [1]: https://travis-ci.org/dfarrell07/puppet-opendaylight
 353 [2]: https://gemnasium.com/dfarrell07/puppet-opendaylight
 354 [3]: https://gitter.im/dfarrell07/puppet-opendaylight?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
 355 [4]: https://travis-ci.org/dfarrell07/puppet-opendaylight.svg
 356 [5]: https://gemnasium.com/dfarrell07/puppet-opendaylight.svg
 357 [6]: https://badges.gitter.im/Join%20Chat.svg
 358 [7]: http://www.opendaylight.org/
 359 [8]: https://github.com/dfarrell07/puppet-opendaylight/blob/master/CONTRIBUTING.markdown#issues
 360 [9]: https://github.com/dfarrell07/opendaylight-systemd/
 361 [10]: https://github.com/dfarrell07/puppet-opendaylight/blob/master/files/upstart.odl.conf
 362 [11]: https://github.com/dfarrell07/vagrant-opendaylight/
 363 [12]: https://github.com/dfarrell07/vagrant-opendaylight/tree/master/manifests
 364 [13]: https://github.com/dfarrell07/puppet-opendaylight/issues/63
 365 [14]: https://github.com/dfarrell07/puppet-opendaylight/blob/master/CONTRIBUTING.markdown
 366 [15]: https://github.com/dfarrell07/puppet-opendaylight/blob/master/CHANGELOG
 367 [16]: https://github.com/dfarrell07/puppet-opendaylight/releases
 368 [17]: https://github.com/dfarrell07/puppet-opendaylight/commits/master
 369 [18]: http://cbs.centos.org/repos/nfv7-opendaylight-4-testing/x86_64/os/Packages/