Bump Puppet version 4.x to 5.x
[integration/packaging/puppet-opendaylight.git] / 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"