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-neon-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_rollover_fileindex`
 327
 328 String that controls file index to use when log rollovers are initiated.
 329
 330 If set to 'max', files with a higher index will be newer than files with
 331 a smaller index.
 332
 333 If set to 'min', file with a lower index will be newer than files with a
 334 higher index.
 335
 336 If set to 'nomax', the min and max values will be ignored, and file
 337 numbering will increment by 1 and each rollover will have an
 338 incrementally higher value with no maximum number of files.
 339
 340 Default: `min`
 341
 342 Valid options: 'min', 'max', 'nomax'
 343
 344 ##### `log_mechanism`
 345
 346 Logging mechanism for karaf logs. They are logged either to a file or console.
 347 When `log_mechanism` is `file`, log files are configured as per `log_max_size`
 348 and `log_max_rollover`.
 349
 350 Default: `file`
 351
 352 Valid options: `file`, `console`.
 353
 354 ##### `log_pattern`
 355
 356 String that controls the log pattern used for logging.
 357
 358 Default: `%d{ISO8601} | %-5p | %-16t | %-60c{6} | %m%n`
 359
 360 Valid options: A valid string that is a valid log4j2 pattern.
 361
 362 ##### `enable_paxosgi_logger`
 363
 364 Boolean that controls whether the PaxOsgi appender is enabled for logging.
 365
 366 Note that enabling this will also require to modify the log pattern to
 367 make use of the added capabilities. To do so the variable `log_pattern` should
 368 be overriden to include a pattern that includes the tokens that PaxOsgi adds.
 369
 370 This could be achieving, for example, by setting `log_pattern` to a string
 371 that includes:
 372
 373 '%X{bundle.id} - %X{bundle.name} - %X{bundle.version}'
 374
 375 Failure to change the `log_pattern` will mean that the PaxOsgi appender will
 376 be enabled but the added functionality not used on the logging. This has no
 377 negative effect on the system and it will continue to run, just it will not
 378 include the added information one could get from PaxOsgi.
 379
 380 A good example would be to set this variable to `true` and set `log_pattern`
 381 to:
 382
 383 '%d{ISO8601} | %-5p | %-16t | %-32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n'
 384
 385 Default: `false`
 386
 387 Valid options: The boolean values `true` and `false`.
 388
 389 ##### `enable_ha`
 390
 391 Enable or disable ODL High Availablity.
 392
 393 Default: `false`
 394
 395 Valid options: The boolean values `true` and `false`.
 396
 397 Requires: `ha_node_ips`, `odl_bind_ip`
 398
 399 The ODL Clustering XML for HA are configured and enabled.
 400
 401 ##### `ha_node_ips`
 402
 403 Specifies the IPs that are part of the HA cluster enabled by `enable_ha`.
 404
 405 Default: \[]
 406
 407 Valid options: An array of IP addresses `['10.10.10.1', '10.10.10.1', '10.10.10.3']`.
 408
 409 Required by: `enable_ha`
 410
 411 ##### `ha_db_modules`
 412
 413 Specifies the modules to use for distributing and sharding the ODL datastore.
 414
 415 Default: `{'default'=> false}`
 416
 417 Valid options: A hash of module and Yang namespace for the module (default has no namespace).
 418
 419 Requires: `enable_ha`
 420
 421 ##### `ha_node_index`
 422
 423 Specifies the index of the IP for the node being configured from the array `ha_node_ips`.
 424
 425 Default: ''
 426
 427 Valid options: Index of a member of the array `ha_node_ips`: `0`.
 428
 429 This parameter is now deprecated and is no longer used.
 430
 431 ##### `snat_mechanism`
 432
 433 Specifies the mechanism to be used for SNAT.
 434
 435 Default: `controller`
 436
 437 Valid options: `conntrack`, `controller`
 438
 439 ##### `vpp_routing_node`
 440
 441 Specifies the routing node for VPP deployment. A non-empty string will create config file
 442 org.opendaylight.groupbasedpolicy.neutron.vpp.mapper.startup.cfg with routing-node set.
 443
 444 Default: `''`
 445
 446 Valid options: A valid host name to a VPP node handling routing.
 447
 448 ##### `java_opts`
 449
 450 Specifies the Java options to run ODL with as a string. Note, these options
 451 are in addition to the default Java options set by the karaf/ODL boot scripts
 452 and IP version based flag set by 'opendaylight' class.
 453
 454 Default: `''`
 455
 456 Valid options: A string of valid Java options.
 457
 458 ##### `username`
 459
 460 Specifies the username to set for admin role in ODL.
 461
 462 Default: `'admin'`
 463
 464 Valid options: A username string.
 465
 466 ##### `password`
 467
 468 Specifies the password to set for admin role in ODL.
 469
 470 Default: `'admin'`
 471
 472 Valid options: A password string.
 473
 474 ### `inherit_dscp_marking`
 475
 476 Specifies whether DSCP marking is enabled for packets egressing out of OVS through
 477 VXLAN/GRE tunnels.
 478
 479 Default: `false`
 480
 481 Valid options: `true`, `false`
 482
 483 ### `stats_polling_enabled`
 484
 485 Enables statistics polling of OpenFlow entities like table, groups.
 486
 487 Default: `false`
 488
 489 Valid options: `true`, `false`
 490
 491 ### `inactivity_probe`
 492
 493 Configures inactivity probe timer when specified.
 494
 495 Default: `undef`
 496
 497 Valid options: An integer or string in milliseconds.
 498
 499 ## Limitations
 500
 501 - Tested on CentOS 7 and Ubuntu 16.04.
 502 - Fedora is allowed but not well-tested, no Beaker coverage.
 503
 504 ## Development
 505
 506 We welcome contributions and work to make them easy!
 507
 508 See [CONTRIBUTING.markdown][4] for details about how to contribute to the
 509 OpenDaylight Puppet module.
 510
 511 ## Release Notes
 512
 513 See the [CHANGELOG][5] for information about releases.
 514
 515 [1]: http://www.opendaylight.org/ "OpenDaylight homepage"
 516
 517 [2]: http://docs.opendaylight.org/en/latest/submodules/integration/packaging/docs/rpms.html#repositories "ODL RPM repo docs"
 518
 519 [3]: https://launchpad.net/~odl-team/+archive/ubuntu/nitrogen "ODL Nitrogen Deb repo"
 520
 521 [4]: https://git.opendaylight.org/gerrit/gitweb?p=integration/packaging/puppet-opendaylight.git;a=blob;f=CONTRIBUTING.markdown "Contributing docs"
 522
 523 [5]: https://git.opendaylight.org/gerrit/gitweb?p=integration/packaging/puppet-opendaylight.git;a=blob;f=CHANGELOG "Chagelog"