README.markdown

   1 # OpenDaylight
   2
   3 #### Table of Contents
   4
   5 1. [Overview](#overview)
   6 2. [Module Description](#module-description)
   7 3. [Setup](#setup)
   8
   9 - [What `opendaylight` affects](#what-opendaylight-affects)
  10 - [Beginning with `opendaylight`](#beginning-with-opendaylight)
  11
  12 4. [Usage](#usage)
  13
  14 - [Karaf Features](#karaf-features)
  15 - [RPM Repo](#rpm-repo)
  16 - [Deb Repo](#deb-repo)
  17 - [Ports](#ports)
  18 - [Log Verbosity](#log-verbosity)
  19 - [Enabling ODL HA](#enabling-odl-ha)
  20
  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 a Deb.
  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 By default, the master branch installs OpenDaylight from the latest testing RPM repository
  40 or from the latest stable Deb repository depending on the OS. There are stable/<release>
  41 branches that install OpenDaylight 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] for OpenDaylight.
  51 - Manipulates OpenDaylight's configuration files according to the params
  52   passed to the `::opendaylight` class.
  53 - Starts the `opendaylight` systemd 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 with
  61 [applying the ODL Puppet module][12] to VMs.
  62
  63 ```
  64 # Provision a CentOS VM using puppet-opendaylight
  65 $ vagrant up cent7_pup_rpm
  66 $ vagrant ssh cent7_pup_rpm
  67 $ sudo systemctl is-active opendaylight
  68 active
  69 ```
  70
  71 ## Usage
  72
  73 The most basic usage, passing no parameters to the OpenDaylight class, will
  74 install and start OpenDaylight with a default configuration.
  75
  76 ```puppet
  77 class { 'opendaylight':
  78 }
  79 ```
  80
  81 ### Karaf Features
  82
  83 To set extra Karaf features to be installed at OpenDaylight start time, pass
  84 them in a list to the `extra_features` param. The extra features you pass will
  85 typically be driven by the requirements of your ODL install. You'll almost
  86 certainly need to pass some.
  87
  88 ```puppet
  89 class { 'opendaylight':
  90   extra_features => ['odl-netvirt-openstack'],
  91 }
  92 ```
  93
  94 OpenDaylight normally installs a default set of Karaf features at boot. They
  95 are recommended, so the ODL Puppet mod defaults to installing them. This can
  96 be customized by overriding the `default_features` param. You shouldn't
  97 normally need to do so.
  98
  99 ```puppet
 100 class { 'opendaylight':
 101   default_features => ['config', 'standard', 'region', 'package', 'kar', 'ssh', 'management'],
 102 }
 103 ```
 104
 105 ### RPM Repo
 106
 107 The `rpm_repo` param can be used to configure which RPM repository
 108 OpenDaylight is installed from.
 109
 110 ```puppet
 111 class { 'opendaylight':
 112   rpm_repo => 'opendaylight-40-release',
 113 }
 114 ```
 115
 116 The naming convention follows the naming convention of the CentOS Community
 117 Build System, which is where upstream ODL hosts its RPMs. The
 118 `opendaylight-40-release` example above would install OpenDaylight Beryllium
 119 4.0.0 from the [nfv7-opendaylight-40-release][18] repo. Repo names ending in
 120 `-release` will always contain well-tested, officially released versions of
 121 OpenDaylight. Repos ending in `-testing` contain frequent, but unstable and
 122 unofficial, releases. The ODL version given in repo names shows which major
 123 and minor version it is pinned to. The `opendaylight-40-release` repo will
 124 always provide OpenDaylight Beryllium 4.0, whereas `opendaylight-4-release`
 125 will provide the latest release with major version 4 (which could include
 126 Service Releases, like SR2 4.2).
 127
 128 For a full list of OpenDaylight releases and their CBS repos, see the
 129 [OpenDaylight Deployment wiki][19].
 130
 131 This is only read for RedHat based operating systems. For Debian based OSs,
 132 this values is `none`.
 133
 134 ### Deb Repo
 135
 136 The `deb_repo` param can be used to configure which Deb repository
 137 OpenDaylight is installed from.
 138
 139 ```puppet
 140 class { 'opendaylight':
 141   deb_repo => 'ppa:odl-team/boron',
 142 }
 143 ```
 144
 145 The naming convention is same as the naming convention of Launchpad PPA's,
 146 which is where ODL .debs are hosted. The `ppa:odl-team/boron` example above
 147 would install OpenDaylight Boron realease from the [odl-team's boron][20] repo.
 148
 149 This is only read for Debian based operating systems. For RedHat based OSs,
 150 this values is `none`.
 151
 152 ### Ports
 153
 154 To change the port on which OpenDaylight's northbound listens for REST API
 155 calls, use the `odl_rest_port` param.
 156
 157 ```puppet
 158 class { 'opendaylight':
 159   odl_rest_port => '8080',
 160 }
 161 ```
 162
 163 ### Log Verbosity
 164
 165 It's possible to define custom logger verbosity levels via the `log_levels`
 166 param.
 167
 168 ```puppet
 169 class { 'opendaylight':
 170   log_levels => { 'org.opendaylight.ovsdb' => 'TRACE', 'org.opendaylight.ovsdb.lib' => 'INFO' },
 171 }
 172 ```
 173
 174 ### Enabling ODL HA
 175
 176 To enable ODL HA, use the `enable_ha` flag. It's disabled by default.
 177
 178 When `enable_ha` is set to true the `ha_node_ips` should be populated with the
 179 IP addresses that ODL will listen on for each node in the HA cluster and
 180 `odl_bind_ip` should be set with the IP address from `ha_node_ips` configured
 181 for the particular node that puppet is configuring as part of the
 182 HA cluster.
 183
 184 By default a single ODL instance will become the leader for the entire
 185 datastore.  In order to distribute the datastore over multiple ODL instances,
 186 `ha_db_modules` parameter may be specified which will include the modules
 187 desired to separate out from the default shard, along with the Yang namespace
 188 for that module.
 189
 190 ```puppet
 191 class { 'opendaylight':
 192   enable_ha     => true,
 193   ha_node_ips   => ['10.10.10.1', '10.10.10.1', '10.10.10.3'],
 194   odl_bind_ip   => 0,
 195   ha_db_modules => {'default' => false, 'topology' => 'urn:opendaylight:topology'}
 196 }
 197 ```
 198
 199 ## Reference
 200
 201 ### Classes
 202
 203 #### Public classes
 204
 205 - `::opendaylight`: Main entry point to the module. All ODL knobs should be
 206   managed through its params.
 207
 208 #### Private classes
 209
 210 - `::opendaylight::params`: Contains default `opendaylight` class param values.
 211 - `::opendaylight::install`: Installs ODL from an RPM or a Deb.
 212 - `::opendaylight::config`: Manages ODL config, including Karaf features and
 213   REST port.
 214 - `::opendaylight::service`: Starts the OpenDaylight service.
 215
 216 ### `::opendaylight`
 217
 218 #### Parameters
 219
 220 ##### `default_features`
 221
 222 Sets the Karaf features to install by default. These should not normally need
 223 to be overridden.
 224
 225 Default: `['config', 'standard', 'region', 'package', 'kar', 'ssh', 'management']`
 226
 227 Valid options: A list of Karaf feature names as strings.
 228
 229 ##### `extra_features`
 230
 231 Specifies Karaf features to install in addition to the defaults listed in
 232 `default_features`.
 233
 234 You will likely need to customize this to your use-case.
 235
 236 Default: `[]`
 237
 238 Valid options: A list of Karaf feature names as strings.
 239
 240 ##### `odl_rest_port`
 241
 242 Specifies the port for the ODL northbound REST interface to listen on.
 243
 244 Default: `'8080'`
 245
 246 Valid options: A valid port number as a string or integer.
 247
 248 ##### `rpm_repo`
 249
 250 OpenDaylight CentOS CBS repo to install RPM from (opendaylight-4-testing,
 251 opendaylight-40-release, ...).
 252
 253 ##### `deb_repo`
 254
 255 OpenDaylight Launchpad PPA repo to install .deb from (ppa:odl-team/boron,
 256 ppa:odl-team/carbon, ...).
 257
 258 ##### `log_levels`
 259
 260 Custom OpenDaylight logger verbosity configuration.
 261
 262 Default: `{}`
 263
 264 Valid options: A hash of loggers to log levels.
 265
 266 ```
 267 { 'org.opendaylight.ovsdb' => 'TRACE', 'org.opendaylight.ovsdb.lib' => 'INFO' }
 268 ```
 269
 270 Valid log levels are TRACE, DEBUG, INFO, WARN, and ERROR.
 271
 272 The above example would add the following logging configuration to
 273 `/opt/opendaylight/etc/org.ops4j.pax.logging.cfg`.
 274
 275 ```
 276 # Log level config added by puppet-opendaylight
 277 log4j.logger.org.opendaylight.ovsdb = TRACE
 278
 279 # Log level config added by puppet-opendaylight
 280 log4j.logger.org.opendaylight.ovsdb.lib = INFO
 281 ```
 282
 283 To view loggers and their verbosity levels, use `log:list` at the ODL Karaf shell.
 284
 285 ```
 286 opendaylight-user@root>log:list
 287 Logger                     | Level
 288 ----------------------------------
 289 ROOT                       | INFO
 290 org.opendaylight.ovsdb     | TRACE
 291 org.opendaylight.ovsdb.lib | INFO
 292 ```
 293
 294 The main log output file is `/opt/opendaylight/data/log/karaf.log`.
 295
 296 ##### `log_max_size`
 297
 298 Maximum size of OpenDaylight's log file, `/opt/opendaylight/data/log/karaf.log`.
 299
 300 Once this size is reached, the log will be rolled over, with up to
 301 `log_max_rollover` log rollovers preserved in total.
 302
 303 Default: `10GB`
 304
 305 Valid options: A valid size as a string with unit specified.
 306
 307 ##### `log_max_rollover`
 308
 309 Maximum number of OpenDaylight karaf.log rollovers to keep.
 310
 311 Note that if this is set to 1, log rollovers will result in loosing newly
 312 logged data. It's recommended to use values greater than one to prune from
 313 the end of the log.
 314
 315 Default: `2`
 316
 317 Valid options: An integer greater than 0.
 318
 319 ##### `enable_ha`
 320
 321 Enable or disable ODL High Availablity.
 322
 323 Default: `false`
 324
 325 Valid options: The boolean values `true` and `false`.
 326
 327 Requires: `ha_node_ips`, `odl_bind_ip`
 328
 329 The ODL Clustering XML for HA are configured and enabled.
 330
 331 ##### `ha_node_ips`
 332
 333 Specifies the IPs that are part of the HA cluster enabled by `enable_ha`.
 334
 335 Default: \[]
 336
 337 Valid options: An array of IP addresses `['10.10.10.1', '10.10.10.1', '10.10.10.3']`.
 338
 339 Required by: `enable_ha`
 340
 341 ##### `ha_db_modules`
 342
 343 Specifies the modules to use for distributing and sharding the ODL datastore.
 344
 345 Default: `{'default'=> false}`
 346
 347 Valid options: A hash of module and Yang namespace for the module (default has no namespace).
 348
 349 Requires: `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 This parameter is now deprecated and is no longer used.
 360
 361 ##### `security_group_mode`
 362
 363 Specifies the mode to use for security groups.
 364
 365 Default: `stateful`
 366
 367 Valid options: `transparent`, `learn`, `stateless`
 368
 369 ##### `snat_mechanism`
 370
 371 Specifies the mechanism to be used for SNAT.
 372
 373 Default: `controller`
 374
 375 Valid options: `conntrack`, `controller`
 376
 377 ##### `vpp_routing_node`
 378
 379 Specifies the routing node for VPP deployment. A non-empty string will create config file
 380 org.opendaylight.groupbasedpolicy.neutron.vpp.mapper.startup.cfg with routing-node set.
 381
 382 Default: `''`
 383
 384 Valid options: A valid host name to a VPP node handling routing.
 385
 386 ##### `java_opts`
 387
 388 Specifies the Java options to run ODL with as a string.
 389
 390 Default: `'-Djava.net.preferIPv4Stack=true'`
 391
 392 Valid options: A string of valid Java options.
 393
 394 ##### `username`
 395
 396 Specifies the username to set for admin role in ODL.
 397
 398 Default: `'admin'`
 399
 400 Valid options: A username string.
 401
 402 ##### `password`
 403
 404 Specifies the password to set for admin role in ODL.
 405
 406 Default: `'admin'`
 407
 408 Valid options: A password string.
 409
 410 ## Limitations
 411
 412 - Tested on CentOS 7 and Ubuntu 16.04.
 413 - Fedora is allowed but not well-tested, no Beaker coverage.
 414
 415 ## Development
 416
 417 We welcome contributions and work to make them easy!
 418
 419 See [CONTRIBUTING.markdown][14] for details about how to contribute to the
 420 OpenDaylight Puppet module.
 421
 422 ## Release Notes/Contributors
 423
 424 See the [CHANGELOG][15] or our [git tags][16] for information about releases.
 425 See our [git commit history][17] for contributor information.
 426
 427 [7]: http://www.opendaylight.org/
 428
 429 [8]: https://github.com/dfarrell07/puppet-opendaylight/blob/master/CONTRIBUTING.markdown#issues
 430
 431 [9]: https://github.com/dfarrell07/opendaylight-systemd/
 432
 433 [11]: https://github.com/dfarrell07/vagrant-opendaylight/
 434
 435 [12]: https://github.com/dfarrell07/vagrant-opendaylight/tree/master/manifests
 436
 437 [13]: https://github.com/dfarrell07/puppet-opendaylight/issues/63
 438
 439 [14]: https://github.com/dfarrell07/puppet-opendaylight/blob/master/CONTRIBUTING.markdown
 440
 441 [15]: https://github.com/dfarrell07/puppet-opendaylight/blob/master/CHANGELOG
 442
 443 [16]: https://github.com/dfarrell07/puppet-opendaylight/releases
 444
 445 [17]: https://github.com/dfarrell07/puppet-opendaylight/commits/master
 446
 447 [18]: http://cbs.centos.org/repos/nfv7-opendaylight-40-release/x86_64/os/Packages/ "OpenDaylight Beryllium CentOS CBS repo"
 448
 449 [19]: https://wiki.opendaylight.org/view/Deployment#RPM "OpenDaylight RPMs and their repos"
 450
 451 [20]: https://launchpad.net/~odl-team/+archive/ubuntu/boron