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-oxygen-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/carbon',
 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/carbon` example above
 125 would install OpenDaylight Carbon from the [Boron 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 => '8080',
 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: `'8080'`
 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/carbon, ...).
 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 log4j.logger.org.opendaylight.ovsdb = TRACE
 283
 284 # Log level config added by puppet-opendaylight
 285 log4j.logger.org.opendaylight.ovsdb.lib = INFO
 286 ```
 287
 288 To view loggers and their verbosity levels, use `log:list` at the ODL Karaf shell.
 289
 290 ```
 291 opendaylight-user@root>log:list
 292 Logger                     | Level
 293 ----------------------------------
 294 ROOT                       | INFO
 295 org.opendaylight.ovsdb     | TRACE
 296 org.opendaylight.ovsdb.lib | INFO
 297 ```
 298
 299 The main log output file is `/opt/opendaylight/data/log/karaf.log`.
 300
 301 ##### `log_max_size`
 302
 303 Maximum size of OpenDaylight's log file, `/opt/opendaylight/data/log/karaf.log`.
 304
 305 Once this size is reached, the log will be rolled over, with up to
 306 `log_max_rollover` log rollovers preserved in total.
 307
 308 Default: `10GB`
 309
 310 Valid options: A valid size as a string with unit specified.
 311
 312 ##### `log_max_rollover`
 313
 314 Maximum number of OpenDaylight karaf.log rollovers to keep.
 315
 316 Note that if this is set to 1, log rollovers will result in loosing newly
 317 logged data. It's recommended to use values greater than one to prune from
 318 the end of the log.
 319
 320 Default: `2`
 321
 322 Valid options: An integer greater than 0.
 323
 324 ##### `log_mechanism`
 325
 326 Logging mechanism for karaf logs. They are logged either to a file or console.
 327 When `log_mechanism` is `file`, log files are configured as per `log_max_size`
 328 and `log_max_rollover`.
 329
 330 Default: `file`
 331
 332 Valid options: `file`, `console`.
 333
 334 ##### `enable_ha`
 335
 336 Enable or disable ODL High Availablity.
 337
 338 Default: `false`
 339
 340 Valid options: The boolean values `true` and `false`.
 341
 342 Requires: `ha_node_ips`, `odl_bind_ip`
 343
 344 The ODL Clustering XML for HA are configured and enabled.
 345
 346 ##### `ha_node_ips`
 347
 348 Specifies the IPs that are part of the HA cluster enabled by `enable_ha`.
 349
 350 Default: \[]
 351
 352 Valid options: An array of IP addresses `['10.10.10.1', '10.10.10.1', '10.10.10.3']`.
 353
 354 Required by: `enable_ha`
 355
 356 ##### `ha_db_modules`
 357
 358 Specifies the modules to use for distributing and sharding the ODL datastore.
 359
 360 Default: `{'default'=> false}`
 361
 362 Valid options: A hash of module and Yang namespace for the module (default has no namespace).
 363
 364 Requires: `enable_ha`
 365
 366 ##### `ha_node_index`
 367
 368 Specifies the index of the IP for the node being configured from the array `ha_node_ips`.
 369
 370 Default: ''
 371
 372 Valid options: Index of a member of the array `ha_node_ips`: `0`.
 373
 374 This parameter is now deprecated and is no longer used.
 375
 376 ##### `snat_mechanism`
 377
 378 Specifies the mechanism to be used for SNAT.
 379
 380 Default: `controller`
 381
 382 Valid options: `conntrack`, `controller`
 383
 384 ##### `vpp_routing_node`
 385
 386 Specifies the routing node for VPP deployment. A non-empty string will create config file
 387 org.opendaylight.groupbasedpolicy.neutron.vpp.mapper.startup.cfg with routing-node set.
 388
 389 Default: `''`
 390
 391 Valid options: A valid host name to a VPP node handling routing.
 392
 393 ##### `java_opts`
 394
 395 Specifies the Java options to run ODL with as a string.
 396
 397 Default: `'-Djava.net.preferIPv4Stack=true'`
 398
 399 Valid options: A string of valid Java options.
 400
 401 ##### `username`
 402
 403 Specifies the username to set for admin role in ODL.
 404
 405 Default: `'admin'`
 406
 407 Valid options: A username string.
 408
 409 ##### `password`
 410
 411 Specifies the password to set for admin role in ODL.
 412
 413 Default: `'admin'`
 414
 415 Valid options: A password string.
 416
 417 ## Limitations
 418
 419 - Tested on CentOS 7 and Ubuntu 16.04.
 420 - Fedora is allowed but not well-tested, no Beaker coverage.
 421
 422 ## Development
 423
 424 We welcome contributions and work to make them easy!
 425
 426 See [CONTRIBUTING.markdown][4] for details about how to contribute to the
 427 OpenDaylight Puppet module.
 428
 429 ## Release Notes
 430
 431 See the [CHANGELOG][5] for information about releases.
 432
 433 [1]: http://www.opendaylight.org/ "OpenDaylight homepage"
 434
 435 [2]: http://docs.opendaylight.org/en/latest/submodules/integration/packaging/docs/rpms.html#repositories "ODL RPM repo docs"
 436
 437 [3]: https://launchpad.net/~odl-team/+archive/ubuntu/carbon "ODL Carbon Deb repo"
 438
 439 [4]: https://git.opendaylight.org/gerrit/gitweb?p=integration/packaging/puppet-opendaylight.git;a=blob;f=CONTRIBUTING.markdown "Contributing docs"
 440
 441 [5]: https://git.opendaylight.org/gerrit/gitweb?p=integration/packaging/puppet-opendaylight.git;a=blob;f=CHANGELOG "Chagelog"