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
  12 - [What `opendaylight` affects](#what-opendaylight-affects)
  13 - [Beginning with `opendaylight`](#beginning-with-opendaylight)
  14
  15 4. [Usage](#usage)
  16
  17 - [Karaf Features](#karaf-features)
  18 - [RPM Repo](#rpm-repo)
  19 - [Deb Repo](#deb-repo)
  20 - [Ports](#ports)
  21 - [Log Verbosity](#log-verbosity)
  22 - [Enabling ODL HA](#enabling-odl-ha)
  23
  24 5. [Reference ](#reference)
  25 6. [Limitations](#limitations)
  26 7. [Development](#development)
  27 8. [Release Notes/Contributors](#release-notescontributors)
  28
  29 ## Overview
  30
  31 Puppet module that installs and configures the [OpenDaylight Software Defined
  32 Networking (SDN) controller][7].
  33
  34 ## Module Description
  35
  36 Deploys OpenDaylight to various OSs either via an RPM or a Deb.
  37
  38 All OpenDaylight configuration should be handled through the ODL Puppet
  39 module's [params](#parameters). If you need a new knob, [please raise an
  40 Issue][8].
  41
  42 By default, the master branch installs OpenDaylight from the latest testing RPM repository
  43 or from the latest stable Deb repository depending on the OS. There are stable/<release>
  44 branches that install OpenDaylight releases and service releases, like Beryllium or Beryllium SR3.
  45
  46 ## Setup
  47
  48 ### What `opendaylight` affects
  49
  50 - Installs Java, which is required by ODL.
  51 - Creates `odl:odl` user:group if they don't already exist.
  52 - Installs [OpenDaylight][7].
  53 - Installs a [systemd unitfile][9] for OpenDaylight.
  54 - Manipulates OpenDaylight's configuration files according to the params
  55   passed to the `::opendaylight` class.
  56 - Starts the `opendaylight` systemd service.
  57
  58 ### Beginning with `opendaylight`
  59
  60 Getting started with the OpenDaylight Puppet module is as simple as declaring
  61 the `::opendaylight` class.
  62
  63 The [vagrant-opendaylight][11] project provides an easy way to experiment with
  64 [applying the ODL Puppet module][12] to VMs.
  65
  66 ```
  67 # Provision a CentOS VM using puppet-opendaylight
  68 $ vagrant up cent7_pup_rpm
  69 $ vagrant ssh cent7_pup_rpm
  70 $ sudo systemctl is-active opendaylight
  71 active
  72 ```
  73
  74 ## Usage
  75
  76 The most basic usage, passing no parameters to the OpenDaylight class, will
  77 install and start OpenDaylight with a default configuration.
  78
  79 ```puppet
  80 class { 'opendaylight':
  81 }
  82 ```
  83
  84 ### Karaf Features
  85
  86 To set extra Karaf features to be installed at OpenDaylight start time, pass
  87 them in a list to the `extra_features` param. The extra features you pass will
  88 typically be driven by the requirements of your ODL install. You'll almost
  89 certainly need to pass some.
  90
  91 ```puppet
  92 class { 'opendaylight':
  93   extra_features => ['odl-netvirt-openstack'],
  94 }
  95 ```
  96
  97 OpenDaylight normally installs a default set of Karaf features at boot. They
  98 are recommended, so the ODL Puppet mod defaults to installing them. This can
  99 be customized by overriding the `default_features` param. You shouldn't
 100 normally need to do so.
 101
 102 ```puppet
 103 class { 'opendaylight':
 104   default_features => ['config', 'standard', 'region', 'package', 'kar', 'ssh', 'management'],
 105 }
 106 ```
 107
 108 ### RPM Repo
 109
 110 The `rpm_repo` param can be used to configure which RPM repository
 111 OpenDaylight is installed from.
 112
 113 ```puppet
 114 class { 'opendaylight':
 115   rpm_repo => 'opendaylight-40-release',
 116 }
 117 ```
 118
 119 The naming convention follows the naming convention of the CentOS Community
 120 Build System, which is where upstream ODL hosts its RPMs. The
 121 `opendaylight-40-release` example above would install OpenDaylight Beryllium
 122 4.0.0 from the [nfv7-opendaylight-40-release][18] repo. Repo names ending in
 123 `-release` will always contain well-tested, officially released versions of
 124 OpenDaylight. Repos ending in `-testing` contain frequent, but unstable and
 125 unofficial, releases. The ODL version given in repo names shows which major
 126 and minor version it is pinned to. The `opendaylight-40-release` repo will
 127 always provide OpenDaylight Beryllium 4.0, whereas `opendaylight-4-release`
 128 will provide the latest release with major version 4 (which could include
 129 Service Releases, like SR2 4.2).
 130
 131 For a full list of OpenDaylight releases and their CBS repos, see the
 132 [OpenDaylight Deployment wiki][19].
 133
 134 This is only read for RedHat based operating systems. For Debian based OSs,
 135 this values is `none`.
 136
 137 ### Deb Repo
 138
 139 The `deb_repo` param can be used to configure which Deb repository
 140 OpenDaylight is installed from.
 141
 142 ```puppet
 143 class { 'opendaylight':
 144   deb_repo => 'ppa:odl-team/boron',
 145 }
 146 ```
 147
 148 The naming convention is same as the naming convention of Launchpad PPA's,
 149 which is where ODL .debs are hosted. The `ppa:odl-team/boron` example above
 150 would install OpenDaylight Boron realease from the [odl-team's boron][20] repo.
 151
 152 This is only read for Debian based operating systems. For RedHat based OSs,
 153 this values is `none`.
 154
 155 ### Ports
 156
 157 To change the port on which OpenDaylight's northbound listens for REST API
 158 calls, use the `odl_rest_port` param.
 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 HA
 178
 179 To enable ODL HA, use the `enable_ha` flag. It's disabled by default.
 180
 181 When `enable_ha` is set to true the `ha_node_ips` should be populated with the
 182 IP addresses that ODL will listen on for each node in the HA cluster and
 183 `ha_node_index` should be set with the index of the IP address from
 184 `ha_node_ips` for the particular node that puppet is configuring as part of the
 185 HA cluster.
 186
 187 ```puppet
 188 class { 'opendaylight':
 189   enable_ha     => true,
 190   ha_node_ips   => ['10.10.10.1', '10.10.10.1', '10.10.10.3'],
 191   ha_node_index => 0,
 192 }
 193 ```
 194
 195 ## Reference
 196
 197 ### Classes
 198
 199 #### Public classes
 200
 201 - `::opendaylight`: Main entry point to the module. All ODL knobs should be
 202   managed through its params.
 203
 204 #### Private classes
 205
 206 - `::opendaylight::params`: Contains default `opendaylight` class param values.
 207 - `::opendaylight::install`: Installs ODL from an RPM or a Deb.
 208 - `::opendaylight::config`: Manages ODL config, including Karaf features and
 209   REST port.
 210 - `::opendaylight::service`: Starts the OpenDaylight service.
 211
 212 ### `::opendaylight`
 213
 214 #### Parameters
 215
 216 ##### `default_features`
 217
 218 Sets the Karaf features to install by default. These should not normally need
 219 to be overridden.
 220
 221 Default: `['config', 'standard', 'region', 'package', 'kar', 'ssh', 'management']`
 222
 223 Valid options: A list of Karaf feature names as strings.
 224
 225 ##### `extra_features`
 226
 227 Specifies Karaf features to install in addition to the defaults listed in
 228 `default_features`.
 229
 230 You will likely need to customize this to your use-case.
 231
 232 Default: `[]`
 233
 234 Valid options: A list of Karaf feature names as strings.
 235
 236 ##### `odl_rest_port`
 237
 238 Specifies the port for the ODL northbound REST interface to listen on.
 239
 240 Default: `'8080'`
 241
 242 Valid options: A valid port number as a string or integer.
 243
 244 ##### `rpm_repo`
 245
 246 OpenDaylight CentOS CBS repo to install RPM from (opendaylight-4-testing,
 247 opendaylight-40-release, ...).
 248
 249 ##### `deb_repo`
 250
 251 OpenDaylight Launchpad PPA repo to install .deb from (ppa:odl-team/boron,
 252 ppa:odl-team/carbon, ...).
 253
 254 ##### `log_levels`
 255
 256 Custom OpenDaylight logger verbosity configuration.
 257
 258 Default: `{}`
 259
 260 Valid options: A hash of loggers to log levels.
 261
 262 ```
 263 { 'org.opendaylight.ovsdb' => 'TRACE', 'org.opendaylight.ovsdb.lib' => 'INFO' }
 264 ```
 265
 266 Valid log levels are TRACE, DEBUG, INFO, WARN, and ERROR.
 267
 268 The above example would add the following logging configuration to
 269 `/opt/opendaylight/etc/org.ops4j.pax.logging.cfg`.
 270
 271 ```
 272 # Log level config added by puppet-opendaylight
 273 log4j.logger.org.opendaylight.ovsdb = TRACE
 274
 275 # Log level config added by puppet-opendaylight
 276 log4j.logger.org.opendaylight.ovsdb.lib = INFO
 277 ```
 278
 279 To view loggers and their verbosity levels, use `log:list` at the ODL Karaf shell.
 280
 281 ```
 282 opendaylight-user@root>log:list
 283 Logger                     | Level
 284 ----------------------------------
 285 ROOT                       | INFO
 286 org.opendaylight.ovsdb     | TRACE
 287 org.opendaylight.ovsdb.lib | INFO
 288 ```
 289
 290 The main log output file is `/opt/opendaylight/data/log/karaf.log`.
 291
 292 ##### `enable_ha`
 293
 294 Enable or disable ODL High Availablity.
 295
 296 Default: `false`
 297
 298 Valid options: The boolean values `true` and `false`.
 299
 300 Requires: `ha_node_ips`, `ha_node_index`
 301
 302 The ODL Clustering XML for HA are configured and enabled.
 303
 304 ##### `ha_node_ips`
 305
 306 Specifies the IPs that are part of the HA cluster enabled by `enable_ha`.
 307
 308 Default: \[]
 309
 310 Valid options: An array of IP addresses `['10.10.10.1', '10.10.10.1', '10.10.10.3']`.
 311
 312 Required by: `enable_ha`
 313
 314 ##### `ha_node_index`
 315
 316 Specifies the index of the IP for the node being configured from the array `ha_node_ips`.
 317
 318 Default: ''
 319
 320 Valid options: Index of a member of the array `ha_node_ips`: `0`.
 321
 322 Required by: `enable_ha`, `ha_node_ips`
 323
 324 ##### `security_group_mode`
 325
 326 Specifies the mode to use for security groups.
 327
 328 Default: `stateful`
 329
 330 Valid options: `transparent`, `learn`, `stateless`
 331
 332 ##### `vpp_routing_node`
 333
 334 Specifies the routing node for VPP deployment. A non-empty string will create config file
 335 org.opendaylight.groupbasedpolicy.neutron.vpp.mapper.startup.cfg with routing-node set.
 336
 337 Default: `''`
 338
 339 Valid options: A valid host name to a VPP node handling routing.
 340
 341 ##### `java_opts`
 342
 343 Specifies the Java options to run ODL with as a string.
 344
 345 Default: `'-Djava.net.preferIPv4Stack=true'`
 346
 347 Valid options: A string of valid Java options.
 348
 349 ##### `username`
 350
 351 Specifies the username to set for admin role in ODL.
 352
 353 Default: `'admin'`
 354
 355 Valid options: A username string.
 356
 357 ##### `password`
 358
 359 Specifies the password to set for admin role in ODL.
 360
 361 Default: `'admin'`
 362
 363 Valid options: A password string.
 364
 365 ## Limitations
 366
 367 - Tested on CentOS 7 and Ubuntu 16.04.
 368 - Fedora is allowed but not well-tested, no Beaker coverage.
 369
 370 ## Development
 371
 372 We welcome contributions and work to make them easy!
 373
 374 See [CONTRIBUTING.markdown][14] for details about how to contribute to the
 375 OpenDaylight Puppet module.
 376
 377 ## Release Notes/Contributors
 378
 379 See the [CHANGELOG][15] or our [git tags][16] for information about releases.
 380 See our [git commit history][17] for contributor information.
 381
 382 [1]: https://travis-ci.org/dfarrell07/puppet-opendaylight
 383
 384 [2]: https://gemnasium.com/dfarrell07/puppet-opendaylight
 385
 386 [4]: https://travis-ci.org/dfarrell07/puppet-opendaylight.svg?branch=master
 387
 388 [5]: https://gemnasium.com/dfarrell07/puppet-opendaylight.svg?branch=master
 389
 390 [7]: http://www.opendaylight.org/
 391
 392 [8]: https://github.com/dfarrell07/puppet-opendaylight/blob/master/CONTRIBUTING.markdown#issues
 393
 394 [9]: https://github.com/dfarrell07/opendaylight-systemd/
 395
 396 [11]: https://github.com/dfarrell07/vagrant-opendaylight/
 397
 398 [12]: https://github.com/dfarrell07/vagrant-opendaylight/tree/master/manifests
 399
 400 [13]: https://github.com/dfarrell07/puppet-opendaylight/issues/63
 401
 402 [14]: https://github.com/dfarrell07/puppet-opendaylight/blob/master/CONTRIBUTING.markdown
 403
 404 [15]: https://github.com/dfarrell07/puppet-opendaylight/blob/master/CHANGELOG
 405
 406 [16]: https://github.com/dfarrell07/puppet-opendaylight/releases
 407
 408 [17]: https://github.com/dfarrell07/puppet-opendaylight/commits/master
 409
 410 [18]: http://cbs.centos.org/repos/nfv7-opendaylight-40-release/x86_64/os/Packages/ "OpenDaylight Beryllium CentOS CBS repo"
 411
 412 [18]: https://wiki.opendaylight.org/view/Deployment#RPM "OpenDaylight RPMs and their repos"
 413
 414 [20]: https://launchpad.net/~odl-team/+archive/ubuntu/boron