Copyright 2016-2024 DMTF. All rights reserved.
# Redfish Service Validator
## About
The Redfish Service Validator is a Python3 tool for checking conformance of any "device" with a Redfish interface against Redfish CSDL schema.
The tool is designed to be device-agnostic and is driven based on the Redfish specifications and schema intended to be supported by the device.
## Installation
From PyPI:
pip install redfish_service_validator
From GitHub:
git clone https://github.com/DMTF/Redfish-Service-Validator.git
cd Redfish-Service-Validator
python setup.py sdist
pip install dist/redfish_service_validator-x.x.x.tar.gz
## Requirements
External modules:
* beautifulsoup4 - https://pypi.python.org/pypi/beautifulsoup4
* requests - https://github.com/kennethreitz/requests (Documentation is available at http://docs.python-requests.org/)
* lxml - https://pypi.python.org/pypi/lxml
You may install the prerequisites by running:
pip3 install -r requirements.txt
If you have a previous beautifulsoup4 installation, use the following command:
pip3 install beautifulsoup4 --upgrade
There is no dependency based on Windows or Linux OS.
The result logs are generated in HTML format and an appropriate browser, such as Chrome, Firefox, or Edge, is required to view the logs on the client system.
## Usage
Example usage without providing a configuration file:
rf_service_validator -u root -p root -r https://192.168.1.1
Example usage with a configuration file:
rf_service_validator -c config/example.ini
The following sections describe the arguments and configuration file options.
The file `config/example.ini` can be used as a template configuration file.
At a minimum, the `ip`, `username`, and `password` options must be modified.
### [Tool]
| Variable | CLI Argument | Type | Definition |
| :--- | :--- | :--- | :--- |
| `verbose` | `-v` | integer | Verbosity of tool in stdout; 0 to 3, 3 being the greatest level of verbosity. |
### [Host]
| Variable | CLI Argument | Type | Definition |
| :--- | :--- | :--- | :--- |
| `ip` | `-r` | string | The address of the Redfish service (with scheme); example: 'https://123.45.6.7:8000'. |
| `username` | `-u` | string | The username for authentication. |
| `password` | `-p` | string | The password for authentication. |
| `description` | `--description` | string | The description of the system for identifying logs; if none is given, a value is produced from information in the service root. |
| `forceauth` | `--forceauth` | boolean | Force authentication on unsecure connections; 'True' or 'False'. |
| `authtype` | `--authtype` | string | Authorization type; 'None', 'Basic', 'Session', or 'Token'. |
| `token` | `--token` | string | Token when 'authtype' is 'Token'. |
| `ext_http_proxy` | `--ext_http_proxy` | string | URL of the HTTP proxy for accessing external sites. |
| `ext_https_proxy` | `--ext_https_proxy` | string | URL of the HTTPS proxy for accessing external sites. |
| `serv_http_proxy` | `--serv_http_proxy` | string | URL of the HTTP proxy for accessing the service. |
| `serv_https_proxy` | `--serv_https_proxy` | string | URL of the HTTPS proxy for accessing the service. |
### [Validator]
| Variable | CLI Argument | Type | Definition |
| :--- | :--- |:--------| :--- |
| `payload` | `--payload` | string | The mode to validate payloads ('Tree', 'Single', 'SingleFile', or 'TreeFile') followed by resource/filepath; see below. |
| `logdir` | `--logdir` | string | The directory for generated report files; default: 'logs'. |
| `oemcheck` | `--nooemcheck` | boolean | Whether to check OEM items on service; 'True' or 'False'. |
| `uricheck` | `--uricheck` | boolean | Allow URI checking on services below RedfishVersion 1.6.0; 'True' or 'False'. |
| `debugging` | `--debugging` | boolean | Output debug statements to text log, otherwise it only uses INFO; 'True' or 'False'. |
| `schema_directory` | `--schema_directory` | string | Directory for local schema files. |
| `mockup` | `--mockup` | string | Directory tree for local mockup files. This option enables insertion of local mockup resources to replace missing, incomplete, or incorrect implementations retrieved from the service that may hinder full validation coverage. |
| `collectionlimit` | `--collectionlimit` | string | Sets a limit to links gathered from collections by type (schema name).<br/>Example 1: `ComputerSystem 20` limits ComputerSystemCollection to 20 links.<br/>Example 2: `ComputerSystem 20 LogEntry 10` limits ComputerSystemCollection to 20 links and LogEntryCollection to 10 links. |
| `requesttimeout` | `--requesttimeout` | integer | Timeout in seconds for HTTP request waiting for response. |
| `requestattempts` | `--requestattempts` | integer | Number of attempts after failed HTTP requests. |
### Payload Option
The `payload` option takes two parameters as strings.
The first parameter specifies how to test the payload URI given, which can be 'Single', 'SingleFile', 'Tree', or 'TreeFile'.
'Single' and 'SingleFile' will test and give a report on a single resource.
'Tree' and 'TreeFile' will test and give a report on the resource and every link from that resource.
The second parameter specifies a URI of the target payload to test or a filename of a local file to test.
For example, `--payload Single /redfish/v1/AccountService` will perform validation of the URI `/redfish/v1/AccountService` and no other resources.
### Mockup Option
The `mockup` option takes a single parameter as a string. The parameter specifies a local directory path to the `ServiceRoot` resource of a Redfish mockup tree.
This option provides a powerful debugging tool as is allows local "mockup" JSON payloads to replace those retreived from the unit under test. This can aid testers by allowing the tool to skip over problematic resources, which may cause the tool to crash, or more likely, miss portions of the implemented resources due to missing or invalid link properties or values.
The mockup files follow the Redfish mockup style, with the directory tree matching the URI segments under /redfish/v1, and with a single `index.json` file in each subdirectory as desired. For examples of full mockups, see the Redfish Mockup Bundle (DSP2043) at https://www.dmtf.org/sites/default/files/standards/documents/DSP2043_2024.1.zip.
Populate the mockup directory tree with `index.json` files wherever problematic resources need to be replaced. Any replaced resource will report a Warning in the report to indicate a workaround was used.
## Execution Flow
1. The Redfish Service Validator starts by querying the service root resource from the target service and collections information about the service.
* Collects all CSDL from the service.
2. For each resource found, it performs the following:
* Reads all the URIs referenced in the resource.
* Reads the schema file related to the particular resource and builds a model of expected properties.
* Tests each property in the resource against the model built from the schema.
3. Step 2 repeats until all resources are covered.
When validating a resource, the following types of tests may occur for each property:
* Verify `@odata` properties against known patterns, such as `@odata.id`.
* Check if the property is defined in the resource's schema.
* Check if the value of the property matches the expected type, such as integer, string, boolean, array, or object.
* Check if the property is mandatory.
* Check if the property is allowed to be `null`.
* For string properties with a regular expression, check if the value passes the regular expression.
* For enumerations, check if the value is within the enumeration list.
* For numeric properties with defined ranges, check if the value is within the specified range.
* For object properties, check the properties inside the object againt the object's schema definition.
* For links, check that the URI referenced matches the expected resource type.
CSDL syntax errors will cause testing to halt and move on to other resources.
The OData CSDL Validator (https://github.com/DMTF/Redfish-Tools/tree/main/odata-csdl-validator) can be used to identify schema errors prior to testing.
## Conformance Logs - Summary and Detailed Conformance Report
The Redfish Service Validator generates an HTML report under the 'logs' folder and is named as 'ConformanceHtmlLog_MM_DD_YYYY_HHMMSS.html', along with a text and config file.
The report gives the detailed view of the individual properties checked, with pass, fail, skip, or warning status for each resource checked for conformance.
Additionally, there is a verbose text log file that may be referenced to diagnose tool or schema problems when the HTML log is insufficient.
## The Test Status
The test result for each GET operation will be reported as follows:
* PASS: If the operation is successful and returns a success code, such as `200 OK`.
* FAIL: If the operation failed for reasons mentioned in GET method execution, or some configuration.
* SKIP: If the property or method being checked is not mandatory is not supported by the service.
## Limitations
The Redfish Service Validator only performs GET operations on the service.
Below are certain items that are not in scope for the tool.
* Other HTTP methods, such as PATCH, are not covered.
* Query parameters, such as $top and $skip, are not covered.
* Multiple services are not tested simultaneously.
## Building a Standalone Windows Executable
The module pyinstaller is used to package the environment as a standlone executable file; this can be installed with the following command:
pip3 install pyinstaller
From a Windows system, the following command can be used to build a Windows executable file named `RedfishServiceValidator.exe`, which will be found in dist folder:
pyinstaller -F -w -i redfish.ico -n RedfishServiceValidator.exe RedfishServiceValidatorGui.py
## Release Process
1. Go to the "Actions" page
2. Select the "Release and Publish" workflow
3. Click "Run workflow"
4. Fill out the form
5. Click "Run workflow"
Raw data
{
"_id": null,
"home_page": "https://github.com/DMTF/Redfish-Protocol-Validator",
"name": "redfish-service-validator",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "Redfish",
"author": "DMTF, https://www.dmtf.org/standards/feedback",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/47/27/f3c89398fc3e2c53f7d9a052af538b2deb92012d0715642d9a7baeb9cf97/redfish_service_validator-2.4.9.tar.gz",
"platform": null,
"description": "Copyright 2016-2024 DMTF. All rights reserved.\n\n# Redfish Service Validator\n\n## About\n\nThe Redfish Service Validator is a Python3 tool for checking conformance of any \"device\" with a Redfish interface against Redfish CSDL schema.\nThe tool is designed to be device-agnostic and is driven based on the Redfish specifications and schema intended to be supported by the device.\n\n## Installation\n\n\nFrom PyPI:\n\n pip install redfish_service_validator\n\nFrom GitHub:\n\n git clone https://github.com/DMTF/Redfish-Service-Validator.git\n cd Redfish-Service-Validator\n python setup.py sdist\n pip install dist/redfish_service_validator-x.x.x.tar.gz\n\n## Requirements\n\nExternal modules:\n\n* beautifulsoup4 - https://pypi.python.org/pypi/beautifulsoup4\n* requests - https://github.com/kennethreitz/requests (Documentation is available at http://docs.python-requests.org/)\n* lxml - https://pypi.python.org/pypi/lxml\n\nYou may install the prerequisites by running:\n\n pip3 install -r requirements.txt\n\nIf you have a previous beautifulsoup4 installation, use the following command:\n\n pip3 install beautifulsoup4 --upgrade\n\nThere is no dependency based on Windows or Linux OS.\nThe result logs are generated in HTML format and an appropriate browser, such as Chrome, Firefox, or Edge, is required to view the logs on the client system.\n\n## Usage\n\nExample usage without providing a configuration file:\n\n rf_service_validator -u root -p root -r https://192.168.1.1\n\nExample usage with a configuration file:\n\n rf_service_validator -c config/example.ini\n\nThe following sections describe the arguments and configuration file options.\nThe file `config/example.ini` can be used as a template configuration file.\nAt a minimum, the `ip`, `username`, and `password` options must be modified.\n\n### [Tool]\n\n| Variable | CLI Argument | Type | Definition |\n| :--- | :--- | :--- | :--- |\n| `verbose` | `-v` | integer | Verbosity of tool in stdout; 0 to 3, 3 being the greatest level of verbosity. |\n\n### [Host]\n\n| Variable | CLI Argument | Type | Definition |\n| :--- | :--- | :--- | :--- |\n| `ip` | `-r` | string | The address of the Redfish service (with scheme); example: 'https://123.45.6.7:8000'. |\n| `username` | `-u` | string | The username for authentication. |\n| `password` | `-p` | string | The password for authentication. |\n| `description` | `--description` | string | The description of the system for identifying logs; if none is given, a value is produced from information in the service root. |\n| `forceauth` | `--forceauth` | boolean | Force authentication on unsecure connections; 'True' or 'False'. |\n| `authtype` | `--authtype` | string | Authorization type; 'None', 'Basic', 'Session', or 'Token'. |\n| `token` | `--token` | string | Token when 'authtype' is 'Token'. |\n| `ext_http_proxy` | `--ext_http_proxy` | string | URL of the HTTP proxy for accessing external sites. |\n| `ext_https_proxy` | `--ext_https_proxy` | string | URL of the HTTPS proxy for accessing external sites. |\n| `serv_http_proxy` | `--serv_http_proxy` | string | URL of the HTTP proxy for accessing the service. |\n| `serv_https_proxy` | `--serv_https_proxy` | string | URL of the HTTPS proxy for accessing the service. |\n\n### [Validator]\n\n| Variable | CLI Argument | Type | Definition |\n| :--- | :--- |:--------| :--- |\n| `payload` | `--payload` | string | The mode to validate payloads ('Tree', 'Single', 'SingleFile', or 'TreeFile') followed by resource/filepath; see below. |\n| `logdir` | `--logdir` | string | The directory for generated report files; default: 'logs'. |\n| `oemcheck` | `--nooemcheck` | boolean | Whether to check OEM items on service; 'True' or 'False'. |\n| `uricheck` | `--uricheck` | boolean | Allow URI checking on services below RedfishVersion 1.6.0; 'True' or 'False'. |\n| `debugging` | `--debugging` | boolean | Output debug statements to text log, otherwise it only uses INFO; 'True' or 'False'. |\n| `schema_directory` | `--schema_directory` | string | Directory for local schema files. |\n| `mockup` | `--mockup` | string | Directory tree for local mockup files. This option enables insertion of local mockup resources to replace missing, incomplete, or incorrect implementations retrieved from the service that may hinder full validation coverage. |\n| `collectionlimit` | `--collectionlimit` | string | Sets a limit to links gathered from collections by type (schema name).<br/>Example 1: `ComputerSystem 20` limits ComputerSystemCollection to 20 links.<br/>Example 2: `ComputerSystem 20 LogEntry 10` limits ComputerSystemCollection to 20 links and LogEntryCollection to 10 links. |\n| `requesttimeout` | `--requesttimeout` | integer | Timeout in seconds for HTTP request waiting for response. |\n| `requestattempts` | `--requestattempts` | integer | Number of attempts after failed HTTP requests. |\n\n### Payload Option\n\nThe `payload` option takes two parameters as strings.\n\nThe first parameter specifies how to test the payload URI given, which can be 'Single', 'SingleFile', 'Tree', or 'TreeFile'.\n'Single' and 'SingleFile' will test and give a report on a single resource.\n'Tree' and 'TreeFile' will test and give a report on the resource and every link from that resource.\n\nThe second parameter specifies a URI of the target payload to test or a filename of a local file to test.\n\nFor example, `--payload Single /redfish/v1/AccountService` will perform validation of the URI `/redfish/v1/AccountService` and no other resources.\n\n### Mockup Option\n\nThe `mockup` option takes a single parameter as a string. The parameter specifies a local directory path to the `ServiceRoot` resource of a Redfish mockup tree.\n\nThis option provides a powerful debugging tool as is allows local \"mockup\" JSON payloads to replace those retreived from the unit under test. This can aid testers by allowing the tool to skip over problematic resources, which may cause the tool to crash, or more likely, miss portions of the implemented resources due to missing or invalid link properties or values.\n\nThe mockup files follow the Redfish mockup style, with the directory tree matching the URI segments under /redfish/v1, and with a single `index.json` file in each subdirectory as desired. For examples of full mockups, see the Redfish Mockup Bundle (DSP2043) at https://www.dmtf.org/sites/default/files/standards/documents/DSP2043_2024.1.zip.\n\nPopulate the mockup directory tree with `index.json` files wherever problematic resources need to be replaced. Any replaced resource will report a Warning in the report to indicate a workaround was used.\n\n## Execution Flow\n\n1. The Redfish Service Validator starts by querying the service root resource from the target service and collections information about the service.\n * Collects all CSDL from the service.\n2. For each resource found, it performs the following:\n * Reads all the URIs referenced in the resource.\n * Reads the schema file related to the particular resource and builds a model of expected properties.\n * Tests each property in the resource against the model built from the schema.\n3. Step 2 repeats until all resources are covered.\n\nWhen validating a resource, the following types of tests may occur for each property:\n\n* Verify `@odata` properties against known patterns, such as `@odata.id`.\n* Check if the property is defined in the resource's schema.\n* Check if the value of the property matches the expected type, such as integer, string, boolean, array, or object.\n* Check if the property is mandatory.\n* Check if the property is allowed to be `null`.\n* For string properties with a regular expression, check if the value passes the regular expression.\n* For enumerations, check if the value is within the enumeration list.\n* For numeric properties with defined ranges, check if the value is within the specified range.\n* For object properties, check the properties inside the object againt the object's schema definition.\n* For links, check that the URI referenced matches the expected resource type.\n\nCSDL syntax errors will cause testing to halt and move on to other resources.\nThe OData CSDL Validator (https://github.com/DMTF/Redfish-Tools/tree/main/odata-csdl-validator) can be used to identify schema errors prior to testing.\n\n## Conformance Logs - Summary and Detailed Conformance Report\n\nThe Redfish Service Validator generates an HTML report under the 'logs' folder and is named as 'ConformanceHtmlLog_MM_DD_YYYY_HHMMSS.html', along with a text and config file.\nThe report gives the detailed view of the individual properties checked, with pass, fail, skip, or warning status for each resource checked for conformance.\n\nAdditionally, there is a verbose text log file that may be referenced to diagnose tool or schema problems when the HTML log is insufficient. \n\n## The Test Status\n\nThe test result for each GET operation will be reported as follows:\n\n* PASS: If the operation is successful and returns a success code, such as `200 OK`.\n* FAIL: If the operation failed for reasons mentioned in GET method execution, or some configuration.\n* SKIP: If the property or method being checked is not mandatory is not supported by the service.\n\n## Limitations\n\nThe Redfish Service Validator only performs GET operations on the service.\nBelow are certain items that are not in scope for the tool.\n\n* Other HTTP methods, such as PATCH, are not covered.\n* Query parameters, such as $top and $skip, are not covered.\n* Multiple services are not tested simultaneously.\n\n## Building a Standalone Windows Executable\n\nThe module pyinstaller is used to package the environment as a standlone executable file; this can be installed with the following command:\n\n pip3 install pyinstaller\n\nFrom a Windows system, the following command can be used to build a Windows executable file named `RedfishServiceValidator.exe`, which will be found in dist folder:\n\n pyinstaller -F -w -i redfish.ico -n RedfishServiceValidator.exe RedfishServiceValidatorGui.py\n\n## Release Process\n\n1. Go to the \"Actions\" page\n2. Select the \"Release and Publish\" workflow\n3. Click \"Run workflow\"\n4. Fill out the form\n5. Click \"Run workflow\"\n",
"bugtrack_url": null,
"license": "BSD 3-clause \"New\" or \"Revised License\"",
"summary": "Redfish Service Validator",
"version": "2.4.9",
"project_urls": {
"Homepage": "https://github.com/DMTF/Redfish-Protocol-Validator"
},
"split_keywords": [
"redfish"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "70c2a9c1cb9936f945c05738891ec1f1c6a89b8486e5cf1228b946b53345920b",
"md5": "9fc6fcf72cc5607b874bf441d51c0dad",
"sha256": "e298b3ce0f3807b7e7e832a21fa30bf1823f3b89f71530ee01a3f0837b33dff1"
},
"downloads": -1,
"filename": "redfish_service_validator-2.4.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9fc6fcf72cc5607b874bf441d51c0dad",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 79488,
"upload_time": "2024-09-27T19:31:50",
"upload_time_iso_8601": "2024-09-27T19:31:50.056418Z",
"url": "https://files.pythonhosted.org/packages/70/c2/a9c1cb9936f945c05738891ec1f1c6a89b8486e5cf1228b946b53345920b/redfish_service_validator-2.4.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4727f3c89398fc3e2c53f7d9a052af538b2deb92012d0715642d9a7baeb9cf97",
"md5": "5777b70009016e0da63f24dd44c68101",
"sha256": "443ad7ca82aa4054649e99e18cf6d71f88746265e970604f7279d1a789af4bfa"
},
"downloads": -1,
"filename": "redfish_service_validator-2.4.9.tar.gz",
"has_sig": false,
"md5_digest": "5777b70009016e0da63f24dd44c68101",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 79085,
"upload_time": "2024-09-27T19:31:51",
"upload_time_iso_8601": "2024-09-27T19:31:51.948834Z",
"url": "https://files.pythonhosted.org/packages/47/27/f3c89398fc3e2c53f7d9a052af538b2deb92012d0715642d9a7baeb9cf97/redfish_service_validator-2.4.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-27 19:31:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DMTF",
"github_project": "Redfish-Protocol-Validator",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "aenum",
"specs": []
},
{
"name": "colorama",
"specs": []
},
{
"name": "pyasn1",
"specs": []
},
{
"name": "pyasn1-modules",
"specs": []
},
{
"name": "requests",
"specs": []
},
{
"name": "sseclient-py",
"specs": []
},
{
"name": "urllib3",
"specs": []
}
],
"tox": true,
"lcname": "redfish-service-validator"
}
JSON
