Merge "Update to ODL Neon RPM pipelines"
[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_ha`
363
364 Enable or disable ODL High Availablity.
365
366 Default: `false`
367
368 Valid options: The boolean values `true` and `false`.
369
370 Requires: `ha_node_ips`, `odl_bind_ip`
371
372 The ODL Clustering XML for HA are configured and enabled.
373
374 ##### `ha_node_ips`
375
376 Specifies the IPs that are part of the HA cluster enabled by `enable_ha`.
377
378 Default: \[]
379
380 Valid options: An array of IP addresses `['10.10.10.1', '10.10.10.1', '10.10.10.3']`.
381
382 Required by: `enable_ha`
383
384 ##### `ha_db_modules`
385
386 Specifies the modules to use for distributing and sharding the ODL datastore.
387
388 Default: `{'default'=> false}`
389
390 Valid options: A hash of module and Yang namespace for the module (default has no namespace).
391
392 Requires: `enable_ha`
393
394 ##### `ha_node_index`
395
396 Specifies the index of the IP for the node being configured from the array `ha_node_ips`.
397
398 Default: ''
399
400 Valid options: Index of a member of the array `ha_node_ips`: `0`.
401
402 This parameter is now deprecated and is no longer used.
403
404 ##### `snat_mechanism`
405
406 Specifies the mechanism to be used for SNAT.
407
408 Default: `controller`
409
410 Valid options: `conntrack`, `controller`
411
412 ##### `vpp_routing_node`
413
414 Specifies the routing node for VPP deployment. A non-empty string will create config file
415 org.opendaylight.groupbasedpolicy.neutron.vpp.mapper.startup.cfg with routing-node set.
416
417 Default: `''`
418
419 Valid options: A valid host name to a VPP node handling routing.
420
421 ##### `java_opts`
422
423 Specifies the Java options to run ODL with as a string. Note, these options
424 are in addition to the default Java options set by the karaf/ODL boot scripts
425 and IP version based flag set by 'opendaylight' class.
426
427 Default: `''`
428
429 Valid options: A string of valid Java options.
430
431 ##### `username`
432
433 Specifies the username to set for admin role in ODL.
434
435 Default: `'admin'`
436
437 Valid options: A username string.
438
439 ##### `password`
440
441 Specifies the password to set for admin role in ODL.
442
443 Default: `'admin'`
444
445 Valid options: A password string.
446
447 ### `inherit_dscp_marking`
448
449 Specifies whether DSCP marking is enabled for packets egressing out of OVS through
450 VXLAN/GRE tunnels.
451
452 Default: `false`
453
454 Valid options: `true`, `false`
455
456 ### `stats_polling_enabled`
457
458 Enables statistics polling of OpenFlow entities like table, groups.
459
460 Default: `false`
461
462 Valid options: `true`, `false`
463
464 ### `inactivity_probe`
465
466 Configures inactivity probe timer when specified.
467
468 Default: `undef`
469
470 Valid options: An integer or string in milliseconds.
471
472 ## Limitations
473
474 - Tested on CentOS 7 and Ubuntu 16.04.
475 - Fedora is allowed but not well-tested, no Beaker coverage.
476
477 ## Development
478
479 We welcome contributions and work to make them easy!
480
481 See [CONTRIBUTING.markdown][4] for details about how to contribute to the
482 OpenDaylight Puppet module.
483
484 ## Release Notes
485
486 See the [CHANGELOG][5] for information about releases.
487
488 [1]: http://www.opendaylight.org/ "OpenDaylight homepage"
489
490 [2]: http://docs.opendaylight.org/en/latest/submodules/integration/packaging/docs/rpms.html#repositories "ODL RPM repo docs"
491
492 [3]: https://launchpad.net/~odl-team/+archive/ubuntu/nitrogen "ODL Nitrogen Deb repo"
493
494 [4]: https://git.opendaylight.org/gerrit/gitweb?p=integration/packaging/puppet-opendaylight.git;a=blob;f=CONTRIBUTING.markdown "Contributing docs"
495
496 [5]: https://git.opendaylight.org/gerrit/gitweb?p=integration/packaging/puppet-opendaylight.git;a=blob;f=CHANGELOG "Chagelog"