Skip to content

redfish user guide

Jump to bottom
DevipriyaS17 edited this page Dec 19, 2025 · 35 revisions

DMT Console Redfish User Guide

Table of Contents

  1. Introduction

  2. Prerequisites

  3. Building the DMT Console Application

  4. Configuring and Executing the DMT Console Application

  5. Adding a Device to the DMT Console

  6. Using the Redfish API through DMTF Redfish Tool

  7. Using the Redfish API through curl commands

  8. Common Use Cases

  9. Error Handling

  10. Troubleshooting

  11. Additional Documentation Resources

Introduction

This guide provides comprehensive instructions for setting up, configuring, and testing the DMT Console Redfish API implementation. The Redfish API is a modern, RESTful interface that provides programmatic access to manage Intel AMT-enabled devices through standardized HTTP endpoints.

Purpose

This document will help you:

  • Set up the environment and install required tools
  • Build and configure the DMT Console application
  • Add and manage devices through the API
  • Test Redfish endpoints using curl commands or using DMTF Redfish tool.
  • Troubleshoot common issues

Platform Guide

This guide supports both Linux and Windows platforms. Commands and examples are provided for both operating systems throughout the document.

Quick Navigation:

  • Windows Users: Expand sections labeled "Windows PowerShell Commands" or "Windows PowerShell Installation" (open by default)
  • Linux Users: Expand sections labeled "Linux BashShell Commands" or "Linux BashShell Installation" (click to expand)
  • Platform-Agnostic: API concepts, responses, and Redfish operations are identical across platforms

Supported Redfish Features

The DMT Console implements the following Redfish API v1.19.0 features which enable enterprise device management scenarios including remote power management (lights-out operations, scheduled maintenance, disaster recovery) and fleet management (inventory discovery, health monitoring).

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:
    • BIOS Version
    • Host Name
    • Manufacturer and Model
    • Serial Number
    • System Type (Physical/Virtual)
    • Power State (On/Off)
    • Health Status
  • Power Control Actions (/redfish/v1/Systems/{id}/Actions/ComputerSystem.Reset) - Remote power management via ComputerSystem.Reset:
    • On - Power on the system
    • ForceOff - Immediate power off (non-graceful)
    • ForceRestart - Immediate restart (non-graceful)
    • PowerCycle - Power cycle (off then on)

Standards Compliance:

  • Redfish API v1.19.0
  • OData Version 4.0
  • DMTF ComputerSystem v1.26.0 schema

Document Structure

This guide is organized into the following sections:

  1. Prerequisites - System requirements and tool installation
  2. Building the DMT Console Application - Clone the repository and build the application
  3. Configuring and Executing the DMT Console Application - Configuration settings and server startup
  4. Adding a Device to the DMT Console - Device management procedures
  5. Using the Redfish API through DMTF Redfish Tool - API testing with the official DMTF Redfish tool
  6. Using the Redfish API through curl commands - API testing with curl commands
  7. Troubleshooting - Common issues and solutions
  8. Additional Resources - Documentation and reference links

Setup Overview

The following diagram illustrates the connections between components:

graph TB
    subgraph "Admin Machine"
        A[DMT Console<br/>with Redfish Service<br/>Port 8181]
        B[curl]
        C[Redfish Tool]

        B -.->|API Requests <br/>/redfish/v1/.. <br/>/api/v1/..| A
        C -.->|API Requests <br/>/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 <br/> WS-MAN API| D
    A -->|API Requests <br/> WS-MAN API| E
    A -->|API Requests <br/> 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
Loading

Components:

  • DMT Console: Redfish service running on the admin 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

System Requirements

  • Operating System:
    • Linux: Ubuntu 22.04 or later (recommended)
    • Windows: Windows 10/11
  • PowerShell: PowerShell 7.5.4 or later (for Windows users)
  • Memory: Minimum 4GB RAM
  • Disk Space: At least 2GB free space
  • Network: Active network connection for device communication

Required Tools

The following tools are required to build and test the DMT Console Redfish implementation:

Tool Version Purpose Windows Linux
Go 1.25.5 Build the Console application Download Download
Git Latest Clone repository Download Download
PowerShell 7.5.4+ Scripting environment Download N/A
curl 7.81.1+ Test HTTP API endpoints Pre-installed Pre-installed
jq jq-1.8.1+ Pretty-print JSON responses Install via winget/choco Download
python 3.14.2+ Required for Redfish Tool Download Pre-installed
Redfish Tool 1.1.8 DMTF CLI tool for Redfish API Download Download

Check for all the tools versions as below before proceeding with the next steps:

Windows PowerShell Commands 
# Note for the commands here using test user name as user1 this could be any user name on your machine
C:\Users\user1> pwsh --version
PowerShell 7.5.4

C:\Users\user1> go version
go version go1.25.5 windows/amd64

C:\Users\user1> curl --version
curl 8.13.0 (Windows) libcurl/8.13.0 Schannel zlib/1.3.1 WinIDN

C:\Users\user1> jq --version
jq-1.8.1

C:\Users\user1> git --version
git version 2.52.0.windows.1

C:\Users\user1> python --version
Python 3.14.2

C:\Users\user1>  pip --version
pip 25.3 from C:\Users\user1\AppData\Local\Programs\Python\Python314\Lib\site-packages\pip (python 3.14)
Linux Bash Shell Commands 
# Check tool versions on Linux

$ go version
go version go1.25.5 linux/amd64

$ curl --version
curl 7.81.0 (x86_64-pc-linux-gnu) libcurl/7.81.0 OpenSSL/3.0.2 zlib/1.2.11

$ jq --version
jq-1.8.1

$ git --version
git version 2.52.0

$ python3 --version
Python 3.14.2

$ pip3 --version
pip 25.3 from /usr/lib/python3/dist-packages/pip (python 3.14)

Installing Redfish Tool

The DMTF Redfish Tool is a Python-based command-line utility for interacting with Redfish services. It provides a more user-friendly interface compared to raw curl commands.

Windows PowerShell Installation

Windows Setup Required: After installation, you must create a PowerShell function to use redfishtool command. Add this function to your PowerShell profile ($PROFILE) to make it permanent across sessions.

# Install redfishtool via pip by providing the proxy if needed
python -m pip install redfishtool --user --proxy=<http proxy url>

# Post installation create this alias for redfishtool command
# Find the path where python is installed
Get-Command python
# Find the location where redfishtool is installed
# use pip to show where redfishtool is installed
pip show redfishtool
# Look for:
Location: C:\Users\user1\AppData\<Local\Roaming>\Programs\Python\Python314\site-packages
# Then redfishtool.py will be inside the Scripts folder next to that:
C:\Users\user1\AppData\<Local\Roaming>\Programs\Python\Python314\Scripts\redfishtool.py
# Update the below paths accordingly, here's an example
Remove-Item Alias:redfishtool -ErrorAction SilentlyContinue
Remove-Item Function:redfishtool -ErrorAction SilentlyContinue
function redfishtool {
    & "<location of python>" "<path to the redfishtool folder>\redfishtool.py" @args
}
# Verify usage
redfishtool --help
Linux BashShell Installation 
# Install specific version via pip
pip install redfishtool==1.1.8

# Verify installation
redfishtool -V

Building the DMT Console Application

Clone the Repository

Windows PowerShell Commands 
# Clone the DMT Console repository
git clone --branch rf-v1.0.0 https://github.com/nmgaston/console.git
cd console

# Verify you're in the correct directory
dir
# You should see directories like: cmd/, pkg/, internal/, config/, redfish/, etc.
Linux BashShell Commands 
# Clone the DMT Console repository
git clone --branch rf-v1.0.0 https://github.com/nmgaston/console.git
cd console

# Verify you're in the correct directory
ls -la
# You should see directories like: cmd/, pkg/, internal/, config/, redfish/, etc.

Build the Application

Windows PowerShell Commands 
# Navigate to the project root
cd C:\path\to\console

# Build the application
go build -o console.exe .\cmd\app

Note: If you have issues in downloading the go package due to connection failures or timeout, set proxy for the Windows PowerShell as follows

setx HTTP_PROXY  "<http proxy>"; setx HTTPS_PROXY "<https proxy>"; setx GOPROXY direct
# close and open a new powershell window for the changes to take effect
Linux BashShell Commands 
# Navigate to the project root
cd /path/to/console

# Build the application
go build -o console ./cmd/app

Verify the Build

Windows PowerShell Commands 
# Check the binary exists
dir console.exe
Linux BashShell Commands 
# Check the binary exists
ls -lh ./console

Configuring and Executing the DMT Console Application

We shall be using the default configuration file located at config/config.yml for this guide and override only the following information through the environement variables.

Key Configuration Parameters in the context of Redfish:

Parameter Description Default Value
app.encryption_key 32-char Encryption key for sensitive data "" (empty)
http.host HTTP server host localhost
http.port HTTP/Redfish API server port "8181"
logger.log_level Logging level (debug, info, warn, error) info
auth.adminUsername Admin username for standalone mode standalone
auth.adminPassword Admin password for standalone mode G@ppm0ym

Starting the Console Application

Windows PowerShell Commands 
$env:HTTP_PORT="8181"
$env:HTTP_HOST="localhost"
$env:AUTH_ADMIN_USERNAME="<admin-user-name>"
$env:AUTH_ADMIN_PASSWORD="<admin-password>"
$env:APP_ENCRYPTION_KEY="aB3dE5gH7jK9mN1pQ2rS4tU6wX8zC0vB"
.\console.exe --config config\config.yml
Linux BashShell Commands 
HTTP_PORT=8181 HTTP_HOST=localhost AUTH_ADMIN_USERNAME=<admin-user-name> AUTH_ADMIN_PASSWORD=<admin-password> APP_ENCRYPTION_KEY="aB3dE5gH7jK9mN1pQ2rS4tU6wX8zC0vB" ./console -config config/config.yml

Expected output:

# Note : If you are not providing your own encryption key, you will be prompted to generate a new one as shown below. Type 'Y' and press Enter to proceed.

2025/12/06 12:52:48 migrate: environment variable not declared: DB_URL -- using embedded database
2025/12/06 12:52:48 DB path : /home/admin/.config/device-management-toolkit/console.db
2025/12/12 20:30:16 ←[31mWarning: Key Not Found, Generate new key? -- This will prevent access to existing data? Y/N: ←[0m
Y
{"level":"info","time":"2025-12-06T12:52:48+05:30","caller":"/home/admin/rf-ver/console/internal/app/app.go:32","message":"app - Run - version: DEVELOPMENT"}
{"time":"2025-12-06T12:52:48.39601868+05:30","level":"INFO","prefix":"-","file":"service_root.go","line":"251","message":"Loaded 1 services from OpenAPI spec: [Systems]"}
{"level":"info","time":"2025-12-06T12:52:48+05:30","caller":"/home/admin/rf-ver/console/redfish/component.go:101","message":"Redfish component initialized successfully with 1 OData services"}
{"level":"warn","time":"2025-12-06T12:52:48+05:30","caller":"/home/admin/rf-ver/console/internal/controller/http/router.go:142","message":"Could not read embedded main.js: open ui/main.js: file does not exist"}
{"level":"info","time":"2025-12-06T12:52:48+05:30","caller":"/home/admin/rf-ver/console/redfish/component.go:158","message":"Redfish API routes registered with OpenAPI-spec-driven Basic Auth"}
{"level":"info","time":"2025-12-06T12:52:48+05:30","caller":"/home/admin/rf-ver/console/redfish/component.go:181","message":"Redfish API routes registered successfully"}
{"level":"info","time":"2025-12-06T12:52:48+05:30","caller":"/home/admin/rf-ver/console/pkg/httpserver/server.go:131","message":"TLS: using existing self-signed certificate cert=/tmp/console_selfsigned.crt key=/tmp/console_selfsigned.key"}

Verifying the Server

Test that the server 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.

# Check if the server is listening (use -k to ignore self-signed certificate, -s for silent mode)
curl -sk https://<http_host>:<http_port>/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).

Windows PowerShell: Example for adding localhost to NO_PROXY

setx NO_PROXY "localhost,127.0.0.1,::1"

Adding a Device to the DMT Console

The DMT Console supports two activation modes: Client Control Mode(CCM) and Admin Control Mode(ACM). This section focuses on activating the device in CCM Mode.

CCM (Client Control Mode):

  • Password-based authentication
  • Simple setup process
  • No provisioning certificate required
  • Ideal for testing, deployments, and quick setup
  • Requires user consent for remote operations

This section describes the complete workflow for adding a device to the DMT console using CCM Mode, following the procedures documented in Create Profiles - CCM Activation. The workflow uses APIs described in Remote Provisioning Server and Management Provisioning Server. Steps involved are:

  1. Activate Device in CCM Mode: Use RPC (Remote Provisioning Client) to activate Intel AMT devices

  2. Add Devices to Console: Once devices are activated, add them to the console for management. See Adding a Device via API below

Device Requirements

To add a device to the DMT Console, ensure:

  • Device has Intel AMT enabled
  • Device is network-accessible from the Console server
  • You have device credentials (username/password)
  • AMT firmware version is supported (typically 11.x or higher)

DMT Console Requirements

  • DMT Console must be running
  • Admin credentials for the console

Step 1: Activate Device in CCM Mode

Use RPC (Remote Provisioning Client) to activate Intel AMT devices in CCM mode. Follow the instructions in the official guide: - Device Activation Guide to download the RPC onto the AMT device. Use the following command as reference:

rpc activate -local -ccm -password <password>

Note: Note down the password that you use during activation as it will be required later when adding the device to the console.

Step 2: Add Devices to Console

Step 2.1: Setup Environment Variables

Set up the required environment variables for the profile creation workflow. Replace the placeholder values with your actual configuration.

Windows PowerShell Commands

Console Connection Settings:

$env:HTTP_HOST="<http_host>"              # Console server IP or hostname
$env:HTTP_PORT="<http_port>"              # Console server port (default: 8181)

Authentication Credentials:

$env:ADMIN_USERNAME="<admin-user-name>"   # Console admin username
$env:ADMIN_PASSWORD="<admin-password>"    # Console admin password

Device Configuration:

$env:DEVICE_HOSTNAME="<device-hostname-or-ip>"    # Device hostname or IP address
$env:DEVICE_FRIENDLY_NAME="<friendly-name>"       # Descriptive name for the device
$env:DEVICE_USERNAME="admin"                      # AMT username (Typically 'admin')
$env:DEVICE_PASSWORD="<amt-password>"             # AMT password (Password used during activation)

Example Configuration:

$env:HTTP_HOST="localhost"
$env:HTTP_PORT="8181"
$env:ADMIN_USERNAME="admin"
$env:ADMIN_PASSWORD="Password@123"
$env:DEVICE_HOSTNAME="1.2.3.4"
$env:DEVICE_FRIENDLY_NAME="Conference Room Device"
$env:DEVICE_USERNAME="admin"
$env:DEVICE_PASSWORD="Password@123"
Linux BashShell Commands

Console Connection Settings:

export HTTP_HOST=<http_host>              # Console server IP or hostname
export HTTP_PORT=<http_port>              # Console server port (default: 8181)

Authentication Credentials:

export ADMIN_USERNAME=<admin-user-name>   # Console admin username
export ADMIN_PASSWORD=<admin-password>    # Console admin password

Device Configuration:

export DEVICE_HOSTNAME="<device-hostname-or-ip>"    # Device hostname or IP address
export DEVICE_FRIENDLY_NAME="<friendly-name>"       # Descriptive name for the device
export DEVICE_USERNAME="admin"                      # AMT username (typically 'admin')
export DEVICE_PASSWORD="<amt-password>"             # AMT password (same as profile AMT password)

Example Configuration:

export HTTP_HOST=localhost
export HTTP_PORT=8181
export ADMIN_USERNAME=admin
export ADMIN_PASSWORD=Password@123
export DEVICE_HOSTNAME="1.2.3.4"
export DEVICE_FRIENDLY_NAME="Conference Room Device"
export DEVICE_USERNAME="admin"
export DEVICE_PASSWORD="Password@123"

Step 2.2: Log in to the Console

Goal: Obtain JWT authentication token

Token Lifetime: ~1 hour

If Token Expires: Re-run this command if you get 401 errors

Purpose: Authenticate with the DMT Console and obtain a JWT (JSON Web Token) for subsequent API requests.

What this does: Sends your admin credentials to the console's authorization endpoint. Upon successful authentication, the console returns a JWT token that must be included in all subsequent API requests.

Windows PowerShell Commands 
# Make the API request with response code
$RESPONSE = curl.exe -s -k -w "`n%{http_code}" `
  "https://$($env:HTTP_HOST):$($env:HTTP_PORT)/api/v1/authorize" `
  --header "Content-Type: application/json" `
  --data "{`"username`":`"$($env:ADMIN_USERNAME)`",`"password`":`"$($env:ADMIN_PASSWORD)`"}"

# Extract token from first line of response
$JWT_TOKEN = ($RESPONSE -split "`n")[0] | jq -r '.token'

echo $RESPONSE
echo "Token received is: $JWT_TOKEN"
Linux BashShell Commands 
# Log in to the console application and retrieve the JWT for authentication
RESPONSE=$(curl -sk -w "\nHTTP Response Code: %{http_code}\n" \
  https://$HTTP_HOST:$HTTP_PORT/api/v1/authorize \
  -H 'Content-Type: application/json' \
  --data-raw '{"username":"'$ADMIN_USERNAME'","password":"'$ADMIN_PASSWORD'"}')
JWT_TOKEN=$(echo "$RESPONSE" | grep -v "HTTP Response Code" | jq -r '.token')
echo "$RESPONSE"
echo "Token received is : $JWT_TOKEN"

Expected Response:

HTTP Response Code: 200
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3NjUyMDIyMzd9.TV8f1dK8G_u1QoPIp9XIcT0wfmXSkSLaPd4MS-hcNVY"
}

✅ Success Indicators:

  • HTTP Response Code should be 200 (OK)
  • Response contains a token field with a long JWT string
  • Token is successfully extracted and stored in $JWT_TOKEN variable
  • No error messages appear in the console output

Step 2.3: Verify Authentication

Purpose: Confirm that authentication was successful and the JWT token is valid.

What this does: Makes an authenticated API call to retrieve device statistics. This simple GET request verifies that your JWT token is working correctly before proceeding with profile creation.

Windows PowerShell Commands 
curl.exe -s -k -w "`nHTTP Response Code: %{http_code}`n" `
  "https://$($env:HTTP_HOST):$($env:HTTP_PORT)/api/v1/devices/stats" `
  --header "Authorization: Bearer $JWT_TOKEN" |
  ForEach-Object { if ($_ -notmatch '^HTTP Response Code:') { $_ | jq } else { echo $_ } }
Linux BashShell Commands 
curl -sk -w "\nHTTP Response Code: %{http_code}\n" -o >(jq) \
  https://$HTTP_HOST:$HTTP_PORT/api/v1/devices/stats \
  -H "Authorization: Bearer $JWT_TOKEN"

Expected Response:

{
  "totalCount": 0,
  "connectedCount": 0,
  "disconnectedCount": 0
}
HTTP Response Code: 200

✅ Success Indicators:

  • HTTP Response Code should be 200 (OK)
  • Response contains device statistics (counts may be 0 if no devices are added yet)
  • If you receive HTTP 401 (Unauthorized), the token is invalid - re-run the login command

Step 2.4: Add a Device

Purpose: Add an activated Intel AMT device to the DMT Console for management.

What this does: Registers an activated device with the console by providing its connection details and credentials. Once added, the device can be managed through the Redfish API and console interface. The device must be already activated using a CCM profile before adding it to the console.

Windows PowerShell Commands 
curl.exe -s -k -w "`nHTTP Response Code: %{http_code}`n" -X POST `
  "https://$($env:HTTP_HOST):$($env:HTTP_PORT)/api/v1/devices" `
  --header "Accept: application/json, text/plain, */*" `
  --header "Authorization: Bearer $JWT_TOKEN" `
  --header "Content-Type: application/json" `
  --data "{`"hostname`":`"$($env:DEVICE_HOSTNAME)`",`"friendlyName`":`"$($env:DEVICE_FRIENDLY_NAME)`",`"username`":`"$($env:DEVICE_USERNAME)`",`"password`":`"$($env:DEVICE_PASSWORD)`",`"tenantId`":`"`",`"useTLS`":true,`"allowSelfSigned`":true,`"tags`":[]}" |
  ForEach-Object { if ($_ -notmatch '^HTTP Response Code:') { $_ | jq } else { echo $_ } }
Linux BashShell Commands 
curl -sk -w "\nHTTP Response Code: %{http_code}\n" -o >(jq) -X POST \
  "https://$HTTP_HOST:$HTTP_PORT/api/v1/devices" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  --data-raw "{\"hostname\":\"$DEVICE_HOSTNAME\",\"friendlyName\":\"$DEVICE_FRIENDLY_NAME\",\"username\":\"$DEVICE_USERNAME\",\"password\":\"$DEVICE_PASSWORD\",\"tenantId\":\"\",\"useTLS\":true,\"allowSelfSigned\":true,\"tags\":[]}"

Expected Response:

HTTP Response Code: 200
{
  "connectionStatus": false,
  "mpsInstance": "",
  "hostname": "1.2.3.4",
  "guid": "7b7f775e-c970-4fd9-8230-1da7c00f11f4",
  "mpsusername": "",
  "tags": [],
  "tenantId": "",
  "friendlyName": "Conference Room Device",
  "dnsSuffix": "",
  "username": "admin",
  "password": "",
  "useTLS": true,
  "allowSelfSigned": true,
  "certHash": ""
}

✅ Success Indicators:

  • HTTP Response Code should be 200 (OK)
  • Response contains a guid field (unique device identifier)
  • connectionStatus is true (device is connected)
  • deviceInfo shows firmware version and current mode (ccm or acm)
  • Device appears in the console's device list

Common Issues:

  • HTTP 400 "Device already exists": Device with this hostname is already registered
  • Connection failed: Verify device is network accessible and AMT credentials are correct
  • TLS errors: Set allowSelfSigned to true for devices with self-signed certificates

Step 2.5: List All Devices

Purpose: Retrieve a list of all devices registered in the console.

Windows PowerShell Commands 
curl.exe -s -k -w "`nHTTP Response Code: %{http_code}`n" `
  "https://$($env:HTTP_HOST):$($env:HTTP_PORT)/api/v1/devices" `
  --header "Authorization: Bearer $JWT_TOKEN" |
  ForEach-Object { if ($_ -notmatch '^HTTP Response Code:') { $_ | jq } else { echo $_ } }
Linux BashShell Commands 
curl -sk -w "\nHTTP Response Code: %{http_code}\n" -o >(jq) \
  "https://$HTTP_HOST:$HTTP_PORT/api/v1/devices" \
  -H "Authorization: Bearer $JWT_TOKEN"

Expected Response:

HTTP Response Code: 200
[
  {
    "connectionStatus": false,
    "mpsInstance": "",
    "hostname": "1.2.3.4",
    "guid": "1dc41c82-8292-4b70-a235-4b6690500913",
    "mpsusername": "",
    "tags": null,
    "tenantId": "",
    "friendlyName": "Conference Room Device",
    "dnsSuffix": "",
    "username": "admin",
    "password": "",
    "useTLS": true,
    "allowSelfSigned": true,
    "certHash": ""
  }
]

Step 2.6: Get Specific Device Details

Purpose: Retrieve detailed information about a specific device.

Configure Device GUID:

Windows PowerShell Commands 
$env:DEVICE_GUID="<device-guid>"  # GUID from device list or add response
Linux BashShell Commands 
export DEVICE_GUID=<device-guid>  # GUID from device list or add response

Get Device:

Windows PowerShell Commands 
curl.exe -s -k -w "`nHTTP Response Code: %{http_code}`n" `
  "https://$($env:HTTP_HOST):$($env:HTTP_PORT)/api/v1/devices/$($env:DEVICE_GUID)" `
  --header "Authorization: Bearer $JWT_TOKEN" |
  ForEach-Object { if ($_ -notmatch '^HTTP Response Code:') { $_ | jq } else { echo $_ } }
Linux BashShell Commands 
curl -sk -w "\nHTTP Response Code: %{http_code}\n" -o >(jq) \
  "https://$HTTP_HOST:$HTTP_PORT/api/v1/devices/$DEVICE_GUID" \
  -H "Authorization: Bearer $JWT_TOKEN"

Expected Response:

HTTP Response Code: 200
{
  "connectionStatus": false,
  "mpsInstance": "",
  "hostname": "1.2.3.4",
  "guid": "1dc41c82-8292-4b70-a235-4b6690500913",
  "mpsusername": "",
  "tags": null,
  "tenantId": "",
  "friendlyName": "Conference Room Device",
  "dnsSuffix": "",
  "username": "admin",
  "password": "",
  "useTLS": true,
  "allowSelfSigned": true,
  "certHash": ""
}
HTTP Response Code: 200

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: https://github.com/DMTF/Redfishtool

Note: If you haven't already installed the Redfish tool, please refer to the Installing Redfish Tool section in the Prerequisites.

Windows PowerShell Users: Remember to set up the redfishtool function alias in every new PowerShell session. Refer to the Installing Redfish Tool section for the function definition, or add it to your PowerShell profile ($PROFILE) to make it permanent across all sessions.

Basic Usage

The general syntax for the Redfish tool is:

redfishtool [options] <command> [command-options]

Common options:

  • -r <host> or --rhost <host>: Specify the Redfish service host
  • -u <user> or --user <user>: Username for authentication
  • -p <password> or --password <password>: 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.

redfishtool -r <http_host>:<http_port> -S Always root

Reference Successful 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": "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

redfishtool -r <http_host>:<http_port> -S Always odata

Reference Successful Response:

{
  "@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

redfishtool -r <http_host>:<http_port> -S Always metadata

Reference Successful Response:

<?xml version="1.0" encoding="UTF-8"?>
<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx" Version="4.0">
    <edmx:Reference Uri="http://redfish.dmtf.org/schemas/v1/ActionInfo_v1.xml">
        <edmx:Include Namespace="ActionInfo"/>
        <edmx:Include Namespace="ActionInfo.1_5_0"/>
    </edmx:Reference>
    <edmx:Reference Uri="http://redfish.dmtf.org/schemas/v1/ComputerSystemCollection_v1.xml">
        <edmx:Include Namespace="ComputerSystemCollection"/>
    </edmx:Reference>
    <edmx:Reference Uri="http://redfish.dmtf.org/schemas/v1/ComputerSystem_v1.xml">
        <edmx:Include Namespace="ComputerSystem"/>
        <edmx:Include Namespace="ComputerSystem.1_26_0"/>
    </edmx:Reference>
    <edmx:Reference Uri="http://redfish.dmtf.org/schemas/v1/Message_v1.xml">
        <edmx:Include Namespace="Message"/>
        <edmx:Include Namespace="Message.1_2_1"/>
    </edmx:Reference>
    <edmx:Reference Uri="http://redfish.dmtf.org/schemas/v1/ResolutionStep_v1.xml">
        <edmx:Include Namespace="ResolutionStep"/>
        <edmx:Include Namespace="ResolutionStep.1_0_1"/>
    </edmx:Reference>
    <edmx:Reference Uri="http://redfish.dmtf.org/schemas/v1/Resource_v1.xml">
        <edmx:Include Namespace="Resource"/>
        <edmx:Include Namespace="Resource.1_23_0"/>
    </edmx:Reference>
    <edmx:Reference Uri="http://redfish.dmtf.org/schemas/v1/ServiceRoot_v1.xml">
        <edmx:Include Namespace="ServiceRoot"/>
        <edmx:Include Namespace="ServiceRoot.1_19_0"/>
    </edmx:Reference>
    <edmx:DataServices>
        <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Service">
            <EntityContainer Name="Service" Extends="ServiceRoot.v1_19_0.ServiceContainer"/>
        </Schema>
    </edmx:DataServices>
</edmx:Edmx>

What to verify:

  • ✓ Content-Type is application/xml or text/xml
  • ✓ Valid XML structure with <edmx:Edmx> 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.

redfishtool -r <http_host>:<http_port> -u <admin-user-name> -p <admin-user-password> -S Always Systems

Reference Successful Response:

{
  "@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 <system-id> with the actual system identifier (e.g., device GUID).

redfishtool -r <http_host>:<http_port> -u <admin-user-name> -p <admin-user-password> -S Always Systems -I <device-guid> -T 30

Reference Successful Response:

{
  "@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:

redfishtool -r <http_host>:<http_port> -u <admin-user-name> -p <admin-user-password> -S Always Systems -I <device-guid> reset On

Power Off (Force):

redfishtool -r <http_host>:<http_port> -u <admin-user-name> -p <admin-user-password> -S Always Systems -I <device-guid> reset ForceOff

Force Restart:

redfishtool -r <http_host>:<http_port> -u <admin-user-name> -p <admin-user-password> -S Always Systems -I <device-guid> reset ForceRestart

PowerCycle:

redfishtool -r <http_host>:<http_port> -u <admin-user-name> -p <admin-user-password> -S Always Systems -I <device-guid> reset PowerCycle

Get System Power State

Description: Check the current power state of a specific system.

Requires Authentication: Yes

redfishtool -r <http_host>:<http_port> -u <admin-user-name> -p <admin-user-password> -S Always Systems -T 30 -I <device-guid> | 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: https://github.com/DMTF/Redfishtool

Using the Redfish API through curl commands

Authentication

Most Redfish endpoints require Basic Authentication. Use the credentials as provided during the console execution:

Windows PowerShell Commands 
# Using curl with Basic Auth
curl.exe -sk -u <admin-user-name>:<admin-password> https://<http_host>:<http_port>/redfish/v1/Systems
Linux BashShell Commands 
# Using curl with Basic Auth
curl -sk -u <admin-user-name>:<admin-password> https://<http_host>:<http_port>/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.

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://<http_host>:<http_port>/redfish/v1/ | jq See Get Service Root for response format and verification steps
Get OData Service Document
Retrieve the OData service document		 curl -sk https://<http_host>:<http_port>/redfish/v1/odata | jq See Get OData Service Document for response format and verification steps
Get Metadata Document
Retrieve the Redfish metadata document in XML format		 curl -sk https://<http_host>:<http_port>/redfish/v1/\$metadata See Get Metadata Document for response format and verification steps
Get Systems Collection
Retrieve all computer systems
Requires Authentication 		curl -sk -u <admin-user-name>:<admin-password> https://<http_host>:<http_port>/redfish/v1/Systems | jq See 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 <admin-user-name>:<admin-password> https://<http_host>:<http_port>/redfish/v1/Systems/<system-id> | jq See Get Specific System Details for response format and verification steps
Power On
Power on a system
Requires Authentication 		curl -sk -X POST -u <admin-user-name>:<admin-password> -H "Content-Type: application/json" -d '{"ResetType": "On"}' https://<http_host>:<http_port>/redfish/v1/Systems/<system-id>/Actions/ComputerSystem.Reset See Perform Power Actions for details on all power operations
Force Off
Immediate power off (non-graceful)
Requires Authentication 		curl -sk -X POST -u <admin-user-name>:<admin-password> -H "Content-Type: application/json" -d '{"ResetType": "ForceOff"}' https://<http_host>:<http_port>/redfish/v1/Systems/<system-id>/Actions/ComputerSystem.Reset See Perform Power Actions for details on all power operations
Force Restart
Immediate restart (non-graceful)
Requires Authentication 		curl -sk -X POST -u <admin-user-name>:<admin-password> -H "Content-Type: application/json" -d '{"ResetType": "ForceRestart"}' https://<http_host>:<http_port>/redfish/v1/Systems/<system-id>/Actions/ComputerSystem.Reset See Perform Power Actions for details on all power operations
Power Cycle
Power cycle (off then on)
Requires Authentication 		curl -sk -X POST -u <admin-user-name>:<admin-password> -H "Content-Type: application/json" -d '{"ResetType": "PowerCycle"}' https://<http_host>:<http_port>/redfish/v1/Systems/<system-id>/Actions/ComputerSystem.Reset See Perform Power Actions for details on all power operations
Get System Power State
Check current power state
Requires Authentication 		curl -sk -u <admin-user-name>:<admin-password> https://<http_host>:<http_port>/redfish/v1/Systems/<system-id> | jq .PowerState See Get System Power State for details

Common Use Cases

Use Case 1: Check Power State of All Systems

Windows PowerShell Commands 
# 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 BashShell Commands 
# 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 PowerShell Commands 
# 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 BashShell Commands 
# 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 PowerShell Commands 
# 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 BashShell Commands 
# 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 PowerShell Commands 
# 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 BashShell Commands 
# 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:

{
  "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

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:

{
  "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:

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:

{
  "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:

{
  "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:

{
  "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:

Linux:

# 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

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 <PID> -Force

# Or use netstat to find the process
netstat -ano | findstr :8181
taskkill /PID <PID> /F

# Or use a different port
$env:HTTP_PORT=9090
.\console.exe

Additional Documentation Resources

For questions or support, please refer to the project documentation or contact the development team.

Console Wiki

Clone this wiki locally