X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=blobdiff_plain;f=README.markdown;h=4ca99bbe3a6dbdcb8cbe17d61d31dfb8389b2d93;hb=4ab2b0cf3a3ce6287cc6336a2e3f125fd0f98bb1;hp=b7222d534ddf9eb1573b97ddcaeb952e54aa9749;hpb=66ea92fd904cc8ccda190cb3192068f93de2ffd9;p=integration%2Fpackaging%2Fpuppet-opendaylight.git diff --git a/README.markdown b/README.markdown index b7222d5..4ca99bb 100644 --- a/README.markdown +++ b/README.markdown @@ -1,6 +1,3 @@ -[![CI Status][4]][1] -[![Dependency Status][5]][2] - # OpenDaylight #### Table of Contents @@ -8,15 +5,19 @@ 1. [Overview](#overview) 2. [Module Description](#module-description) 3. [Setup](#setup) - - [What `opendaylight` affects](#what-opendaylight-affects) - - [Beginning with `opendaylight`](#beginning-with-opendaylight) + +- [What `opendaylight` affects](#what-opendaylight-affects) +- [Beginning with `opendaylight`](#beginning-with-opendaylight) + 4. [Usage](#usage) - - [Karaf Features](#karaf-features) - - [RPM Repo](#rpm-repo) - - [Deb Repo](#deb-repo) - - [Ports](#ports) - - [Log Verbosity](#log-verbosity) - - [Enabling ODL OVSDB HA](#enabling-odl-ovsdb-ha) + +- [Karaf Features](#karaf-features) +- [RPM Repo](#rpm-repo) +- [Deb Repo](#deb-repo) +- [Ports](#ports) +- [Log Verbosity](#log-verbosity) +- [Enabling ODL HA](#enabling-odl-ha) + 5. [Reference ](#reference) 6. [Limitations](#limitations) 7. [Development](#development) @@ -25,19 +26,18 @@ ## Overview Puppet module that installs and configures the [OpenDaylight Software Defined -Networking (SDN) controller][7]. +Networking (SDN) controller][1]. ## Module Description Deploys OpenDaylight to various OSs either via an RPM or a Deb. All OpenDaylight configuration should be handled through the ODL Puppet -module's [params](#parameters). If you need a new knob, [please raise an -Issue][8]. +module's [params](#parameters). -By default, the master branch installs OpenDaylight from the latest testing RPM repository -or from the latest stable Deb repository depending on the OS. There are stable/ -branches that install OpenDaylight releases and service releases, like Beryllium or Beryllium SR3. +By default, the master branch installs OpenDaylight from the latest testing +RPM repository or from the latest stable Deb repository depending on the OS. +The stable/ branches install corresponding older ODL versions. ## Setup @@ -45,8 +45,7 @@ branches that install OpenDaylight releases and service releases, like Beryllium - Installs Java, which is required by ODL. - Creates `odl:odl` user:group if they don't already exist. -- Installs [OpenDaylight][7]. -- Installs a [systemd unitfile][9] for OpenDaylight. +- Installs [OpenDaylight][1], including a systemd unit file. - Manipulates OpenDaylight's configuration files according to the params passed to the `::opendaylight` class. - Starts the `opendaylight` systemd service. @@ -56,57 +55,6 @@ branches that install OpenDaylight releases and service releases, like Beryllium Getting started with the OpenDaylight Puppet module is as simple as declaring the `::opendaylight` class. -The [vagrant-opendaylight][11] project provides an easy way to experiment -with [applying the ODL Puppet module][12] to CentOS 7, Fedora 22, Fedora -23 and Ubuntu 16.04 Vagrant boxes. - -``` -[~/vagrant-opendaylight]$ vagrant status -Current machine states: - -cent7_li_sr4 not created (virtualbox) -cent7_be not created (virtualbox) -cent7_be_sr1 not created (virtualbox) -cent7_be_sr2 not created (virtualbox) -cent7_rpm_he_sr4 not created (virtualbox) -cent7_rpm_li_sr2 not created (virtualbox) -cent7_rpm_li_sr3 not created (virtualbox) -cent7_rpm_be not created (virtualbox) -cent7_rpm_be_sr1 not created (virtualbox) -cent7_rpm_be_sr2 not created (virtualbox) -cent7_rpm_ve_latest not created (virtualbox) -cent7_ansible not created (virtualbox) -cent7_ansible_latest not created (virtualbox) -cent7_ansible_path not created (virtualbox) -cent7_pup_rpm not created (virtualbox) -cent7_pup_custom_logs not created (virtualbox) -cent7_pup_enable_l3 not created (virtualbox) -cent7_pup_tb not created (virtualbox) -f22_rpm_li not created (virtualbox) -f22_ansible not created (virtualbox) -f22_pup_rpm not created (virtualbox) -f23_rpm_li not created (virtualbox) -f23_rpm_li_sr1 not created (virtualbox) -f23_rpm_li_sr2 not created (virtualbox) -f23_rpm_li_sr3 not created (virtualbox) -f23_rpm_be not created (virtualbox) -f23_rpm_be_rel not created (virtualbox) -f23_rpm_be_latest not created (virtualbox) -f23_ansible not created (virtualbox) -f23_pup_rpm not created (virtualbox) -debian8_ansible_repo not created (virtualbox) -debian8_ansible_path not created (virtualbox) -ubuntu16_ansible_repo not created (virtualbox) -ubuntu16_ansible_path not created (virtualbox) -ubuntu16_pup_deb not created (virtualbox) - -[~/vagrant-opendaylight]$ vagrant up cent7_pup_rpm -# A CentOS 7 VM is created and configured using the ODL Puppet mod's defaults -[~/vagrant-opendaylight]$ vagrant ssh cent7_pup_rpm -[vagrant@localhost ~]$ sudo systemctl is-active opendaylight -active -``` - ## Usage The most basic usage, passing no parameters to the OpenDaylight class, will @@ -126,7 +74,7 @@ certainly need to pass some. ```puppet class { 'opendaylight': - extra_features => ['odl-ovsdb-plugin', 'odl-ovsdb-openstack'], + extra_features => ['odl-netvirt-openstack'], } ``` @@ -141,52 +89,42 @@ class { 'opendaylight': } ``` -### RPM Repo +### RPM Repository The `rpm_repo` param can be used to configure which RPM repository OpenDaylight is installed from. ```puppet class { 'opendaylight': - rpm_repo => 'opendaylight-40-release', + rpm_repo => 'https://nexus.opendaylight.org/content/repositories/opendaylight-neon-epel-7-$basearch-devel', } ``` -The naming convention follows the naming convention of the CentOS Community -Build System, which is where upstream ODL hosts its RPMs. The -`opendaylight-40-release` example above would install OpenDaylight Beryllium -4.0.0 from the [nfv7-opendaylight-40-release][18] repo. Repo names ending in -`-release` will always contain well-tested, officially released versions of -OpenDaylight. Repos ending in `-testing` contain frequent, but unstable and -unofficial, releases. The ODL version given in repo names shows which major -and minor version it is pinned to. The `opendaylight-40-release` repo will -always provide OpenDaylight Beryllium 4.0, whereas `opendaylight-4-release` -will provide the latest release with major version 4 (which could include -Service Releases, like SR2 4.2). +The URL should be formatted like a baseurl in RPM .repo config files. In +particular, note the $basearch variable, which should be left form the +package manager (yum, dnf) to populate. -For a full list of OpenDaylight releases and their CBS repos, see the -[OpenDaylight Deployment wiki][19]. +For additional information about ODL RPM repos, see the [Integration/Packaging +RPM repositories documentation][2]. -This is only read for RedHat based operating systems. For Debian based OSs, -this values is `none`. +This is only read for Red Hat-family operating systems. -### Deb Repo +### Deb Repository The `deb_repo` param can be used to configure which Deb repository OpenDaylight is installed from. ```puppet class { 'opendaylight': - deb_repo => 'ppa:odl-team/boron', + deb_repo => 'ppa:odl-team/nitrogen', } ``` The naming convention is same as the naming convention of Launchpad PPA's, -which is where ODL .debs are hosted. The `ppa:odl-team/boron` example above -would install OpenDaylight Boron realease from the [odl-team's boron][20] repo. +which is where ODL .debs are hosted. The `ppa:odl-team/nitrogen` example above +would install OpenDaylight Nitrogen from the [Nitrogen launchpad repo][3]. -This is only read for Debian based operating systems. For RedHat based OSs, -this values is `none`. +This is only read for Debian-family operating systems. ### Ports @@ -195,7 +133,7 @@ calls, use the `odl_rest_port` param. ```puppet class { 'opendaylight': - odl_rest_port => '8080', + odl_rest_port => '8181', } ``` @@ -210,24 +148,60 @@ class { 'opendaylight': } ``` -### Enabling ODL OVSDB HA +### Enabling ODL HA -To enable ODL OVSDB HA, use the `enable_ha` flag. It's disabled by default. +To enable ODL HA, use the `enable_ha` flag. It's disabled by default. When `enable_ha` is set to true the `ha_node_ips` should be populated with the -IP addresses that ODL will listen on for each node in the OVSDB HA cluster and -`ha_node_index` should be set with the index of the IP address from -`ha_node_ips` for the particular node that puppet is configuring as part of the +IP addresses that ODL will listen on for each node in the HA cluster and +`odl_bind_ip` should be set with the IP address from `ha_node_ips` configured +for the particular node that puppet is configuring as part of the HA cluster. +By default a single ODL instance will become the leader for the entire +datastore. In order to distribute the datastore over multiple ODL instances, +`ha_db_modules` parameter may be specified which will include the modules +desired to separate out from the default shard, along with the Yang namespace +for that module. + ```puppet class { 'opendaylight': enable_ha => true, ha_node_ips => ['10.10.10.1', '10.10.10.1', '10.10.10.3'], - ha_node_index => 0, + odl_bind_ip => 0, + ha_db_modules => {'default' => false, 'topology' => 'urn:opendaylight:topology'} } ``` +### Configuring websocket address + +Websocket address can be configured to the IP of ODL rather than default 0.0.0.0. This IP will +be defined by `odl_bind_ip`. + +### Enabling TLS with OpenDaylight + +It is possible to enable TLS encrypted communication for OpenDaylight Northbound REST +along with Southbound OVSDB/OpenFlow communication with Open vSwitch. To enable +TLS, use the `enable_tls` flag. This option will create two keystores in OpenDaylight +which are stored in '/opt/opendaylight/configuration/ssl'. The first keystore +is the controller keystore, which will hold the private key and ODL certificate, +along with the Certificate Authority (CA) certificate if provided. The second +keystore is the trust keystore, which will hold the trusted OVS switch certificates. + +In order to enable TLS, it is required to provide the `tls_keystore_password` +parameter. This represents the password to use for the controller and truststore +keystores. With only providing these parameters, ODL will generate the +controller keystore with a random private key and self-signed certficate. + +Additionally the `tls_key_file` and `tls_cert_file` parameters may be provided. +These represent ODL's private key file and certificate file to be used when building +the controller keystore. Optionally the `tls_ca_cert_file` may be provided which +will chain the CA certificate to the keystore for client validation. + +`tls_trusted_certs` may be provided as an array of trusted certificates to be +added to the trusted keystore. This allows OpenDaylight to identify trusted +clients which may connect to ODL Southbound and Northbound. + ## Reference ### Classes @@ -273,19 +247,18 @@ Valid options: A list of Karaf feature names as strings. Specifies the port for the ODL northbound REST interface to listen on. -Default: `'8080'` +Default: `'8181'` Valid options: A valid port number as a string or integer. ##### `rpm_repo` -OpenDaylight CentOS CBS repo to install RPM from (opendaylight-4-testing, -opendaylight-40-release, ...). +Repo URL to install ODL RPM from, in .repo baseurl format. ##### `deb_repo` OpenDaylight Launchpad PPA repo to install .deb from (ppa:odl-team/boron, -ppa:odl-team/carbon, ...). +ppa:odl-team/nitrogen, ...). ##### `log_levels` @@ -306,10 +279,12 @@ The above example would add the following logging configuration to ``` # Log level config added by puppet-opendaylight -log4j.logger.org.opendaylight.ovsdb = TRACE +log4j2.logger.org_opendaylight_ovsdb.level = TRACE +log4j2.logger.org_opendaylight_ovsdb.name = org.opendaylight.ovsdb # Log level config added by puppet-opendaylight -log4j.logger.org.opendaylight.ovsdb.lib = INFO +log4j2.logger.org_opendaylight_ovsdb_lib.level = INFO +log4j2.logger.org_opendaylight_ovsdb_lib.name = org.opendaylight.ovsdb.lib ``` To view loggers and their verbosity levels, use `log:list` at the ODL Karaf shell. @@ -325,17 +300,103 @@ org.opendaylight.ovsdb.lib | INFO The main log output file is `/opt/opendaylight/data/log/karaf.log`. +##### `log_max_size` + +Maximum size of OpenDaylight's log file, `/opt/opendaylight/data/log/karaf.log`. + +Once this size is reached, the log will be rolled over, with up to +`log_max_rollover` log rollovers preserved in total. + +Default: `10GB` + +Valid options: A valid size as a string with unit specified. + +##### `log_max_rollover` + +Maximum number of OpenDaylight karaf.log rollovers to keep. + +Note that if this is set to 1, log rollovers will result in loosing newly +logged data. It's recommended to use values greater than one to prune from +the end of the log. + +Default: `2` + +Valid options: An integer greater than 0. + +##### `log_rollover_fileindex` + +String that controls file index to use when log rollovers are initiated. + +If set to 'max', files with a higher index will be newer than files with +a smaller index. + +If set to 'min', file with a lower index will be newer than files with a +higher index. + +If set to 'nomax', the min and max values will be ignored, and file +numbering will increment by 1 and each rollover will have an +incrementally higher value with no maximum number of files. + +Default: `min` + +Valid options: 'min', 'max', 'nomax' + +##### `log_mechanism` + +Logging mechanism for karaf logs. They are logged either to a file or console. +When `log_mechanism` is `file`, log files are configured as per `log_max_size` +and `log_max_rollover`. + +Default: `file` + +Valid options: `file`, `console`. + +##### `log_pattern` + +String that controls the log pattern used for logging. + +Default: `%d{ISO8601} | %-5p | %-16t | %-60c{6} | %m%n` + +Valid options: A valid string that is a valid log4j2 pattern. + +##### `enable_paxosgi_logger` + +Boolean that controls whether the PaxOsgi appender is enabled for logging. + +Note that enabling this will also require to modify the log pattern to +make use of the added capabilities. To do so the variable `log_pattern` should +be overriden to include a pattern that includes the tokens that PaxOsgi adds. + +This could be achieving, for example, by setting `log_pattern` to a string +that includes: + +'%X{bundle.id} - %X{bundle.name} - %X{bundle.version}' + +Failure to change the `log_pattern` will mean that the PaxOsgi appender will +be enabled but the added functionality not used on the logging. This has no +negative effect on the system and it will continue to run, just it will not +include the added information one could get from PaxOsgi. + +A good example would be to set this variable to `true` and set `log_pattern` +to: + +'%d{ISO8601} | %-5p | %-16t | %-32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n' + +Default: `false` + +Valid options: The boolean values `true` and `false`. + ##### `enable_ha` -Enable or disable ODL OVSDB High Availablity. +Enable or disable ODL High Availablity. Default: `false` Valid options: The boolean values `true` and `false`. -Requires: `ha_node_ips`, `ha_node_index` +Requires: `ha_node_ips`, `odl_bind_ip` -The ODL OVSDB Clustering XML for HA are configured and enabled. +The ODL Clustering XML for HA are configured and enabled. ##### `ha_node_ips` @@ -347,6 +408,16 @@ Valid options: An array of IP addresses `['10.10.10.1', '10.10.10.1', '10.10.10. Required by: `enable_ha` +##### `ha_db_modules` + +Specifies the modules to use for distributing and sharding the ODL datastore. + +Default: `{'default'=> false}` + +Valid options: A hash of module and Yang namespace for the module (default has no namespace). + +Requires: `enable_ha` + ##### `ha_node_index` Specifies the index of the IP for the node being configured from the array `ha_node_ips`. @@ -355,20 +426,20 @@ Default: '' Valid options: Index of a member of the array `ha_node_ips`: `0`. -Required by: `enable_ha`, `ha_node_ips` +This parameter is now deprecated and is no longer used. -##### `security_group_mode` +##### `snat_mechanism` -Specifies the mode to use for security groups. +Specifies the mechanism to be used for SNAT. -Default: `stateful` +Default: `controller` -Valid options: `transparent`, `learn`, `stateless` +Valid options: `conntrack`, `controller` ##### `vpp_routing_node` Specifies the routing node for VPP deployment. A non-empty string will create config file -org.opendaylight.groupbasedpolicy.neutron.vpp.mapper.cfg with routing-node set. +org.opendaylight.groupbasedpolicy.neutron.vpp.mapper.startup.cfg with routing-node set. Default: `''` @@ -376,61 +447,77 @@ Valid options: A valid host name to a VPP node handling routing. ##### `java_opts` -Specifies the Java options to run ODL with as a string. +Specifies the Java options to run ODL with as a string. Note, these options +are in addition to the default Java options set by the karaf/ODL boot scripts +and IP version based flag set by 'opendaylight' class. -Default: `'-Djava.net.preferIPv4Stack=true'` +Default: `''` Valid options: A string of valid Java options. -## Limitations +##### `username` -- Tested on Fedora 22, 23, CentOS 7 and Ubuntu 16.04. -- CentOS 7 is currently the most stable OS option. +Specifies the username to set for admin role in ODL. -## Development +Default: `'admin'` -We welcome contributions and work to make them easy! +Valid options: A username string. -See [CONTRIBUTING.markdown][14] for details about how to contribute to the -OpenDaylight Puppet module. +##### `password` + +Specifies the password to set for admin role in ODL. -## Release Notes/Contributors +Default: `'admin'` -See the [CHANGELOG][15] or our [git tags][16] for information about releases. -See our [git commit history][17] for contributor information. +Valid options: A password string. -[1]: https://travis-ci.org/dfarrell07/puppet-opendaylight +### `inherit_dscp_marking` -[2]: https://gemnasium.com/dfarrell07/puppet-opendaylight +Specifies whether DSCP marking is enabled for packets egressing out of OVS through +VXLAN/GRE tunnels. -[4]: https://travis-ci.org/dfarrell07/puppet-opendaylight.svg +Default: `false` -[5]: https://gemnasium.com/dfarrell07/puppet-opendaylight.svg +Valid options: `true`, `false` -[7]: http://www.opendaylight.org/ +### `stats_polling_enabled` -[8]: https://github.com/dfarrell07/puppet-opendaylight/blob/master/CONTRIBUTING.markdown#issues +Enables statistics polling of OpenFlow entities like table, groups. + +Default: `false` -[9]: https://github.com/dfarrell07/opendaylight-systemd/ +Valid options: `true`, `false` -[10]: https://github.com/dfarrell07/puppet-opendaylight/blob/master/files/upstart.odl.conf +### `inactivity_probe` -[11]: https://github.com/dfarrell07/vagrant-opendaylight/ +Configures inactivity probe timer when specified. -[12]: https://github.com/dfarrell07/vagrant-opendaylight/tree/master/manifests +Default: `undef` -[13]: https://github.com/dfarrell07/puppet-opendaylight/issues/63 +Valid options: An integer or string in milliseconds. + +## Limitations + +- Tested on CentOS 7 and Ubuntu 16.04. +- Fedora is allowed but not well-tested, no Beaker coverage. + +## Development + +We welcome contributions and work to make them easy! + +See [CONTRIBUTING.markdown][4] for details about how to contribute to the +OpenDaylight Puppet module. -[14]: https://github.com/dfarrell07/puppet-opendaylight/blob/master/CONTRIBUTING.markdown +## Release Notes -[15]: https://github.com/dfarrell07/puppet-opendaylight/blob/master/CHANGELOG +See the [CHANGELOG][5] for information about releases. -[16]: https://github.com/dfarrell07/puppet-opendaylight/releases +[1]: http://www.opendaylight.org/ "OpenDaylight homepage" -[17]: https://github.com/dfarrell07/puppet-opendaylight/commits/master +[2]: http://docs.opendaylight.org/en/latest/submodules/integration/packaging/docs/rpms.html#repositories "ODL RPM repo docs" -[18]: "OpenDaylight Beryllium CentOS CBS repo" +[3]: https://launchpad.net/~odl-team/+archive/ubuntu/nitrogen "ODL Nitrogen Deb repo" -[19]: "OpenDaylight RPMs and their repos" +[4]: https://git.opendaylight.org/gerrit/gitweb?p=integration/packaging/puppet-opendaylight.git;a=blob;f=CONTRIBUTING.markdown "Contributing docs" -[20]: https://launchpad.net/~odl-team/+archive/ubuntu/boron +[5]: https://git.opendaylight.org/gerrit/gitweb?p=integration/packaging/puppet-opendaylight.git;a=blob;f=CHANGELOG "Chagelog"