Package: oneview-redfish-toolkit
HPE OneView Redfish ToolkitThis toolkit provides a REST service to answerDMTF's Redfishcompliant requests by querying HPE OneView.HPE OneView is a fresh approach to converged infrastructure management, inspired by the way you expect to work, with a single integrated view of your IT infrastructure.DMTF's Redfish is an open industry standard specification and schema that specifies a RESTful interface and utilizes JSON and OData to help customers integrate solutions within their existing tool chains.Getting startedRequirementsTo install the application:Ubuntu 16.04 (standard server install works fine)Python >=3.5pip >=18.1setuptools >=40.6.3OpenSSL >= 1.0.2gInternet connectivityTo run the application (and make it useful):HPE OneView 4.0 or laterDependenciesAll service dependencies (besides the ones listed under requirements above) will be automatically downloaded and installed as part of installing the service.
A full list of dependencies is available atrequirements.txtfileInstalling the application$pipinstalloneview-redfish-toolkitOffline InstallationObtaining Oneview Redfish Toolkit and dependenciesYou can download offline installer atReleases page.
Or you can download the toolkit from PyPI running this command:$pipdownloadoneview-redfish-toolkitInstallationCreate Python 3.5 virtual environment and activate it:$python3.5-mvenv<virtual-environment-name>
$source<virtual-environment-name>/bin/activateUpdate pip and setuptools to the latest version:$pipinstallpip-U
$pipinstallsetuptools-UUnzip oneview-redfish-toolkit-installer:$unzip<oneview-redfish-toolkit-installer-0.4.0.zip>Run pip install where the files are placed:$pipinstall<oneview-redfish-toolkit-installer-0.4.0>/*Running the applicationThe first time the application is run, it will create all the needed configuration files under user's home directory. It will also prompt for the OneView IP that you wish to connect to the redfish toolkit. This can either be a single IP address, or a comma seperated list of IP addresses.  The configuration is persisted in theredfish.conf.Below is an example run that will add two different OneView instances to the Redfish service:$ oneview-redfish-toolkit
Welcome to oneview-redfish-toolkit. Please enter a comma separated list of OneView IPs you want to connect to.
Oneview IP(s): 192.168.3.100, 192.168.3.101
Using configuration file: /root/.config/oneview-redfish-toolkit/redfish.conf
Using logging configuration file: /root/.config/oneview-redfish-toolkit/logging.conf
oneview-redfish-toolkit service is now available at 0.0.0.0:5000The following files will be created:$HOME/.config/oneview-redfish-toolkit/redfish.conflogging.confredfish.logcerts/Theredfish.confandlogging.confare used  to customize the service, but generally, don't need to be modified. Thecertsdirectory is used to place the retrieved OneView certificates when the Event Service is enabled.You can customize the configuration files created under the user directory, or if you want to use your own custom configuration files you can pass them as arguments. If no arguments are passed, the application will use the ones on user directory:$oneview-redfish-toolkit--configredfish.conf--log-configlogging.confAdditional information about the toolkitToolkit ConfigurationThe toolkit configuration resides onredfish.conffile. All required properties have default values that will work just fine. The only empty required property, OneView IP, will be prompted for user at the first execution and will update this file with inputed value. If OneView IP change or if you want add more OneViews you can manually update the property. In the same way you can edit theredfish.conffile to tuning other available properties.You can check all properties listed below:redfishsectionindent_json: whether JSON objects on answers are indented or notxml_prettify: whether XML objects on answers are indented or notredfish_host: the IP address where redfish service will listen to. Usinghost = 0.0.0.0means it will listen to all IP addresses.redfish_port: the TCP port where redfish service will listen toauthentication_mode: can beconforsession.conf: credentials from the conf file will be used for the requests. The toolkit will handle authentication with OneView internally. This configuration is the only mode that supportsEvent Serviceand it's recommended for demo purposes only.session: the Redfish client must create a session and use the generatedx-auth-tokenfor the requests. For more details please check Session Management section.redfish-compositionsectionPowerOffServerOnCompose: enable or disable power off the server on composition. The default value used isForceOff- an immediate (hard) shutdown. If not specified (blank value) no power off action will be performed.PowerOffServerOnDecompose: enable or disable power off the server on decomposing a system. The default value used isForceOff- an immediate (hard) shutdown. If not specified (blank value) no power off action will be performed. Other option can beGracefulShutdown- a normal (soft) power off.oneview_configsectionip: HPE OneView's IP/FQDN address or comma separated list of OneView's IP/FQDN address for multiple instances.Oneview Redfish Toolkit now also includes support for multiple OneView instances, allowing a single instance of the service manage more than one OneView instance instead of instantiating a new service for each HPE OneView that is part of the solution. It simplifies for the Redfish client that does not need to handle multiple connections to the Redfish services.credentialssectionusername: HPE OneView's usernamepassword: HPE OneView's passwordauthLoginDomain: HPE OneView's authentication login domain. If not set, defaults to "Local".Note: HPE OneView credentials are used only for authentication_mode set to "conf". They are stored in clear-text. Make sure only authorized users can access this file. When handling multiple OneView instances, make sure all instances have this username/password enabled.event_servicesectionDeliveryRetryAttempts: The value of this property shall be the number of retrys attempted for any given event to the subscription destination before the subscription is terminated.DeliveryRetryIntervalSeconds: The value of this property shall be the interval in seconds between the retry attempts for any given event to the subscription destination.sslsectionSSLType: select one of the options below. The default value used isadhoc.disabled: no SSL. Flask will be used as the web server.adhoc: SSL is enabled with self-signed keys generated by the server every time you start the server. Flask will be used as the web server.self-signed: SSL is enabled with a self-signed cert generated in the certs directory if no files named self-signed.crt and self-signed.key exists in that directory. This will create the certificates on the first run and every time you delete the files and restart the server. The directorycerts mustexist in the system root directory) certs (SSL is enabled with keys provided by user in the fields below). Cherrypy will be used as the web server unless the toolkit is initialized in development and debug mode (arguments set "--dev" and "--debug"). In this case, Flask will be used as the web server.SSLCertFile: The user SSL cert file.SSLKeyFile: The user SSL key file. Should not have a password.ssl-cert-defaultssection: Defines the values used in the self-signed generated certificatecountryName: The name of the country.Required!stateOrProvinceName: The name of the state or province.Required!localityName: Name of the locality (city for example).Required!organizationName: Name of the organization (company name for example).Required!organizationalUnitName: Name of the organizational unit (department for example).Required!commonName: FQDN of the server or it's IP address. If not provided will detect de default route IP and use it.Optional.emailAddress: Email address to contact the responsible for this server/certificate. This is an optional information. Will not be added to certificate if not informed.Optional.cherrypy_configsection: See advanced CherryPy configurationhereLoggingLogging configuration can be found inlogging.conffile. The provided configuration enables INFO level at both console and file output, which will generate aredfish.log,redfish_performance.logandredfish_ov_data.logfiles at$HOME/.config/oneview-redfish-toolkit/.The application has two extended logs, where all logs will be created on the same directory$HOME/.config/oneview-redfish-toolkit/:Performance loggerFor each Redfish Toolkit API request the performance logger will log the elapsed time for each OneView SDK request triggered, the amount elapsed time for all OneView SDK requests, the overhead toolkit process elapsed time and the total elapsed time for the Redfish Toolkit API request. So we can monitoring the OneView performance and the redfish toolkit performance as well. It will be log onredfish_performance.logfile once enabled onlogging.confby changing its level and the root log level as DEBUG. Log example:2018-10-10 15:42:41,112 - perf - DEBUG   - Thread 139974930331392 - OneView request: server_profile_templates.get: 0.02929878234
2018-10-10 15:42:42,304 - perf - DEBUG   - Thread 139974930331392 - OneView request: server_hardware.get_all: 0.03278422355
2018-10-10 15:42:43,231 - perf - DEBUG   - Thread 139974930331392 - OneView request: server_hardware.get_all:  0.03367638587
2018-10-10 15:42:43,291 - perf - DEBUG   - Thread 139974930331392 - OneView process: 0.09575939176
2018-10-10 15:42:43,291 - perf - DEBUG   - Thread 139974930331392 - Redfish process: 0.01273488998413086
2018-10-10 15:42:43,294 - perf - DEBUG   - Thread 139974930331392 - Total process: 0.10849428174OneView Data loggerThe OneView data logger will log the result for each OneView SDK request triggered. So we can check OneView data retrieved for each OneView SDK request. It will be log onredfish_ov_data.logfile once enabled onlogging.confby changing its level and the root log level to DEBUG. Log example:2018-10-10 15:42:43,230 - ovData - DEBUG - Thread 139974930331392 - Request to Oneview 'oneview.net', calling 'server_hardware.get_all' with args () and kwargs {}. Result: []Enabling loggersYou can enable loggersPerformance,OneView Dataand others by setting its level and root logger level as DEBUG on thelogging.conffile. For example:[logger_root]
level=DEBUG

[logger_performance]
propagate=0
level=DEBUG
...You can customize extended logs to have default entry logs as well. To do this add the extended loggers handlers to the root logger:[logger_root]
level=DEBUG
handlers=consoleHandler,defaultFileHandler,performanceFileHandler,oneviewDataFileHandlerDevelopment EnvironmentIn order to run tests and documentation generationtoxis also needed. General instructions on how to install are availablehere.We recommend to run inside a virtual environment. You can create one running:$virtualenvenv_name_you_choose-ppython3.5# to create a Python3.5 environment, for example$sourceenv_name_you_choose/bin/activate# load the environmentOnce the environment is loaded, download and uncompress the latest version fromreleases page, or clone current development version running:$gitclonehttps://github.com/HewlettPackard/oneview-redfish-toolkit.gitThen, proceed with:$cdoneview-redfish-toolkit# enter the service folder# edit redfish.conf$pipinstall-rrequirements.txt# to install all requirements into the virtual environment$./run.sh# to launch the serviceSDK DocumentationThe latest version of the SDK documentation can be found in theSDK Documentation section.Note: This documentation has been manually updated following the steps foundhere.Session ManagementAs specified in the Redfish spec, the endpoints/redfishand/redfish/v1can be accessed unauthenticated, also POST to Sessions Collection (that's how a Redfish session can be established).To create a Redfish session, the redfish client must authenticate himself using his own username and password sending a post request to/redfish/v1/SessionService/Sessions. Since current toolkit implementation delegates the session management to OneView, the Redfish client must pass a valid OneView user and password:curl-i-XPOST\-H"Content-Type:application/json"\https://<ip>:5000/redfish/v1/SessionService/Sessions\-d'{"UserName": "administrator", "Password": "password"}'One of the headers in the response isX-Auth-Tokenthat should be send for all subsequent requests:curl-XGET\-H"X-Auth-Token: NzQ8ODI6MTcxOTkxRdvdtE-HaNeFgkoylkaQVA3l1uIsHxQ7"\https://<ip>:5000/redfish/v1/SystemsWhen handling multiple OneView instances, make sure all instances have this username/password enabled.Event Service notesCurrent implementation follows Redfish specificationDSP0266 version 1.5.0. Event Service works only when authentication_mode is set toconfand does not support multiple OneView instances, hence it's not production ready. As it connects directly to HPE OneView SCMB, the toolkit will request OneView to generate SCMB certs and download the certs to the correct location. The certs file are:oneview_ca: OneView's CA cert file located at:certs/oneview_ca.pem.scmb_cert: OneView's SCMB Client cert file located at:certs/oneview_scmb.pem.scmb_key: OneView's SCMB Client key file located at:certs/oneview_scmb.keyIn order to integrate properly with OneView, the OneView API 300 is required to be supported by OneView instance.Only alerts and events related to enclosures, racks and server hardware are being monitored and will generate the following Redfish events: ResourceAdded, ResourceUpdated and ResourceRemoved.Composition ServiceCurrent implementation follows Redfish specificationDSP2050 version 1.0.0and does not use any OEM (vendor specific) attributes. One of the biggest challenges of adding composability support was to identify what type of Resource Blocks that should be available since full composability is not available due to limitations in the current specification. A first approach leveraging OneView server profile templates was proposed and evaluated with Redfish authors. With this proposal each OneView server profile template maps to Redfish Resource Zones that may list three types of resource blocks:Storage Resource Block: each SAS drive from drive enclosures is mapped for a specific Resource Zone if the SAS storage controller is present in the server profile template. This block presents information about CapacityBytes, Protocol, and MediaType. Other storage types such as DAS and SAN disk are out of scope.Network Resource Block: all connections (network and network sets) specified in the server profile template are mapped to Ethernet interfaces that are part of a Network Resource Block. This block presents information about network name, speedMbps, and VLANs.Computer System Resource Block: each server that matches the server hardware type in the server profile template (Resource Zone) is mapped as a Computer System Resource Block. This block presents information about Processor (Model, MaxSpeedMHz, TotalCores) and Memory. The OneView Redfish service is responsible for making sure to list only Computer System Resource Blocks and Storage Resource Blocks that can be composed (located in the same Enclosure) for a specific Resource Zone. This is a different model than OneView, so extra validation was implemented rather than relying on the OneView server profile API directly.On a Compose request, the Redfish client must select one Computer System Resource Block, one Network Resource Block, and as many Storage Resource Blocks as desired from the available Resource Blocks on the selected Resource Zone. The required attributes in the compose request are specified in the Capabilities Object. A server profile will be created leveraging the server profile template as identified in the POST request. Each Storage Resource Block (SAS drive) will be configured as external logical JBOD (logical drives are out of scope).Important: To have the Composition Service functional, the administrator must create OneView server profile templates in advance. To allow Storage Resource Blocks in composition requests via the OneView Redfish service, the SAS storage controller should be configured, however, no drives should be added in the template (they will be assigned to the profile on the composition request).ContributingYou know the drill. Fork it, branch it, change it, commit it, and pull-request it. We are passionate about improving this project, and are glad to accept help to make it better. However, keep the following in mind:We reserve the right to reject changes that we feel do not fit the scope of this project. For feature additions, please open an issue to discuss your ideas before doing the work.Feature RequestsIf you have a need not being met by the current implementation, please let us know (via a new issue). This feedback is crucial for us to deliver a useful product. Do not assume that we have already thought of everything, because we assure you that is not the case.TestingWe have already packaged everything you need to do to verify if the code is passing the tests. The tox script wraps the unit tests execution against Python 3, flake8 validation, and the test coverage report generation.Run the following command:$ toxLicenseThis project is licensed under the Apache License 2.0.