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][1].
  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).
  37
  38 By default, the master branch installs OpenDaylight from the latest testing
  39 RPM repository or from the latest stable Deb repository depending on the OS.
  40 The stable/<release> branches install corresponding older ODL versions.
  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][1], including a systemd unit file.
  49 - Manipulates OpenDaylight's configuration files according to the params
  50   passed to the `::opendaylight` class.
  51 - Starts the `opendaylight` systemd service.
  52
  53 ### Beginning with `opendaylight`
  54
  55 Getting started with the OpenDaylight Puppet module is as simple as declaring
  56 the `::opendaylight` class.
  57
  58 ## Usage
  59
  60 The most basic usage, passing no parameters to the OpenDaylight class, will
  61 install and start OpenDaylight with a default configuration.
  62
  63 ```puppet
  64 class { 'opendaylight':
  65 }
  66 ```
  67
  68 ### Karaf Features
  69
  70 To set extra Karaf features to be installed at OpenDaylight start time, pass
  71 them in a list to the `extra_features` param. The extra features you pass will
  72 typically be driven by the requirements of your ODL install. You'll almost
  73 certainly need to pass some.
  74
  75 ```puppet
  76 class { 'opendaylight':
  77   extra_features => ['odl-netvirt-openstack'],
  78 }
  79 ```
  80
  81 OpenDaylight normally installs a default set of Karaf features at boot. They
  82 are recommended, so the ODL Puppet mod defaults to installing them. This can
  83 be customized by overriding the `default_features` param. You shouldn't
  84 normally need to do so.
  85
  86 ```puppet
  87 class { 'opendaylight':
  88   default_features => ['config', 'standard', 'region', 'package', 'kar', 'ssh', 'management'],
  89 }
  90 ```
  91
  92 ### RPM Repository
  93
  94 The `rpm_repo` param can be used to configure which RPM repository
  95 OpenDaylight is installed from.
  96
  97 ```puppet
  98 class { 'opendaylight':
  99   rpm_repo => 'https://nexus.opendaylight.org/content/repositories/opendaylight-fluorine-epel-7-$basearch-devel',
 100 }
 101 ```
 102
 103 The URL should be formatted like a baseurl in RPM .repo config files. In
 104 particular, note the $basearch variable, which should be left form the
 105 package manager (yum, dnf) to populate.
 106
 107 For additional information about ODL RPM repos, see the [Integration/Packaging
 108 RPM repositories documentation][2].
 109
 110 This is only read for Red Hat-family operating systems.
 111
 112 ### Deb Repository
 113
 114 The `deb_repo` param can be used to configure which Deb repository
 115 OpenDaylight is installed from.
 116
 117 ```puppet
 118 class { 'opendaylight':
 119   deb_repo => 'ppa:odl-team/nitrogen',
 120 }
 121 ```
 122
 123 The naming convention is same as the naming convention of Launchpad PPA's,
 124 which is where ODL .debs are hosted. The `ppa:odl-team/nitrogen` example above
 125 would install OpenDaylight Nitrogen from the [Nitrogen launchpad repo][3].
 126
 127 This is only read for Debian-family operating systems.
 128
 129 ### Ports
 130
 131 To change the port on which OpenDaylight's northbound listens for REST API
 132 calls, use the `odl_rest_port` param.
 133
 134 ```puppet
 135 class { 'opendaylight':
 136   odl_rest_port => '8181',
 137 }
 138 ```
 139
 140 ### Log Verbosity
 141
 142 It's possible to define custom logger verbosity levels via the `log_levels`
 143 param.
 144
 145 ```puppet
 146 class { 'opendaylight':
 147   log_levels => { 'org.opendaylight.ovsdb' => 'TRACE', 'org.opendaylight.ovsdb.lib' => 'INFO' },
 148 }
 149 ```
 150
 151 ### Enabling ODL HA
 152
 153 To enable ODL HA, use the `enable_ha` flag. It's disabled by default.
 154
 155 When `enable_ha` is set to true the `ha_node_ips` should be populated with the
 156 IP addresses that ODL will listen on for each node in the HA cluster and
 157 `odl_bind_ip` should be set with the IP address from `ha_node_ips` configured
 158 for the particular node that puppet is configuring as part of the
 159 HA cluster.
 160
 161 By default a single ODL instance will become the leader for the entire
 162 datastore.  In order to distribute the datastore over multiple ODL instances,
 163 `ha_db_modules` parameter may be specified which will include the modules
 164 desired to separate out from the default shard, along with the Yang namespace
 165 for that module.
 166
 167 ```puppet
 168 class { 'opendaylight':
 169   enable_ha     => true,
 170   ha_node_ips   => ['10.10.10.1', '10.10.10.1', '10.10.10.3'],
 171   odl_bind_ip   => 0,
 172   ha_db_modules => {'default' => false, 'topology' => 'urn:opendaylight:topology'}
 173 }
 174 ```
 175
 176 ### Configuring websocket address
 177
 178 Websocket address can be configured to the IP of ODL rather than default 0.0.0.0. This IP will
 179 be defined by `odl_bind_ip`.
 180
 181 ### Enabling TLS with OpenDaylight
 182
 183 It is possible to enable TLS encrypted communication for OpenDaylight Northbound REST
 184 along with Southbound OVSDB/OpenFlow communication with Open vSwitch. To enable
 185 TLS, use the `enable_tls` flag. This option will create two keystores in OpenDaylight
 186 which are stored in '/opt/opendaylight/configuration/ssl'. The first keystore
 187 is the controller keystore, which will hold the private key and ODL certificate,
 188 along with the Certificate Authority (CA) certificate if provided. The second
 189 keystore is the trust keystore, which will hold the trusted OVS switch certificates.
 190
 191 In order to enable TLS, it is required to provide the `tls_keystore_password`
 192 parameter. This represents the password to use for the controller and truststore
 193 keystores. With only providing these parameters, ODL will generate the
 194 controller keystore with a random private key and self-signed certficate.
 195
 196 Additionally the `tls_key_file` and `tls_cert_file` parameters may be provided.
 197 These represent ODL's private key file and certificate file to be used when building
 198 the controller keystore. Optionally the `tls_ca_cert_file` may be provided which
 199 will chain the CA certificate to the keystore for client validation.
 200
 201 `tls_trusted_certs` may be provided as an array of trusted certificates to be
 202 added to the trusted keystore. This allows OpenDaylight to identify trusted
 203 clients which may connect to ODL Southbound and Northbound.
 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 a Deb.
 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 ##### `odl_rest_port`
 247
 248 Specifies the port for the ODL northbound REST interface to listen on.
 249
 250 Default: `'8181'`
 251
 252 Valid options: A valid port number as a string or integer.
 253
 254 ##### `rpm_repo`
 255
 256 Repo URL to install ODL RPM from, in .repo baseurl format.
 257
 258 ##### `deb_repo`
 259
 260 OpenDaylight Launchpad PPA repo to install .deb from (ppa:odl-team/boron,
 261 ppa:odl-team/nitrogen, ...).
 262
 263 ##### `log_levels`
 264
 265 Custom OpenDaylight logger verbosity configuration.
 266
 267 Default: `{}`
 268
 269 Valid options: A hash of loggers to log levels.
 270
 271 ```
 272 { 'org.opendaylight.ovsdb' => 'TRACE', 'org.opendaylight.ovsdb.lib' => 'INFO' }
 273 ```
 274
 275 Valid log levels are TRACE, DEBUG, INFO, WARN, and ERROR.
 276
 277 The above example would add the following logging configuration to
 278 `/opt/opendaylight/etc/org.ops4j.pax.logging.cfg`.
 279
 280 ```
 281 # Log level config added by puppet-opendaylight
 282 log4j2.logger.org_opendaylight_ovsdb.level = TRACE
 283 log4j2.logger.org_opendaylight_ovsdb.name = org.opendaylight.ovsdb
 284
 285 # Log level config added by puppet-opendaylight
 286 log4j2.logger.org_opendaylight_ovsdb_lib.level = INFO
 287 log4j2.logger.org_opendaylight_ovsdb_lib.name = org.opendaylight.ovsdb.lib
 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 ##### `log_max_size`
 304
 305 Maximum size of OpenDaylight's log file, `/opt/opendaylight/data/log/karaf.log`.
 306
 307 Once this size is reached, the log will be rolled over, with up to
 308 `log_max_rollover` log rollovers preserved in total.
 309
 310 Default: `10GB`
 311
 312 Valid options: A valid size as a string with unit specified.
 313
 314 ##### `log_max_rollover`
 315
 316 Maximum number of OpenDaylight karaf.log rollovers to keep.
 317
 318 Note that if this is set to 1, log rollovers will result in loosing newly
 319 logged data. It's recommended to use values greater than one to prune from
 320 the end of the log.
 321
 322 Default: `2`
 323
 324 Valid options: An integer greater than 0.
 325
 326 ##### `log_mechanism`
 327
 328 Logging mechanism for karaf logs. They are logged either to a file or console.
 329 When `log_mechanism` is `file`, log files are configured as per `log_max_size`
 330 and `log_max_rollover`.
 331
 332 Default: `file`
 333
 334 Valid options: `file`, `console`.
 335
 336 ##### `enable_ha`
 337
 338 Enable or disable ODL High Availablity.
 339
 340 Default: `false`
 341
 342 Valid options: The boolean values `true` and `false`.
 343
 344 Requires: `ha_node_ips`, `odl_bind_ip`
 345
 346 The ODL Clustering XML for HA are configured and enabled.
 347
 348 ##### `ha_node_ips`
 349
 350 Specifies the IPs that are part of the HA cluster enabled by `enable_ha`.
 351
 352 Default: \[]
 353
 354 Valid options: An array of IP addresses `['10.10.10.1', '10.10.10.1', '10.10.10.3']`.
 355
 356 Required by: `enable_ha`
 357
 358 ##### `ha_db_modules`
 359
 360 Specifies the modules to use for distributing and sharding the ODL datastore.
 361
 362 Default: `{'default'=> false}`
 363
 364 Valid options: A hash of module and Yang namespace for the module (default has no namespace).
 365
 366 Requires: `enable_ha`
 367
 368 ##### `ha_node_index`
 369
 370 Specifies the index of the IP for the node being configured from the array `ha_node_ips`.
 371
 372 Default: ''
 373
 374 Valid options: Index of a member of the array `ha_node_ips`: `0`.
 375
 376 This parameter is now deprecated and is no longer used.
 377
 378 ##### `snat_mechanism`
 379
 380 Specifies the mechanism to be used for SNAT.
 381
 382 Default: `controller`
 383
 384 Valid options: `conntrack`, `controller`
 385
 386 ##### `vpp_routing_node`
 387
 388 Specifies the routing node for VPP deployment. A non-empty string will create config file
 389 org.opendaylight.groupbasedpolicy.neutron.vpp.mapper.startup.cfg with routing-node set.
 390
 391 Default: `''`
 392
 393 Valid options: A valid host name to a VPP node handling routing.
 394
 395 ##### `java_opts`
 396
 397 Specifies the Java options to run ODL with as a string. Note, these options
 398 are in addition to the default Java options set by the karaf/ODL boot scripts.
 399
 400 Default: `'-Djava.net.preferIPv4Stack=true'`
 401
 402 Valid options: A string of valid Java options.
 403
 404 ##### `username`
 405
 406 Specifies the username to set for admin role in ODL.
 407
 408 Default: `'admin'`
 409
 410 Valid options: A username string.
 411
 412 ##### `password`
 413
 414 Specifies the password to set for admin role in ODL.
 415
 416 Default: `'admin'`
 417
 418 Valid options: A password string.
 419
 420 ### `inherit_dscp_marking`
 421
 422 Specifies whether DSCP marking is enabled for packets egressing out of OVS through
 423 VXLAN/GRE tunnels.
 424
 425 Default: `false`
 426
 427 Valid options: `true`, `false`
 428
 429 ### `stats_polling_enabled`
 430
 431 Enables statistics polling of OpenFlow entities like table, groups.
 432
 433 Default: `false`
 434
 435 Valid options: `true`, `false`
 436
 437 ## Limitations
 438
 439 - Tested on CentOS 7 and Ubuntu 16.04.
 440 - Fedora is allowed but not well-tested, no Beaker coverage.
 441
 442 ## Development
 443
 444 We welcome contributions and work to make them easy!
 445
 446 See [CONTRIBUTING.markdown][4] for details about how to contribute to the
 447 OpenDaylight Puppet module.
 448
 449 ## Release Notes
 450
 451 See the [CHANGELOG][5] for information about releases.
 452
 453 [1]: http://www.opendaylight.org/ "OpenDaylight homepage"
 454
 455 [2]: http://docs.opendaylight.org/en/latest/submodules/integration/packaging/docs/rpms.html#repositories "ODL RPM repo docs"
 456
 457 [3]: https://launchpad.net/~odl-team/+archive/ubuntu/nitrogen "ODL Nitrogen Deb repo"
 458
 459 [4]: https://git.opendaylight.org/gerrit/gitweb?p=integration/packaging/puppet-opendaylight.git;a=blob;f=CONTRIBUTING.markdown "Contributing docs"
 460
 461 [5]: https://git.opendaylight.org/gerrit/gitweb?p=integration/packaging/puppet-opendaylight.git;a=blob;f=CHANGELOG "Chagelog"