X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2Fgetting-started-guide%2Finstalling_opendaylight.rst;h=0e4743c206a98d95a44f783a8309086f4e3a6981;hb=HEAD;hp=1f46d0d8b252a32a0ed73ac47bfe65dd0889efd1;hpb=9e1777fd68269d28e1bc7fef2959d59a0e4c6154;p=docs.git diff --git a/docs/getting-started-guide/installing_opendaylight.rst b/docs/getting-started-guide/installing_opendaylight.rst index 1f46d0d8b..0e4743c20 100644 --- a/docs/getting-started-guide/installing_opendaylight.rst +++ b/docs/getting-started-guide/installing_opendaylight.rst @@ -1,5 +1,8 @@ +.. _install_odl: + +*********************** Installing OpenDaylight -======================= +*********************** You complete the following steps to install your networking environment, with specific instructions provided in the subsections below. @@ -11,10 +14,70 @@ Known issues and limitations Install OpenDaylight --------------------- +==================== + +Downloading and installing OpenDaylight +--------------------------------------- + +The default distribution can be found on the OpenDaylight software +download page: https://docs.opendaylight.org/en/latest/downloads.html + +The Karaf distribution has no features enabled by default. However, all +of the features are available to be installed. + +.. note:: For compatibility reasons, you cannot enable all the features + simultaneously. We try to document known incompatibilities in + the `Install the Karaf features`_ section below. + +Running the karaf distribution +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To run the Karaf distribution: + +#. Unzip the zip file. +#. Navigate to the directory. +#. run ``./bin/karaf``. + +For Example:: + + $ ls karaf-0.8.x-Oxygen.zip + karaf-0.8.x-Oxygen.zip + $ unzip karaf-0.8.x-Oxygen.zip + Archive: karaf-0.8.x-Oxygen.zip + creating: karaf-0.8.x-Oxygen/ + creating: karaf-0.8.x-Oxygen/configuration/ + creating: karaf-0.8.x-Oxygen/data/ + creating: karaf-0.8.x-Oxygen/data/tmp/ + creating: karaf-0.8.x-Oxygen/deploy/ + creating: karaf-0.8.x-Oxygen/etc/ + creating: karaf-0.8.x-Oxygen/externalapps/ + ... + inflating: karaf-0.8.x-Oxygen/bin/start.bat + inflating: karaf-0.8.x-Oxygen/bin/status.bat + inflating: karaf-0.8.x-Oxygen/bin/stop.bat + $ cd distribution-karaf-0.8.x-Oxygen + $ ./bin/karaf + + ________ ________ .__ .__ .__ __ + \_____ \ ______ ____ ____ \______ \ _____ ___.__.\| \| \|__\| ____ \| \|___/ \|_ + / \| \\____ \_/ __ \ / \ \| \| \\__ \< \| \|\| \| \| \|/ ___\\| \| \ __\ + / \| \ \|_> > ___/\| \| \\| ` \/ __ \\___ \|\| \|_\| / /_/ > Y \ \| + \_______ / __/ \___ >___\| /_______ (____ / ____\|\|____/__\___ /\|___\| /__\| + \/\|__\| \/ \/ \/ \/\/ /_____/ \/ + + + +* Press ``tab`` for a list of available commands +* Typing ``[cmd] --help`` will show help for a specific command. +* Press ``ctrl-d`` or type ``system:shutdown`` or ``logout`` to shutdown OpenDaylight. + +.. note:: Please take a look at the :ref:`security_deployment_recommendations` + and following sections under :ref:`security_considerations` if you're + planning on running OpenDaylight outside of an isolated test lab + environment. Install the Karaf features --------------------------- +========================== To install a feature, use the following command, where feature1 is the feature name listed in the table below:: @@ -29,13 +92,13 @@ You can install multiple features using the following command:: simultaneously. The table below documents feature installation names and known incompatibilities.Compatibility values indicate the following: -* *all* - the feature can be run with other features. -* *self+all* - the feature can be installed with other features with a value of - *all*, but may interact badly with other features that have a value of - *self+all*. Not every combination has been tested. +* **all** - the feature can be run with other features. +* **self+all** - the feature can be installed with other features with a value of + **all**, but may interact badly with other features that have a value of + **self+all**. Not every combination has been tested. Uninstalling features -^^^^^^^^^^^^^^^^^^^^^ +--------------------- To uninstall a feature, you must shut down OpenDaylight, delete the data directory, and start OpenDaylight up again. @@ -43,7 +106,7 @@ directory, and start OpenDaylight up again. is not supported and can cause unexpected and undesirable behavior. Listing available features -^^^^^^^^^^^^^^^^^^^^^^^^^^ +-------------------------- To find the complete list of Karaf features, run the following command:: feature:list @@ -52,533 +115,27 @@ To list the installed Karaf features, run the following command:: feature:list -i -Features to implement networking functionality provide release notes you can -access on the OpenDaylight Wiki: https://wiki.opendaylight.org/view/Project_list - -* Authentication, Authorization and Accounting (AAA_) -* ALTO_ -* BGPCEP_ -* Controller_ -* Control And Provisioning of Wireless Access Points (CAPWAP_) -* Identification and Driver Management (DIDM_) -* DLUX_ -* FaaS_ -* Group_Based_Policy_ (GPB) -* Internet of Things Data Management (IoTDM_) -* L2_Switch_ -* Link Aggregation Control Protocol (LACP_) -* LISP_Flow_Mapping_ -* MDSAL_ -* NEMO_ -* NETCONF_ -* NetIDE_ -* NeXt_ -* Network Intent Composition (NIC_) -* Neutron_Northbound_ -* OF-Config_ -* OpFlex_ -* OpenFlow_Plugin_ -* OpenFlow_Protocol_Library_ -* OVSDB_Netvirt_ -* Packet_Cable_ / PCMM -* SDN_Interface_Application_ -* Secure Network Bootstrapping Infrastructure (SNBI_) -* SNMP4SDN_ -* SNMP_Plugin_ -* Secure tag eXchange Protocol (SXP_) -* Service Function Chaining (SFC_) -* TCPMD5_ -* Time Series Data Repository (TSDR_) -* Table Type Patterns (TTP_) -* Topology_Processing_Framework_ -* Unified Secure Channel (USC_) -* VPN_Service_ -* Virtual Tenant Network (VTN_) -* YANG_Tools_ - -Projects without Release Notes -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The following projects participated in Beryllium, but intentionally do not have -release notes: - -* The Documentation Project produced this and the other downloadable - documentation. -* The Integration Group hosted the OpenDaylight-wide tests and main release - distribution. -* Controller Core Functionality Tutorials provided a single test suite - (dsbenchmark) that was used as part of integration testing -* Release Engineering used autorelease to build the Beryllium release artifacts, - including the main release download. - -Beryllium features ------------------- - -.. list-table:: Beryllium features - :widths: 10 25 10 5 - :header-rows: 1 - - * - Feature Name - - Feature Description - - Karaf feature name - - Compatibility - - * - Authentication - - Enables authentication with support for federation using Apache Shiro - - odl-aaa-shiro - - all - - * - BGP - - Provides support for Border Gateway Protocol (including Link-State - Distribution) as a source of L3 topology information - - odl-bgpcep-bgp - - all - - * - BMP - - Provides support for BGP Monitoring Protocol as a monitoring station - - odl-bgpcep-bmp - - all - - * - DIDM - - Device Identification and Driver Management - - odl-didm-all - - all - - * - Centinel - - Provides interfaces for streaming analytics - - odl-centinel-all - - all - - * - DLUX - - Provides an intuitive graphical user interface for OpenDaylight - - odl-dlux-all - - all - * - Fabric as a Service (Faas) - - Creates a common abstraction layer on top of a physical network so - northbound APIs or services can be more easiliy mapped onto the - physical network as a concrete device configuration - - odl-faas-all - - all - - * - Group Based Policy - - Enables Endpoint Registry and Policy Repository REST APIs and associated - functionality for Group Based Policy with the default renderer for - OpenFlow renderers - - odl-groupbasedpolicy-ofoverlay - - all - - * - GBP User Interface - - Enables a web-based user interface for Group Based Policy - - odl-groupbasedpolicyi-ui - - all - - * - GBP FaaS renderer - - Enables the Fabric as a Service renderer for Group Based Policy - - odl-groupbasedpolicy-faas - - self+all - - * - GBP Neutron Support - - Provides OpenStack Neutron support using Group Based Policy - - odl-groupbasedpolicy-neutronmapper - - all - - * - L2 Switch - - Provides L2 (Ethernet) forwarding across connected OpenFlow switches and - support for host tracking - - odl-l2switch-switch-ui - - self+all - - * - LACP - - Enables support for the Link Aggregation Control Protocol - - odl-lacp-ui - - self+all - - * - LISP Flow Mapping - - Enables LISP control plane services including the mapping system - services REST API and LISP protocol SB plugin - - odl-lispflowmapping-msmr - - all - - * - NEMO CLI - - Provides intent mappings and implementation with CLI for legacy devices - - odl-nemo-cli-renderer - - all - - * - NEMO OpenFlow - - Provides intent mapping and implementation for OpenFlow devices - - odl-nemo-openflow-renderer - - self+all - - * - NetIDE - - Enables portabilty and cooperation inside a single network by using a - client/server multi-controller architecture - - odl-netide-rest - - all - - * - NETCONF over SSH - - Provides support to manage NETCONF-enabled devices over SSH - - odl-netconf-connector-ssh - - all - - * - OF-CONFIG - - Enables remote configuration of OpenFlow datapaths - - odl-of-config-rest - - all - - * - OVSDB OpenStack Neutron - - OpenStack Network Virtualization using OpenDaylight's OVSDB support - - odl-ovsdb-openstack - - all - - * - OVSDB Southbound - - OVSDB MDSAL southbound plugin for Open_vSwitch schema - - odl-ovsdb-southbound-impl-ui - - all - - * - OVSDB HWVTEP Southbound - - OVSDB MDSAL hwvtep southbound plugin for the hw_vtep schema - - odl-ovsdb-hwvtepsouthbound-ui - - all - - * - OVSDB NetVirt SFC - - OVSDB NetVirt support for SFC - - odl-ovsdb-sfc-ui - - all - - * - OpenFlow Flow Programming - - Enables discovery and control of OpenFlow switches and the topoology - between them - - odl-openflowplugin-flow-services-ui - - all - - * - OpenFlow Table Type Patterns - - Allows OpenFlow Table Type Patterns to be manually associated with - network elements - - odl-ttp-all - - all - - * - Packetcable PCMM - - Enables flow-based dynamic QoS management of CMTS use in the DOCSIS - infrastructure and a policy server - - odl-packetcable-policy-server - - self+all - - * - PCEP - - Enables support for PCEP - - odl-bgpcep-pcep - - all - - * - RESTCONF API Support - - Enables REST API access to the MD-SAL including the data store - - odl-restconf - - all - - * - SDNinterface - - Provides support for interaction and sharing of state between - (non-clustered) OpenDaylight instances - - odl-sdninterfaceapp-all - - all - - * - SFC over L2 - - Supports implementing Service Function Chaining using Layer 2 - forwarding - - odl-sfcofl2 - - self+all - - * - SFC over LISP - - Supports implementing Service Function Chaining using LISP - - odl-sfclisp - - all - - * - SFC over REST - - Supports implementing Service Function Chaining using REST CRUD - operations on network elements - - odl-sfc-sb-rest - - all - - * - SFC over VXLAN - - Supports implementing Service Function Chaining using VXLAN tunnels - - odl-sfc-ovs - - self+all - - * - SNMP Plugin - - Enables monitoring and control of network elements via SNMP - - odl-snmp-plugin - - all - - * - SNMP4SDN - - Enables OpenFlow-like control of network elements via SNMP - - odl-snmp4sdn-all - - all - - * - SSSD Federated Authentication - - Enables support for federated authentication using SSSD - - odl-aaa-sssd-plugin - - all - - * - Secure tag eXchange Protocol (SXP) - - Enables distribution of shared tags to network devices - - odl-sxp-controller - - all - - * - Time Series Data Repository (TSDR) - - Enables support for storing and querying time series data with the - default data collector for OpenFlow statistics the default data store - for HSQLDB - - odl-tsdr-hsqldb-all - - all - - * - TSDR Data Collectors - - Enables support for various TSDR data sources (collectors) including - OpenFlow statistics, NetFlow statistics, NetFlow statistics, SNMP data, - Syslog, and OpenDaylight (controller) metrics - - odl-tsdr-openflow-statistics-collector, - odl-tsdr-netflow-statistics-collector, - odl-tsdr-snmp-data-collector, - odl-tsdr-syslog-collector, - odl-tsdr-controller-metrics-collector - - all - - * - TSDR Data Stores - - Enables support for TSDR data stores including HSQLDB, HBase, and - Cassandra - - odl-tsdr-hsqldb, odl-tsdr-hbase, or odl-tsdr-cassandra - - all - - * - Topology Processing Framework - - Enables merged and filtered views of network topologies - - odl-topoprocessing-framework - - all - - * - Unified Secure Channel (USC) - - Enables support for secure, remote connections to network devices - - odl-usc-channel-ui - - all - - * - VPN Service - - Enables support for OpenStack VPNaaS - - odl-vpnservice-core - - all - - * - VTN Manager - - Enables Virtual Tenant Network support - - odl-vtn-manager-rest - - self+all - - * - VTN Manager Neutron - - Enables OpenStack Neutron support of VTN Manager - - odl-vtn-manager-neutron - - self+all - - -Other Beryllium features ------------------------- - -.. list-table:: Other Beryllium features - :widths: 10 25 10 5 - :header-rows: 1 - - * - Feature Name - - Feature Description - - Karaf feature name - - Compatibility - - * - OpFlex - - Provides OpFlex agent for Open vSwitch to enforce network policy, such - as GBP, for locally-attached virtual machines or containers - - n/a - - all - - * - NeXt - - Provides a developer toolkit for designing network-centric topology - user interfaces - - n/a - - all - - -Experimental Beryllium Features -------------------------------- -The following functionality is labeled as experimental in OpenDaylight -Beryllium and should be used accordingly. In general, it is not supposed to be -used in production unless its limitations are well understood by those -deploying it. - -.. list-table:: Other Beryllium features - :widths: 10 25 10 5 - :header-rows: 1 - - * - Feature Name - - Feature Description - - Karaf feature name - - Compatibility - - * - Authorization - - Enables configurable role-based authorization - - odl-aaa-authz - - all - - * - ALTO - - Enables support for Application-Layer Traffic Optimization - - odl-alto-core - - self+all - - * - CAPWAP - - Enables control of supported wireless APs - - odl-capwap-ac-rest - - all - - * - Clustered Authentication - - Enables the use of the MD-SAL clustered data store for the - authentication database - - odl-aaa-authn-mdsal-cluster - - all - - * - Controller Shield - - Provides controller security information to northbound applications - - odl-usecplugin - - all - - * - GBP IO Visor Renderer - - Provides support for rendering Group Based Policy to IO Visor - - odl-groupbasedpolicy-iovisor - - all - - * - Internet of Things Data Management - - Enables support for the oneM2M specification - - odl-iotdm-onem2m - - all - - * - LISP Flow Mapping OpenStack Network Virtualization - - Experimental support for OpenStack Neutron virtualization - - odl-lispflowmapping-neutron - - self+all - - * - Messaging4Transport - - Introduces an AMQP Northbound to MD-SAL - - odl-messaging4transport - - all - - * - Network Intent Composition (NIC) - - Provides abstraction layer for communcating network intents (including - a distributed intent mapping service REST API) using either Hazelcast - or the MD-SAL as the backing data store for intents - - odl-nic-core-hazelcast or odl-nic-core-mdsal - - all - - * - NIC Console - - Provides a Karaf CLI extension for intent CRUD operations and mapping - service operations - - odl-nic-console - - all - - * - NIC VTN renderer - - Virtual Tenant Network renderer for Network Intent Composition - - odl-nic-renderer-vtn - - self+all - - * - NIC GBP renderer - - Group Based Policy renderer for Network Intent Composition - - odl-nic-renderer-gbp - - self+all - - * - NIC OpenFlow renderer - - OpenFlow renderer for Network Intent Composition - - odl-nic-renderer-of - - self+all - - * - NIC NEMO renderer - - NEtwork MOdeling renderer for Network Intent Composition - - odl-nic-renderer-nemo - - self+all - - * - OVSDB NetVirt UI - - OVSDB DLUX UI - - odl-ovsdb-ui - - all - - * - Secure Networking Bootstrap - - Defines a SNBi domain and associated white lists of devices to be - accommodated to the domain - - odl-snbi-all - - self+all - - * - UNI Manager - - Initiates the development of data models and APIs to facilitate - configuration and provisioning connectivity services for OpenDaylight - applications and services - - odl-unimgr - - all - - * - YANG PUBSUB - - Allows subscriptions to be placed on targeted subtrees of YANG - datastores residing on remote devices to obviate the need for - OpenDaylight to make continuous fetch requests - - odl-yangpush-rest - - all - -Install support for REST APIs ------------------------------ -Most components that offer REST APIs will automatically load the RESTCONF API -Support component, but if for whatever reason they seem to be missing, install -the “odl-restconf” feature to activate this support. - - -Install the DLUX interface --------------------------- -OpenDaylight’s DLUX web interface draws information from topology and host -databases to display information about the topology of the network, flow -statistics, and host locations. - -To integrate with OpenDaylight you must enable the DLUX Karaf feature. Each -feature can be enabled or disabled separately. Ensure that you have created a -topology and enabled the MD-SAL feature in the Karaf distribution before you -use DLUX for network management. For more information about enabling the Karaf -features for DLUX, refer to Enable_DLUX_Feature_. - -MD-SAL clustering ------------------ -In the Beryllium release and newer, the odl-mdsal-broker installs MD-SAL -clustering automatically. - -.. _Enable_DLUX_Feature: https://wiki.opendaylight.org/view/DLUX:Beryllium_System_Test_Plan#Enabling_The_Feature - - -.. _AAA: https://wiki.opendaylight.org/view/AAA:Beryllium_Release_Notes -.. _ALTO: https://wiki.opendaylight.org/view/ALTO:Beryllium:Release_Notes -.. _BGPCEP: https://wiki.opendaylight.org/view/BGP_LS_PCEP:Beryllium_Release_Notes -.. _CAPWAP: https://wiki.opendaylight.org/view/CAPWAP:Beryllium:Release_Notes -.. _Controller: https://wiki.opendaylight.org/view/OpenDaylight_Controller:Beryllium:Release_Notes -.. _DIDM: https://wiki.opendaylight.org/view/DIDM:_Beryllium_Release_Notes -.. _DLUX: https://wiki.opendaylight.org/view/OpenDaylight_DLUX:Beryllium:Release_Notes -.. _FaaS: https://wiki.opendaylight.org/view/FaaS:Beryllium_Release_Notes -.. _Group_Based_Policy: https://wiki.opendaylight.org/view/Group_Based_Policy_(GBP)/Releases/Beryllium:Beryllium_Release_Notes -.. _IoTDM: https://wiki.opendaylight.org/view/Iotdm:Beryllium_Release_Notes -.. _L2_Switch: https://wiki.opendaylight.org/view/L2_Switch:Beryllium:Release_Notes -.. _LACP: https://wiki.opendaylight.org/view/LACP:Beryllium:Release_Notes -.. _LISP_Flow_Mapping: https://wiki.opendaylight.org/view/OpenDaylight_Lisp_Flow_Mapping:Beryllium_Release_Notes -.. _MDSAL: https://wiki.opendaylight.org/view/MD-SAL:Beryllium:Release_Notes -.. _NEMO: https://wiki.opendaylight.org/view/NEMO:Beryllium:Release_Notes -.. _NETCONF: https://wiki.opendaylight.org/view/OpenDaylight_NETCONF:Beryllium_Release_Notes -.. _NetIDE: https://wiki.opendaylight.org/view/NetIDE:Release_Notes -.. _NeXt: https://wiki.opendaylight.org/view/NeXt:Beryllium_Release_Notes -.. _NIC: https://wiki.opendaylight.org/view/Network_Intent_Composition:Release_Notes -.. _Neutron_Northbound: https://wiki.opendaylight.org/view/NeutronNorthbound:Beryllium:Release_Notes -.. _OF-Config: https://wiki.opendaylight.org/view/OF-CONFIG:Beryllium:Release_Notes -.. _OpFlex: https://wiki.opendaylight.org/view/OpFlex:Beryllium_Release_Notes -.. _OpenFlow_Plugin: https://wiki.opendaylight.org/view/OpenDaylight_OpenFlow_Plugin:Beryllium_Release_Notes -.. _OpenFlow_Protocol_Library: https://wiki.opendaylight.org/view/Openflow_Protocol_Library:Release_Notes:Beryllium_Release_Notes -.. _OVSDB_Netvirt: https://wiki.opendaylight.org/view/OpenDaylight_OVSDB:Beryllium_Release_Notes -.. _Packet_Cable: https://wiki.opendaylight.org/view/PacketCablePCMM:BerylliumReleaseNotes -.. _SDN_Interface_Application: https://wiki.opendaylight.org/view/ODL-SDNi:Beryllium_Release_Notes -.. _SNBI: https://wiki.opendaylight.org/view/SNBI_Berrylium_Release_Notes -.. _SNMP4SDN: https://wiki.opendaylight.org/view/SNMP4SDN:Beryllium_Release_Note -.. _SNMP_Plugin: https://wiki.opendaylight.org/view/SNMP_Plugin:SNMP_Plugin:Beryllium_Release_Notes -.. _SXP: https://wiki.opendaylight.org/view/SXP:Beryllium:Release_Notes -.. _SFC: https://wiki.opendaylight.org/view/Service_Function_Chaining:Beryllium_Release_Notes -.. _TCPMD5: https://wiki.opendaylight.org/view/TCPMD5:Beryllium_Release_Notes -.. _TSDR: https://wiki.opendaylight.org/view/TSDR:Beryllium:Release_Notes -.. _TTP: https://wiki.opendaylight.org/view/Table_Type_Patterns/Beryllium/Release_Notes -.. _Topology_Processing_Framework: https://wiki.opendaylight.org/view/Topology_Processing_Framework:BERYLLIUM_Release_Notes -.. _USC: https://wiki.opendaylight.org/view/USC:Beryllium:Release_Notes -.. _VPN_Service: https://wiki.opendaylight.org/view/Vpnservice:Beryllium_Release_Notes -.. _VTN: https://wiki.opendaylight.org/view/VTN:Beryllium:Release_Notes -.. _YANG_Tools: https://wiki.opendaylight.org/view/YANG_Tools:Beryllium:Release_Notes +The description of these features is in the project specific +release notes :ref:`proj_rel_notes` section. + +Karaf running on Windows 10 +--------------------------- + +Windows 10 cannot be identify by Karaf (equinox). +Issue occurs during installation of karaf features e.g.:: + + opendaylight-user@root>feature:install odl-restconf + Error executing command: Can't install feature odl-restconf/0.0.0: + Could not start bundle mvn:org.fusesource.leveldbjni/leveldbjni-all/1.8-odl in feature(s) odl-akka-leveldb-0.7: The bundle "org.fusesource.leveldbjni.leveldbjni-all_1.8.0 [300]" could not be resolved. Reason: No match found for native code: META-INF/native/windows32/leveldbjni.dll; processor=x86; osname=Win32, META-INF/native/windows64/leveldbjni.dll; processor=x86-64; osname=Win32, META-INF/native/osx/libleveldbjni.jnilib; processor=x86; osname=macosx, META-INF/native/osx/libleveldbjni.jnilib; processor=x86-64; osname=macosx, META-INF/native/linux32/libleveldbjni.so; processor=x86; osname=Linux, META-INF/native/linux64/libleveldbjni.so; processor=x86-64; osname=Linux, META-INF/native/sunos64/amd64/libleveldbjni.so; processor=x86-64; osname=SunOS, META-INF/native/sunos64/sparcv9/libleveldbjni.so; processor=sparcv9; osname=SunOS + +Workaround is to add:: + + org.osgi.framework.os.name = Win32 + +to the karaf file:: + + etc/system.properties + +The workaround and further info are in this thread: +https://stackoverflow.com/questions/35679852/karaf-exception-is-thrown-while-installing-org-fusesource-leveldbjni +