From 592589c3efc9105e4cae969b44df2441e147c8c6 Mon Sep 17 00:00:00 2001 From: "Pola, Sudhir" Date: Tue, 3 Mar 2026 20:22:01 +0530 Subject: [PATCH 1/3] docs: added redfish tutorial for usage with console --- docs/Tutorials/Redfish/redfishUserGuide.md | 803 +++++++++++++++++++++ mkdocs.yml | 6 +- 2 files changed, 807 insertions(+), 2 deletions(-) create mode 100644 docs/Tutorials/Redfish/redfishUserGuide.md diff --git a/docs/Tutorials/Redfish/redfishUserGuide.md b/docs/Tutorials/Redfish/redfishUserGuide.md new file mode 100644 index 00000000..1f4ab380 --- /dev/null +++ b/docs/Tutorials/Redfish/redfishUserGuide.md @@ -0,0 +1,803 @@ +# DMT Console Redfish User Guide + +This tutorial demonstrates how to set up, configure, and test the DMT Console Redfish API implementation. The Redfish API is a REST interface that lets you manage Intel AMT-enabled devices through standardized HTTP endpoints. + +## What You Will Do + +In this tutorial, you will: + +- Download and run the DMT Console Release supporting Redfish end points +- Test Redfish endpoints using curl commands or the DMTF Redfish Tool +- Troubleshoot common issues + +## Supported Redfish Features + +The DMT Console implements the following Redfish API v1.19.0 features for remote power management and fleet management. + +**Service Discovery:** + +- Service Root (`/redfish/v1/`) - Entry point for the Redfish service +- OData Service Document (`/redfish/v1/odata`) - List of available entity sets +- Metadata Document (`/redfish/v1/$metadata`) - OData CSDL schema definition + +**Computer System Management:** + +- **Systems Collection** (`/redfish/v1/Systems`) - List all managed Intel AMT devices +- **System Information** (`/redfish/v1/Systems/{id}`) - Retrieve detailed system properties: +- **Power Control Actions** (`/redfish/v1/Systems/{id}/Actions/ComputerSystem.Reset`) - Remote power management via `ComputerSystem.Reset`: + +**Standards Compliance:** + +- Redfish API v1.19.0 +- OData Version 4.0 +- DMTF ComputerSystem v1.26.0 schema + +## Tutorial Flow + +Follow these sections in order: + +1. **[Prerequisites](#prerequisites)** - Tools installation +2. **[Download the Pre-built Redfish Binary](#download-the-pre-built-redfish-binary)** - Download and prepare the release package +3. **[Configuring and Executing the DMT Console Application](#configuring-and-executing-the-dmt-console-application)** - Configuration settings and server startup +4. **[Using the Redfish API through DMTF Redfish Tool](#using-the-redfish-api-through-dmtf-redfish-tool)** - API testing with the official DMTF Redfish tool +5. **[Using the Redfish API through curl commands](#using-the-redfish-api-through-curl-commands)** - API testing with curl commands +6. **[Troubleshooting](#troubleshooting)** - Common issues and solutions +7. **[Additional Resources](#additional-resources)** - Documentation and reference links + +## Setup Overview + +The following diagram shows how the components connect during this tutorial: + +```mermaid +graph TB + subgraph "Admin Machine" + A[DMT Console
with Redfish Service
Port 8181] + B[curl] + C[Redfish Tool] + + B -.->|API Requests
/redfish/v1/..
/api/v1/..| A + C -.->|API Requests
/redfish/v1/..| A + end + + subgraph "Managed Devices" + D[Intel AMT Device 1] + E[Intel AMT Device 2] + F[Intel AMT Device N] + end + + A -->|API Requests
WS-MAN API| D + A -->|API Requests
WS-MAN API| E + A -->|API Requests
WS-MAN API| F + + style A fill:blue,stroke:black,stroke-width:2px,color:white + style B fill:green,stroke:black,stroke-width:2px,color:white + style C fill:green,stroke:black,stroke-width:2px,color:white + style D fill:blue,stroke:black,stroke-width:2px,color:white + style E fill:blue,stroke:black,stroke-width:2px,color:white + style F fill:blue,stroke:black,stroke-width:2px,color:white +``` + +**Components:** + +- **DMT Console**: Redfish service running on the helpdesk machine +- **curl / Redfish Tool**: Command-line clients for testing and interacting with the Redfish API +- **Intel AMT Devices**: Managed devices with Intel AMT firmware + +## Prerequisites + +Install the following tools before running this tutorial: + +1. **curl** (for API calls) : Comes pre-installed on most of the OS'es, if not available install it from the official website() or your OS package manager. + +2. **DMTF Redfish Tool** (for Redfish CLI testing) : Repository and install guidance: . The version used in this tutorial is 1.1.8 or later. + +## Download and Configure the Pre-built Redfish Binary + +Download the pre-built release package from +Use a release that includes the Redfish functionality you want to test, then extract the archive. + +After downloading and extracting the Redfish binary, continue with the Enterprise setup guide: [Configuration](../../GetStarted/Enterprise/setup.md#configuration) and follow the instructions to run the Console application and Add Devices. Once the console is running, you can proceed to test the Redfish API using either curl commands or the DMTF Redfish Tool as described in the next sections. + +> **Note:** Configure the Console application to run with TLS enabled before testing Redfish endpoints. Redfish access in this guide assumes HTTPS. + +### Verifying the Redfish Endpoint + +Test that the Redfish Endpoint is running: + +> **Note:** On Windows, PowerShell has a built-in `curl` alias for `Invoke-WebRequest`. To use the native curl executable instead, either use `curl.exe` explicitly in commands, or remove the alias by running `Remove-Item Alias:curl` in your PowerShell session. + +```bash +# Check if the server is listening (use -k to ignore self-signed certificate, -s for silent mode) +curl -sk https://:/redfish/v1/ | jq + +# Reference response: +{ + "@odata.context": "/redfish/v1/$metadata#ServiceRoot.ServiceRoot", + "@odata.id": "/redfish/v1", + "@odata.type": "#ServiceRoot.v1_19_0.ServiceRoot", + "Id": "RootService", + "Name": "Root Service", + "Product": "Device Management Toolkit - Redfish Service", + "RedfishVersion": "1.19.0", + "Systems": { + "@odata.id": "/redfish/v1/Systems" + }, + "UUID": "ebc6c6c9-1ed3-4f12-ae0b-7b877c55de07", + "Vendor": "Device Management Toolkit" +} + +# Reference log on the Console +{"level":"info","time":"2025-12-06T15:22:40+05:30","caller":"/home/admin/dmt/console-redfish-nm/pkg/logger/adapters.go:29","message":"[GIN] 2025/12/06 - 15:22:40 | 200 | 795.431µs | 10.190.213.16 | GET \"/redfish/v1/\""} +``` + +> Note: If you receive connection errors or no response check for any proxy settings on your machine that may be interfering with local connections. If you are not using a proxy, ensure that no proxy environment variables are set (e.g., `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`). + +## Using the Redfish API through DMTF Redfish Tool + +The DMTF Redfish Tool is a Python-based command-line utility that provides a more user-friendly interface for interacting with Redfish services compared to raw curl commands. It automatically handles authentication, response formatting, and provides convenient shortcuts for common operations. + +### About DMTF Redfish Tool + +The DMTF Redfish Tool is the official reference implementation tool from the Distributed Management Task Force (DMTF) for interacting with Redfish APIs. It provides: + +- Simplified command syntax for Redfish operations +- Automatic JSON formatting and pretty-printing +- Built-in authentication handling +- Support for HTTP and HTTPS connections +- Comprehensive coverage of Redfish API operations + +**Official Repository:** + +**Note:** If you haven't already installed the Redfish tool, please refer to [Prerequisites](#prerequisites). + +### Basic Usage + +The general syntax for the Redfish tool is: + +```bash +redfishtool [options] [command-options] +``` + +**Common options:** + +- `-r ` or `--rhost `: Specify the Console service host +- `-u ` or `--user `: Console Username for authentication +- `-p ` or `--password `: Console Password for authentication +- `-v` or `--verbose`: Enable verbose output + +### Using Redfish Tool with DMT Console + +The following examples demonstrate how to use the DMTF Redfish tool with DMT Console for all common Redfish operations. These correspond to the same scenarios covered in the curl commands section. + +#### Get Service Root + +**Description:** Retrieve the Redfish service root document. + +**Requires Authentication:** No + +This command displays the service root with available API endpoints and service information. + +```bash +redfishtool -r : -S Always root +``` + +**Reference Successful Response:** + +```json +{ + "@odata.context": "/redfish/v1/$metadata#ServiceRoot.ServiceRoot", + "@odata.id": "/redfish/v1", + "@odata.type": "#ServiceRoot.v1_19_0.ServiceRoot", + "Id": "RootService", + "Name": "Root Service", + "Product": "Device Management Toolkit - Redfish Service", + "RedfishVersion": "1.19.0", + "Systems": { + "@odata.id": "/redfish/v1/Systems" + }, + "UUID": "998ecc0a-b980-4ec4-9738-2a3303daad7d", + "Vendor": "Device Management Toolkit" +} +``` + +**What to verify:** + +- ✓ Response has `@odata.context`, `@odata.id`, `@odata.type` +- ✓ Contains links to Systems collections +- ✓ Header `OData-Version: 4.0` is present +- ✓ `RedfishVersion` is `1.19.0` +- ✓ `Vendor` is `Device Management Toolkit` +- ✓ `UUID` is a valid GUID and would the same on subsequent requests + +#### Get OData Service Document + +**Description:** Retrieve the OData service document that describes available entity sets. + +**Requires Authentication:** No + +```bash +redfishtool -r : -S Always odata +``` + +**Reference Successful Response:** + +```json +{ + "@odata.context": "/redfish/v1/$metadata#ServiceRoot.ServiceRoot", + "value": [ + { + "name": "Systems", + "kind": "Singleton", + "url": "/redfish/v1/Systems" + } + ] +} + +``` + +**What to verify:** + +- ✓ Response contains `value` array +- ✓ Entity sets are listed with `name`, `kind`, and `url` + +#### Get Metadata Document + +**Description:** Retrieve the Redfish metadata document in XML format (OData CSDL schema). + +**Requires Authentication:** No + +```bash +redfishtool -r : -S Always metadata +``` + +**Reference Successful Response:** + +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +**What to verify:** + +- ✓ Content-Type is `application/xml` or `text/xml` +- ✓ Valid XML structure with `` root element +- ✓ Contains schema definitions for Redfish resources + +#### Get Systems Collection + +**Description:** Retrieve the collection of computer systems managed by the console. + +**Requires Authentication:** Yes + +This displays all systems managed by the DMT Console. + +```bash +redfishtool -r : -u -p -S Always Systems +``` + +**Reference Successful Response:** + +```json +{ + "@odata.context": "/redfish/v1/$metadata#ComputerSystemCollection.ComputerSystemCollection", + "@odata.id": "/redfish/v1/Systems", + "@odata.type": "#ComputerSystemCollection.ComputerSystemCollection", + "Description": "Collection of Computer Systems", + "Members": [ + { + "@odata.id": "/redfish/v1/Systems/f141c6d4-7b1b-4435-ae10-53d4f45355ab" + } + ], + "Members@odata.count": 1, + "Name": "Computer System Collection" +} + +``` + +**What to verify:** + +- ✓ Response contains `Members` array +- ✓ `Members@odata.count` matches number of devices +- ✓ Each member has `@odata.id` link + +#### Get Specific System Details + +**Description:** Retrieve detailed information about a specific computer system. + +**Requires Authentication:** Yes + +Replace `` with the actual system identifier (e.g., device GUID). + +```bash +redfishtool -r : -u -p -S Always Systems -I -T 30 +``` + +**Reference Successful Response:** + +```json +{ + "@odata.context": "/redfish/v1/$metadata#ComputerSystem.ComputerSystem", + "@odata.id": "/redfish/v1/Systems/device-guid-12345", + "@odata.type": "#ComputerSystem.v1_0_0.ComputerSystem", + "Actions": { + "#ComputerSystem.Reset": { + "target": "/redfish/v1/Systems/device-guid-12345/Actions/ComputerSystem.Reset" + "title": "Reset" + } + }, + "BiosVersion": "1.2.3", + "HostName": "test-host", + "Id": "device-guid-12345", + "Manufacturer": "Intel Corporation", + "Model": "NUC14RVH-B", + "Name": "device-guid-12345", + "PowerState": "On", + "SerialNumber": "SN1234567890", + "SystemType": "Physical", +} +``` + +**What to verify:** + +- ✓ Response contains system properties ( BiosVersion, Id, Name, PowerState, etc.) +- ✓ `Actions` object contains available operations + +#### Perform Power Actions + +**Description:** Perform power control operations on a computer system. + +**Requires Authentication:** Yes + +**Supported Reset Types:** + +- `On` - Power on the system +- `ForceOff` - Immediate power off (non-graceful) +- `ForceRestart` - Immediate restart (non-graceful) +- `PowerCycle` - Power cycle (off then on) + +**Power On:** + +```bash +redfishtool -r : -u -p -S Always Systems -I reset On +``` + +**Power Off (Force):** + +```bash +redfishtool -r : -u -p -S Always Systems -I reset ForceOff +``` + +**Force Restart:** + +```bash +redfishtool -r : -u -p -S Always Systems -I reset ForceRestart +``` + +**PowerCycle:** + +```bash +redfishtool -r : -u -p -S Always Systems -I reset PowerCycle +``` + +#### Get System Power State + +**Description:** Check the current power state of a specific system. + +**Requires Authentication:** Yes + +```bash +redfishtool -r : -u -p -S Always Systems -T 30 -I | jq .PowerState +``` + +### Advantages Over curl + +The Redfish tool offers several advantages: + +- **Simpler Syntax:** No need to construct full URLs or JSON payloads +- **Automatic Formatting:** JSON responses are automatically formatted +- **Error Handling:** Better error messages and handling +- **Discovery:** Built-in commands for service discovery +- **Consistency:** Uniform interface across all Redfish operations + +### Additional Resources + +For comprehensive documentation and all available commands, refer to the DMTF Redfish Tool Repository: + +--- + +## Using the Redfish API through curl commands + +### Authentication + +Most Redfish endpoints require Basic Authentication. Use the credentials as provided during the console execution: + +=== "Windows" + ``` + # Using curl with Basic Auth + curl.exe -sk -u : https://:/redfish/v1/Systems + ``` +=== "Linux" + ``` bash + # Using curl with Basic Auth + curl -sk -u : https://:/redfish/v1/Systems + ``` + +**Public endpoints (no authentication required):** + +- `/redfish/v1/` - Service root +- `/redfish/v1/odata` - OData service document +- `/redfish/v1/$metadata` - Metadata document + +### Testing Redfish Endpoints + +The following table provides curl commands for common Redfish API operations. For detailed response examples and verification steps, refer to the corresponding sections in [Using Redfish Tool with DMT Console](#using-redfish-tool-with-dmt-console). + +**Note for Windows users:** Use `curl.exe` instead of `curl` to ensure the native curl executable is used, as PowerShell has a `curl` alias for `Invoke-WebRequest`. + +| Scenario | Curl Command | Reference | +|----------|--------------|-----------| +| **Get Service Root**
Retrieve the Redfish service root document | `curl -sk https://:/redfish/v1/ \| jq` | See [Get Service Root](#get-service-root) for response format and verification steps | +| **Get OData Service Document**
Retrieve the OData service document | `curl -sk https://:/redfish/v1/odata \| jq` | See [Get OData Service Document](#get-odata-service-document) for response format and verification steps | +| **Get Metadata Document**
Retrieve the Redfish metadata document in XML format | `curl -sk https://:/redfish/v1/\$metadata` | See [Get Metadata Document](#get-metadata-document) for response format and verification steps | +| **Get Systems Collection**
Retrieve all computer systems
*Requires Authentication* | `curl -sk -u : https://:/redfish/v1/Systems \| jq` | See [Get Systems Collection](#get-systems-collection) for response format and verification steps | +| **Get Specific System Details**
Retrieve detailed information about a specific system
*Requires Authentication* | `curl -sk -u : https://:/redfish/v1/Systems/ \| jq` | See [Get Specific System Details](#get-specific-system-details) for response format and verification steps | +| **Power On**
Power on a system
*Requires Authentication* | `curl -sk -X POST -u : -H "Content-Type: application/json" -d '{"ResetType": "On"}' https://:/redfish/v1/Systems//Actions/ComputerSystem.Reset` | See [Perform Power Actions](#perform-power-actions) for details on all power operations | +| **Force Off**
Immediate power off (non-graceful)
*Requires Authentication* | `curl -sk -X POST -u : -H "Content-Type: application/json" -d '{"ResetType": "ForceOff"}' https://:/redfish/v1/Systems//Actions/ComputerSystem.Reset` | See [Perform Power Actions](#perform-power-actions) for details on all power operations | +| **Force Restart**
Immediate restart (non-graceful)
*Requires Authentication* | `curl -sk -X POST -u : -H "Content-Type: application/json" -d '{"ResetType": "ForceRestart"}' https://:/redfish/v1/Systems//Actions/ComputerSystem.Reset` | See [Perform Power Actions](#perform-power-actions) for details on all power operations | +| **Power Cycle**
Power cycle (off then on)
*Requires Authentication* | `curl -sk -X POST -u : -H "Content-Type: application/json" -d '{"ResetType": "PowerCycle"}' https://:/redfish/v1/Systems//Actions/ComputerSystem.Reset` | See [Perform Power Actions](#perform-power-actions) for details on all power operations | +| **Get System Power State**
Check current power state
*Requires Authentication* | `curl -sk -u : https://:/redfish/v1/Systems/ \| jq .PowerState` | See [Get System Power State](#get-system-power-state) for details | + + +--- + +## Common Use Cases + +### Use Case 1: Check Power State of All Systems + +=== "Windows" + ``` + # Get all systems + $SYSTEMS = curl.exe -s -k -u admin:password123 https://localhost:8181/redfish/v1/Systems | jq -r '.Members[]."@odata.id"' + + # Loop through each system + foreach ($system in $SYSTEMS) { + Write-Host "System: $system" + curl.exe -s -k -u admin:password123 "https://localhost:8181$system" | jq '.PowerState' + Write-Host "---" + } + ``` +=== "Linux" + ``` bash + # Get all systems + SYSTEMS=$(curl -sk -u admin:password123 https://localhost:8181/redfish/v1/Systems | jq -r '.Members[]."@odata.id"') + + # Loop through each system + for system in $SYSTEMS; do + echo "System: $system" + curl -sk -u admin:password123 "https://localhost:8181$system" | jq '.PowerState' + echo "---" + done + ``` + +### Use Case 2: Power On All Systems + +=== "Windows" + ``` + # Get all systems + $SYSTEMS = curl.exe -s -k -u admin:password123 https://localhost:8181/redfish/v1/Systems | jq -r '.Members[]."@odata.id"' + + # Power on each system + foreach ($system in $SYSTEMS) { + Write-Host "Powering on: $system" + curl.exe -s -k -X POST ` + -u admin:password123 ` + -H "Content-Type: application/json" ` + -d '{"ResetType": "On"}' ` + "https://localhost:8181${system}/Actions/ComputerSystem.Reset" + Write-Host "" + } + ``` +=== "Linux" + ``` bash + # Get all systems + SYSTEMS=$(curl -sk -u admin:password123 https://localhost:8181/redfish/v1/Systems | jq -r '.Members[]."@odata.id"') + + # Power on each system + for system in $SYSTEMS; do + echo "Powering on: $system" + curl -sk -X POST \ + -u admin:password123 \ + -H "Content-Type: application/json" \ + -d '{"ResetType": "On"}' \ + "https://localhost:8181${system}/Actions/ComputerSystem.Reset" + echo "" + done + ``` + +### Use Case 3: Get System Inventory + +=== "Windows" + ``` + # Get detailed system information + $SYSTEM_ID = "device-guid-12345" + + curl.exe -s -k -u admin:password123 ` + "https://localhost:8181/redfish/v1/Systems/$SYSTEM_ID" | jq + ``` +=== "Linux" + ``` bash + # Get detailed system information + SYSTEM_ID="device-guid-12345" + + curl -sk -u admin:password123 \ + https://localhost:8181/redfish/v1/Systems/$SYSTEM_ID | jq + ``` + +### Use Case 4: Graceful Shutdown All Systems + +=== "Windows" + ``` + # Get all systems + $SYSTEMS = curl.exe -s -k -u admin:password123 https://localhost:8181/redfish/v1/Systems | jq -r '.Members[]."@odata.id"' + + # Gracefully shutdown each system + foreach ($system in $SYSTEMS) { + Write-Host "Shutting down: $system" + curl.exe -s -k -X POST ` + -u admin:password123 ` + -H "Content-Type: application/json" ` + -d '{"ResetType": "GracefulShutdown"}' ` + "https://localhost:8181${system}/Actions/ComputerSystem.Reset" + Write-Host "" + } + ``` +=== "Linux" + ``` bash + # Get all systems + SYSTEMS=$(curl -sk -u admin:password123 https://localhost:8181/redfish/v1/Systems | jq -r '.Members[]."@odata.id"') + + # Gracefully shutdown each system + for system in $SYSTEMS; do + echo "Shutting down: $system" + curl -sk -X POST \ + -u admin:password123 \ + -H "Content-Type: application/json" \ + -d '{"ResetType": "GracefulShutdown"}' \ + "https://localhost:8181${system}/Actions/ComputerSystem.Reset" + echo "" + done + ``` + +--- + +## Error Handling + +### Common HTTP Status Codes + +| Status Code | Meaning | Example Scenario | +|-------------|---------|------------------| +| 200 OK | Successful GET request | Getting service root, systems collection | +| 202 Accepted | Action accepted for processing | Power action initiated | +| 400 Bad Request | Invalid request body or parameters | Invalid ResetType value | +| 401 Unauthorized | Missing or invalid credentials | No authentication provided | +| 404 Not Found | Resource does not exist | Invalid system ID | +| 405 Method Not Allowed | HTTP method not supported | GET on action endpoint | +| 500 Internal Server Error | Server-side error | Backend service failure | + +### Error Response Format + +All errors follow the Redfish standard error format: + +```json +{ + "error": { + "code": "Base.1.8.GeneralError", + "message": "A general error has occurred", + "@Message.ExtendedInfo": [ + { + "MessageId": "Base.1.8.PropertyValueNotInList", + "Message": "The value 'InvalidType' for the property ResetType is not in the list of acceptable values", + "Severity": "Warning", + "Resolution": "Choose a value from the enumeration list and resubmit the request" + } + ] + } +} + +``` + +### Example: Invalid Reset Type + +```bash +curl -sk -X POST \ + -u admin:password123 \ + -H "Content-Type: application/json" \ + -d '{"ResetType": "InvalidType"}' \ + + http://localhost:8181/redfish/v1/Systems/device-guid-12345/Actions/ComputerSystem.Reset + +``` + +**Response:** + +```json +{ + "error": { + "code": "Base.1.8.PropertyValueNotInList", + "message": "Invalid ResetType value", + "@Message.ExtendedInfo": [ + { + "MessageId": "Base.1.8.PropertyValueNotInList", + "Message": "The value 'InvalidType' for the property ResetType is not in the list of acceptable values", + "Severity": "Warning", + "Resolution": "Use one of: On, ForceOff, ForceRestart, GracefulShutdown, PowerCycle, GracefulRestart" + } + ] + } +} + +``` + +--- + +## Troubleshooting + +### Common Issues + +#### Issue 1: Connection Refused + +**Symptom:** + +```bash +curl: (7) Failed to connect to localhost port 8181: Connection refused +``` + +**Solution:** + +- Verify server is running: `ps aux | grep console` +- Check if port is correct: `netstat -tlnp | grep 8181` +- Review server logs: `cat logs/console.log` +- Restart the application + + +#### Issue 2: Authentication Failed + +**Symptom:** + +```json +{ + "error": { + "code": "Base.1.8.Unauthorized", + "message": "Authentication failed" + } +} + +``` + +**Solution:** + +- Verify credentials in `config.yml` +- Ensure Basic Auth header is correct: `echo -n "admin:password123" | base64` +- Check if authentication is enabled in config +- Try with correct credentials: `curl -u admin:password123 ...` + + +#### Issue 3: Device Not Found + +**Symptom:** + +```json +{ + "error": { + "code": "Base.1.8.ResourceNotFound", + "message": "System not found" + } +} + +``` + +**Solution:** + +- List all systems: `curl -u admin:password123 http://localhost:8181/redfish/v1/Systems` +- Verify device GUID is correct +- Check if device is added to Console +- Verify device is online and reachable + + +#### Issue 4: Power Action Fails + +**Symptom:** + +```json +{ + "error": { + "code": "Base.1.8.GeneralError", + "message": "Failed to execute power action" + } +} + +``` + +**Solution:** + +- Check device connectivity +- Verify AMT credentials are correct +- Review backend service logs +- Ensure device supports the requested power action +- Check if device is in a valid state for the action + +### Port Conflicts + +If port is already in use: + +=== "Windows" + ```powershell + # Find process using port 8181 + Get-NetTCPConnection -LocalPort 8181 | Select-Object -Property OwningProcess + + # Kill the process (replace PID with actual process ID) + Stop-Process -Id -Force + + # Or use netstat to find the process + netstat -ano | findstr :8181 + taskkill /PID /F + + # Or use a different port + $env:HTTP_PORT=9090 + .\console.exe + ``` + +=== "Linux" + ```bash + # Find process using port ex:8181 + lsof -ti:8181 + + # Kill the process + lsof -ti:8181 | xargs -r kill -9 + + # Or use a different port + HTTP_PORT=9090 ./console + ``` + +--- + +## Additional Documentation Resources + +- [DMT Console Supported Redfish Open API Specification](https://github.com/device-management-toolkit/console/blob/redfish/redfish/openapi/redfish-openapi.yaml) +- [DMTF Redfish Specification](https://www.dmtf.org/standards/redfish) +- [OData Version 4.0 Specification](http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part1-protocol.html) + +**For questions or support, please refer to the project documentation or contact the development team.** diff --git a/mkdocs.yml b/mkdocs.yml index d2c89817..f318a485 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -56,7 +56,7 @@ nav: - License: license.md - Get Help: - FAQ: Reference/faq.md - - Glossary: Glossary.md + - Glossary: Glossary.md - Troubleshooting: Reference/troubleshooting.md - Get Started: - Overview: GetStarted/overview.md @@ -106,7 +106,7 @@ nav: - Wireless Activation: Tutorials/createWiFiConfig.md - Modify User Authentication: Tutorials/modifyUserAuth.md - One Click Recovery (OCR): Tutorials/ocrTutorial.md - - Localization: + - Localization: - Console: Tutorials/Localization/consoleLocalization.md - Sample Web UI: Tutorials/Localization/webuiLocalization.md - Scaling Tutorials: @@ -117,6 +117,8 @@ nav: - AKS: Tutorials/Scaling/Kubernetes/deployingk8s-aks.md - EKS: Tutorials/Scaling/Kubernetes/deployingk8s-eks.md - KUMA Service Mesh: Tutorials/Scaling/Kubernetes/service-mesh.md + - Redfish: + - Redfish User Guide: Tutorials/Redfish/redfishUserGuide.md - Reference: - Architecture Overview: Reference/architectureOverview.md - AMT Power States: Reference/powerstates.md From c31a1657522ed9e48dc8e85a35e6d4fafe49cf0d Mon Sep 17 00:00:00 2001 From: Natalie Gaston Date: Tue, 3 Mar 2026 18:46:39 -0800 Subject: [PATCH 2/3] docs(redfish): add Reset to BIOS section and fix table entry --- docs/Tutorials/Redfish/redfishUserGuide.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/Tutorials/Redfish/redfishUserGuide.md b/docs/Tutorials/Redfish/redfishUserGuide.md index 1f4ab380..170f8848 100644 --- a/docs/Tutorials/Redfish/redfishUserGuide.md +++ b/docs/Tutorials/Redfish/redfishUserGuide.md @@ -412,6 +412,16 @@ redfishtool -r : -u -p : -u -p -S Always Systems -I reset PowerCycle ``` +#### Reset to BIOS + +**Description:** Set the system to boot into BIOS setup on the next restart. The override applies once and reverts to normal boot order afterwards. After sending this command, issue a restart (e.g., `ForceRestart`) to trigger the BIOS boot. + +**Requires Authentication:** Yes + +```bash +redfishtool -r : -u -p -S Always Systems -I setBootOverride Once BiosSetup +``` + #### Get System Power State **Description:** Check the current power state of a specific system. @@ -478,6 +488,7 @@ The following table provides curl commands for common Redfish API operations. Fo | **Force Off**
Immediate power off (non-graceful)
*Requires Authentication* | `curl -sk -X POST -u : -H "Content-Type: application/json" -d '{"ResetType": "ForceOff"}' https://:/redfish/v1/Systems//Actions/ComputerSystem.Reset` | See [Perform Power Actions](#perform-power-actions) for details on all power operations | | **Force Restart**
Immediate restart (non-graceful)
*Requires Authentication* | `curl -sk -X POST -u : -H "Content-Type: application/json" -d '{"ResetType": "ForceRestart"}' https://:/redfish/v1/Systems//Actions/ComputerSystem.Reset` | See [Perform Power Actions](#perform-power-actions) for details on all power operations | | **Power Cycle**
Power cycle (off then on)
*Requires Authentication* | `curl -sk -X POST -u : -H "Content-Type: application/json" -d '{"ResetType": "PowerCycle"}' https://:/redfish/v1/Systems//Actions/ComputerSystem.Reset` | See [Perform Power Actions](#perform-power-actions) for details on all power operations | +| **Reset to BIOS**
Reset to BIOS
*Requires Authentication* | `curl -sk -X PATCH -u : -H "Content-Type: application/json" -d '{"Boot": {"BootSourceOverrideTarget": "BiosSetup", "BootSourceOverrideEnabled": "Once"}}' https://:/redfish/v1/Systems/` | See [Reset to BIOS](#reset-to-bios) for details | | **Get System Power State**
Check current power state
*Requires Authentication* | `curl -sk -u : https://:/redfish/v1/Systems/ \| jq .PowerState` | See [Get System Power State](#get-system-power-state) for details | From c65d954ef341b0c210e88b5694f7343eb9691943 Mon Sep 17 00:00:00 2001 From: DevipriyaS17 Date: Wed, 4 Mar 2026 18:39:16 +0530 Subject: [PATCH 3/3] docs: added session commands --- docs/Tutorials/Redfish/redfishUserGuide.md | 88 ++++++++++++++++++++++ 1 file changed, 88 insertions(+) diff --git a/docs/Tutorials/Redfish/redfishUserGuide.md b/docs/Tutorials/Redfish/redfishUserGuide.md index 170f8848..d7e9726e 100644 --- a/docs/Tutorials/Redfish/redfishUserGuide.md +++ b/docs/Tutorials/Redfish/redfishUserGuide.md @@ -432,6 +432,89 @@ redfishtool -r : -u -p : -u -p -S Always Systems -T 30 -I | jq .PowerState ``` +#### Get SessionService + +**Description:** Retrieve SessionService metadata including session timeout configuration and supported authentication methods. + +**Requires Authentication:** No + +```bash +redfishtool sessions info +``` + +**What to verify:** + +- ✓ Response HTTP 200 OK +- ✓ SessionTimeout value is returned (default 24 hours) +- ✓ ServiceEnabled is true +- ✓ Sessions collection URI is present + +#### Create Session (Login) + +**Description:** Authenticate with the console to obtain a session token for token-based authentication. + +**Requires Authentication:** Basic Auth (username and password) + +```bash +redfishtool -r : -u -p -S Always Sessions +``` + +**What to verify:** + +- ✓ Response HTTP 201 Created +- ✓ X-Auth-Token header is present in response +- ✓ Session ID (@odata.id) is returned +- ✓ Session can be used for subsequent API calls + +#### Get Sessions + +**Description:** Retrieve all active sessions on the console. + +**Requires Authentication:** Yes + +```bash +redfishtool -r : -u -p -S Always Sessions +``` + +**What to verify:** + +- ✓ Response contains Members array +- ✓ Members@odata.count shows number of active sessions +- ✓ Each session has @odata.id and UserName properties + +#### Get Session Details + +**Description:** Retrieve details of a specific session including UserName, CreatedTime, and token information. + +**Requires Authentication:** Yes + +```bash +redfishtool -r : -u -p -S Always Sessions -I +``` + +**What to verify:** + +- ✓ Response HTTP 200 OK +- ✓ Session @odata.id matches the requested session-id +- ✓ UserName is displayed +- ✓ CreatedTime and other session metadata is present + +#### Delete Session (Logout) + +**Description:** End a session and invalidate the authentication token. + +**Requires Authentication:** Yes (session token or Basic Auth) + +```bash +redfishtool -r : -t -S Always Sessions -I -m DELETE +``` + +**What to verify:** + +- ✓ HTTP 204 No Content response +- ✓ Session no longer appears in active sessions list +- ✓ Session token is invalidated for future requests + ### Advantages Over curl The Redfish tool offers several advantages: @@ -490,6 +573,11 @@ The following table provides curl commands for common Redfish API operations. Fo | **Power Cycle**
Power cycle (off then on)
*Requires Authentication* | `curl -sk -X POST -u : -H "Content-Type: application/json" -d '{"ResetType": "PowerCycle"}' https://:/redfish/v1/Systems//Actions/ComputerSystem.Reset` | See [Perform Power Actions](#perform-power-actions) for details on all power operations | | **Reset to BIOS**
Reset to BIOS
*Requires Authentication* | `curl -sk -X PATCH -u : -H "Content-Type: application/json" -d '{"Boot": {"BootSourceOverrideTarget": "BiosSetup", "BootSourceOverrideEnabled": "Once"}}' https://:/redfish/v1/Systems/` | See [Reset to BIOS](#reset-to-bios) for details | | **Get System Power State**
Check current power state
*Requires Authentication* | `curl -sk -u : https://:/redfish/v1/Systems/ \| jq .PowerState` | See [Get System Power State](#get-system-power-state) for details | +| **Get SessionService**
Get SessionService metadata
*No Authentication Required* | `curl -sk https://:/redfish/v1/SessionService \| jq` | See [Get SessionService](#get-sessionservice) for details | +| **Get Sessions**
Get all active sessions
*Requires Authentication* | `curl -sk -u : https://:/redfish/v1/SessionService/Sessions \| jq` | See [Get Sessions](#get-sessions-1) for details | +| **Create Session (Login)**
Authenticate and obtain session token
*No Pre-Authentication Required* | `curl -sk -X POST -H "Content-Type: application/json" -d '{"UserName": "", "Password": ""}' https://:/redfish/v1/SessionService/Sessions \| jq` | See [Create Session](#create-session-login-1) for details | +| **Get Session Details**
Get details of a specific session
*Requires Authentication* | `curl -sk -u : https://:/redfish/v1/SessionService/Sessions/ \| jq` | See [Get Session Details](#get-session-details) for details | +| **Delete Session (Logout)**
End a session and invalidate token
*Requires Authentication* | `curl -sk -X DELETE -H "X-Auth-Token: " https://:/redfish/v1/SessionService/Sessions/` | See [Delete Session](#delete-session-logout-1) for details | ---