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 HA](#enabling-odl-ovsdb-ha)
  20 5. [Reference ](#reference)
  21 6. [Limitations](#limitations)
  22 7. [Development](#development)
  23 8. [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 ```puppet
 189 class { 'opendaylight':
 190   odl_rest_port => '8080',
 191 }
 192 ```
 193
 194 ### Log Verbosity
 195
 196 It's possible to define custom logger verbosity levels via the `log_levels`
 197 param.
 198
 199 ```puppet
 200 class { 'opendaylight':
 201   log_levels => { 'org.opendaylight.ovsdb' => 'TRACE', 'org.opendaylight.ovsdb.lib' => 'INFO' },
 202 }
 203 ```
 204
 205 ### Enabling ODL OVSDB HA
 206
 207 To enable ODL OVSDB HA, use the `enable_ha` flag. It's disabled by default.
 208
 209 When `enable_ha` is set to true the `ha_node_ips` should be populated with the
 210 IP addresses that ODL will listen on for each node in the OVSDB HA cluster and
 211 `ha_node_index` should be set with the index of the IP address from
 212 `ha_node_ips` for the particular node that puppet is configuring as part of the
 213 HA cluster.
 214
 215 ```puppet
 216 class { 'opendaylight':
 217   enable_ha     => true,
 218   ha_node_ips   => ['10.10.10.1', '10.10.10.1', '10.10.10.3'],
 219   ha_node_index => 0,
 220 }
 221 ```
 222
 223 ## Reference
 224
 225 ### Classes
 226
 227 #### Public classes
 228
 229 - `::opendaylight`: Main entry point to the module. All ODL knobs should be
 230   managed through its params.
 231
 232 #### Private classes
 233
 234 - `::opendaylight::params`: Contains default `opendaylight` class param values.
 235 - `::opendaylight::install`: Installs ODL from an RPM or tarball.
 236 - `::opendaylight::config`: Manages ODL config, including Karaf features and
 237   REST port.
 238 - `::opendaylight::service`: Starts the OpenDaylight service.
 239
 240 ### `::opendaylight`
 241
 242 #### Parameters
 243
 244 ##### `default_features`
 245
 246 Sets the Karaf features to install by default. These should not normally need
 247 to be overridden.
 248
 249 Default: `['config', 'standard', 'region', 'package', 'kar', 'ssh', 'management']`
 250
 251 Valid options: A list of Karaf feature names as strings.
 252
 253 ##### `extra_features`
 254
 255 Specifies Karaf features to install in addition to the defaults listed in
 256 `default_features`.
 257
 258 You will likely need to customize this to your use-case.
 259
 260 Default: `[]`
 261
 262 Valid options: A list of Karaf feature names as strings.
 263
 264 ##### `install_method`
 265
 266 Specifies the install method by which to install OpenDaylight.
 267
 268 The RPM install method is less complex, more frequently consumed and
 269 recommended.
 270
 271 Default: `'rpm'`
 272
 273 Valid options: The strings `'tarball'` or `'rpm'`.
 274
 275 ##### `odl_rest_port`
 276
 277 Specifies the port for the ODL northbound REST interface to listen on.
 278
 279 Default: `'8080'`
 280
 281 Valid options: A valid port number as a string or integer.
 282
 283 ##### `log_levels`
 284
 285 Custom OpenDaylight logger verbosity configuration.
 286
 287 Default: `{}`
 288
 289 Valid options: A hash of loggers to log levels.
 290
 291 ```
 292 { 'org.opendaylight.ovsdb' => 'TRACE', 'org.opendaylight.ovsdb.lib' => 'INFO' }
 293 ```
 294
 295 Valid log levels are TRACE, DEBUG, INFO, WARN, and ERROR.
 296
 297 The above example would add the following logging configuration to
 298 `/opt/opendaylight/etc/org.ops4j.pax.logging.cfg`.
 299
 300 ```
 301 # Log level config added by puppet-opendaylight
 302 log4j.logger.org.opendaylight.ovsdb = TRACE
 303
 304 # Log level config added by puppet-opendaylight
 305 log4j.logger.org.opendaylight.ovsdb.lib = INFO
 306 ```
 307
 308 To view loggers and their verbosity levels, use `log:list` at the ODL Karaf shell.
 309
 310 ```
 311 opendaylight-user@root>log:list
 312 Logger                     | Level
 313 ----------------------------------
 314 ROOT                       | INFO
 315 org.opendaylight.ovsdb     | TRACE
 316 org.opendaylight.ovsdb.lib | INFO
 317 ```
 318
 319 The main log output file is `/opt/opendaylight/data/log/karaf.log`.
 320
 321 ##### `enable_ha`
 322
 323 Enable or disable ODL OVSDB High Availablity.
 324
 325 Default: `false`
 326
 327 Valid options: The boolean values `true` and `false`.
 328
 329 Requires: `ha_node_ips`, `ha_node_index`
 330
 331 The ODL OVSDB Clustering and Jolokia XML for HA are configured and enabled.
 332
 333 ##### `ha_node_ips`
 334
 335 Specifies the IPs that are part of the HA cluster enabled by `enable_ha`.
 336
 337 Default: \[]
 338
 339 Valid options: An array of IP addresses `['10.10.10.1', '10.10.10.1', '10.10.10.3']`.
 340
 341 Required by: `enable_ha`
 342
 343 ##### `ha_node_index`
 344
 345 Specifies the index of the IP for the node being configured from the array `ha_node_ips`.
 346
 347 Default: ''
 348
 349 Valid options: Index of a member of the array `ha_node_ips`: `0`.
 350
 351 Required by: `enable_ha`, `ha_node_ips`
 352
 353 ##### `tarball_url`
 354
 355 Specifies the ODL tarball to use when installing via the tarball install
 356 method.
 357
 358 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'`
 359
 360 Valid options: A valid URL to an ODL tarball as a string.
 361
 362 ##### `unitfile_url`
 363
 364 Specifies the ODL systemd .service file to use when installing via the tarball
 365 install method.
 366
 367 It's very unlikely that you'll need to override this.
 368
 369 Default: `'https://github.com/dfarrell07/opendaylight-systemd/archive/master/opendaylight-unitfile.tar.gz'`
 370
 371 Valid options: A valid URL to an ODL systemd .service file (archived in a
 372 tarball) as a string.
 373
 374 ##### `security_group_mode`
 375
 376 Specifies the mode to use for security groups.
 377
 378 Default: `stateful`
 379
 380 Valid options: `transparent`, `learn`, `statless`
 381
 382 ## Limitations
 383
 384 - Tested on Fedora 22, 23, CentOS 7 and Ubuntu 14.04.
 385 - CentOS 7 is currently the most stable OS option.
 386 - The RPM install method is likely more reliable than the tarball install
 387   method.
 388
 389 ## Development
 390
 391 We welcome contributions and work to make them easy!
 392
 393 See [CONTRIBUTING.markdown][14] for details about how to contribute to the
 394 OpenDaylight Puppet module.
 395
 396 ## Release Notes/Contributors
 397
 398 See the [CHANGELOG][15] or our [git tags][16] for information about releases.
 399 See our [git commit history][17] for contributor information.
 400
 401 [1]: https://travis-ci.org/dfarrell07/puppet-opendaylight
 402
 403 [2]: https://gemnasium.com/dfarrell07/puppet-opendaylight
 404
 405 [4]: https://travis-ci.org/dfarrell07/puppet-opendaylight.svg
 406
 407 [5]: https://gemnasium.com/dfarrell07/puppet-opendaylight.svg
 408
 409 [7]: http://www.opendaylight.org/
 410
 411 [8]: https://github.com/dfarrell07/puppet-opendaylight/blob/master/CONTRIBUTING.markdown#issues
 412
 413 [9]: https://github.com/dfarrell07/opendaylight-systemd/
 414
 415 [10]: https://github.com/dfarrell07/puppet-opendaylight/blob/master/files/upstart.odl.conf
 416
 417 [11]: https://github.com/dfarrell07/vagrant-opendaylight/
 418
 419 [12]: https://github.com/dfarrell07/vagrant-opendaylight/tree/master/manifests
 420
 421 [13]: https://github.com/dfarrell07/puppet-opendaylight/issues/63
 422
 423 [14]: https://github.com/dfarrell07/puppet-opendaylight/blob/master/CONTRIBUTING.markdown
 424
 425 [15]: https://github.com/dfarrell07/puppet-opendaylight/blob/master/CHANGELOG
 426
 427 [16]: https://github.com/dfarrell07/puppet-opendaylight/releases
 428
 429 [17]: https://github.com/dfarrell07/puppet-opendaylight/commits/master
 430
 431 [18]&#x3A; <http://cbs.centos.org/repos/nfv7-opendaylight-40-release/x86_64/os/Packages/> OpenDaylight Beryllium CentOS CBS repo
 432 [19]&#x3A; <https://wiki.opendaylight.org/view/Deployment#RPM> OpenDaylight RPMs and their repos