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