dracs 1.23.0

Dell Rack & Asset Control System - CLI inventory tool for managing Dell bare-metal systems

DRACS — Dell Rack & Asset Control System

Simple, portable, self-contained dynamic CLI inventory tool for managing Dell bare-metal systems inventory, warranty and lifecycle.

• Plugs directly into Dell Support API
• Live hardware data management via SNMP
• Utilizes a portable SQLite database
• Supports regex and simple search patterns
• Easily extensible to scripting and automation
  • 🚀 Features
  • 🛠️ Prerequisites
  • 📦 Installation
  • 📖 Usage
    • 1. Add a New System
    • 2. Discover a System
    • 3. List Inventory
    • 4. Lookup a Specific System
    • 5. Edit a System
    • 6. Refresh System Data
    • 7. Remove a System
    • Common Usage Patterns
  • ⚙️ Command Reference
    • Global Arguments (apply to all commands)
    • Command Aliases
    • Filter Options for list Command
  • 📝 Tips & Troubleshooting

🚀 Features

• Warranty Tracking: Automatically fetches expiration dates from the Dell API using Service Tags
• Hardware Discovery: Uses SNMP to poll iDRAC and BIOS version information directly from the hardware
• Data Refresh: Update both SNMP hardware data AND warranty information for existing systems
• Version Comparison: List and filter systems based on version strings (e.g., find all hosts with BIOS version less than 2.1.0)
• Flexible Output: View inventory in a formatted grid table or export to JSON for automation
• Verbose Logging: Optional verbose (-v) and debug (-d) modes for detailed progress tracking
• SQLite Backend: No heavy database setup required; everything is stored in a local .db file
• Command Aliases: Short aliases for all commands (e.g., a for add, li for list, rf for refresh)

🛠️ Prerequisites

• Python 3.12+
• Dell TechDirect API Credentials: You must have a Client ID and Secret from Dell to access warranty data
• SNMP Enabled: The target Dell systems must have SNMP enabled on their iDRACs (default community: public)
• Network Access: Ability to reach Dell iDRAC interfaces via DNS (naming convention configured via DRACS_DNS_STRING and DRACS_DNS_MODE)

📦 Installation

1) Clone the repository:

git clone https://github.com/kambiz-aghaiepour/dracs.git
cd dracs

2) Install:

Option A: Install with uv (from cloned repo):

uv sync
source .venv/bin/activate

For development (includes pytest, black, etc.):

uv sync --group dev
source .venv/bin/activate

Option B: Install with pip:

mkdir -p ~/dracs && cd ~/dracs
python3 -m venv venv
source venv/bin/activate
pip install dracs
dracs init

The dracs init command creates example configuration files in the current directory:

• .env.example — environment variable template
• drac-passwords.ini.example — iDRAC credentials template
• BIOS-filename.ini.example — BIOS filename mapping template

After running dracs init, copy and configure the environment file:

cp .env.example .env

Edit .env with your Dell API credentials and other settings (see step 3 below).

To start the web interface, run dracs-webapp from the same directory as your .env file.

3) Configure environment variables: Create a .env file in the root directory:

# Required: Dell TechDirect API credentials
CLIENT_ID=your_dell_client_id
CLIENT_SECRET=your_dell_client_secret

# Required: iDRAC DNS configuration
# DRACS_DNS_STRING: String to add to hostname for iDRAC FQDN
# DRACS_DNS_MODE: How to add the string ('prefix' or 'suffix')
#
# Examples:
# Prefix mode: "mgmt-" + "host01.example.com" = "mgmt-host01.example.com"
DRACS_DNS_STRING=mgmt-
DRACS_DNS_MODE=prefix
#
# Suffix mode: "host01" + "-mm" + ".example.com" = "host01-mm.example.com"
# DRACS_DNS_STRING=-mm
# DRACS_DNS_MODE=suffix

# Optional: SNMP community string (defaults to 'public')
SNMP_COMMUNITY=public

# Optional: Enable debug logging via environment (can also use -d flag)
DEBUG=false

# Flask secret key for session cookie signing (used by the web interface)
# IMPORTANT: For production, generate a secure key with:
#   python -c "import secrets; print(secrets.token_hex(32))"
FLASK_SECRET_KEY=dev-secret-key-change-in-production-12345678901234567890123456789012

# Web interface admin credentials
# Change these from the defaults for production use
WEBADMIN_USER=admin
WEBADMIN_PASSWORD=admin

Note: Obtain Dell API credentials from Dell TechDirect

Security: The WEBADMIN_USER and WEBADMIN_PASSWORD control access to the web interface. Change these from the defaults before deploying to production.

The FLASK_SECRET_KEY is used to cryptographically sign session cookies. The default value is for development only. For production, generate a secure key:

python -c "import secrets; print(secrets.token_hex(32))"

Copy the output and set it as FLASK_SECRET_KEY in your .env file. Anyone who knows this key can forge session cookies and bypass authentication.

4) Configure iDRAC credentials (optional, for web interface):

The web interface uses SSH to connect to iDRAC for firmware updates, BIOS updates, and job queue management. By default it uses root/calvin. To customize credentials, copy the example file to the same directory where the webapp runs:

cp drac-passwords.ini.example drac-passwords.ini

Edit drac-passwords.ini to set default credentials and optional per-host overrides:

[DEFAULT]
username = root
password = calvin

[host01.example.com]
username = admin
password = admin

The [DEFAULT] section applies to all hosts. Add a section named after a specific hostname to override credentials for that host. This file contains sensitive credentials and is excluded from version control via .gitignore.

📖 Usage

DRACS uses subcommands for different operations: add, discover, edit, lookup, list, refresh, and remove.

1. Add a New System

This polls the iDRAC for firmware/BIOS versions and the Dell API for warranty.

# Add a system (full command)
dracs add --svctag ABC1234 --target server01.example.com --model R660

# Using alias and verbose output
dracs -v a -s ABC1234 -t server01.example.com -m R660

# With custom database path
dracs -w /path/to/custom.db add -s ABC1234 -t server01 -m R650

2. Discover a System

Automatically discover service tag and model information via SNMP, then optionally add to database.

# Discover a system (prompts for confirmation)
dracs discover --target server01.example.com

# Using alias
dracs d -t server01.example.com

# Auto-add without prompting
dracs discover --target server01.example.com --add

# With verbose output
dracs -v discover -t server01.example.com

# Discover and auto-add using alias
dracs d -t server01.example.com --add

3. List Inventory

View all systems. You can filter by model, expiration, or version. Results are always sorted by hostname.

# List all systems
dracs list

# List all systems (using alias)
dracs li

# List systems by model
dracs list --model R660

# List systems expiring in the next 30 days (excludes already expired)
dracs list --expires_in 30

# List systems with expired warranties
dracs list --expired

# List systems with hostname matching a pattern
dracs list --regex "server%"

# Filter by BIOS version
dracs list --bios_lt 2.5.1        # BIOS less than 2.5.1
dracs list --bios_le 2.5.1        # BIOS less than or equal to 2.5.1
dracs list --bios_gt 2.5.1        # BIOS greater than 2.5.1
dracs list --bios_ge 2.5.1        # BIOS greater than or equal to 2.5.1
dracs list --bios_eq 2.5.1        # BIOS equal to 2.5.1

# Filter by iDRAC firmware version
dracs list --idrac_lt 6.10.30.00  # iDRAC less than 6.10.30.00
dracs list --idrac_ge 6.10.30.00  # iDRAC greater than or equal

# Output as JSON for automation
dracs list --json

# Output only hostnames (one per line) - useful for scripting
dracs list --host-only
dracs list --model R650 --host-only

# Complex filter: R660 systems with old BIOS expiring soon
dracs list --model R660 --bios_lt 2.5.0 --expires_in 60

# Lookup specific system in list format
dracs list --svctag ABC1234
dracs list --target server01.example.com

4. Lookup a Specific System

Retrieve detailed information about a single system.

# Lookup by service tag with all fields
dracs lookup --svctag ABC1234 --full

# Lookup by hostname
dracs lookup --target server01.example.com --full

# Show only BIOS version
dracs lookup --svctag ABC1234 --bios

# Show only iDRAC firmware version
dracs lookup -s ABC1234 --idrac

# Using alias
dracs l -t server01.example.com --full

5. Edit a System

Update specific fields in the database by re-polling hardware or changing model.

# Update both BIOS and iDRAC versions from SNMP
dracs edit --target server01.example.com --bios --idrac

# Update by service tag
dracs edit --svctag ABC1234 --bios --idrac

# Update only BIOS version
dracs edit -t server01 --bios

# Update only iDRAC firmware version
dracs edit -s ABC1234 --idrac

# Change model name
dracs edit -s ABC1234 --model R650

# Using alias with verbose output
dracs -v e -t server01 --bios --idrac

6. Refresh System Data

Refresh both SNMP data (BIOS/iDRAC versions) AND warranty information from Dell API. This is useful when service contracts are renewed or firmware is updated.

# Refresh by service tag
dracs refresh --svctag ABC1234

# Refresh by hostname
dracs refresh --target server01.example.com

# Using alias with verbose output to see progress
dracs -v rf -s ABC1234

# With debug output
dracs -d refresh -t server01

7. Remove a System

Delete a system from the database.

# Remove by service tag
dracs remove --svctag ABC1234

# Remove by hostname
dracs remove --target server01.example.com

# Using alias
dracs r -s ABC1234

Common Usage Patterns

# Initial setup: Add all your systems
dracs -v add -s ABC1234 -t server01.example.com -m R660
dracs -v add -s DEF5678 -t server02.example.com -m R650
dracs -v add -s GHI9012 -t server03.example.com -m R660

# Or discover and add systems automatically
dracs -v discover -t server04.example.com --add
dracs -v d -t server05.example.com --add

# Discover a system but confirm before adding
dracs discover -t server06.example.com

# Check what's expiring soon
dracs list --expires_in 30

# Check what has already expired
dracs list --expired

# Find systems that need firmware updates
dracs list --idrac_lt 6.10.30.00

# After updating firmware, refresh the data
dracs -v refresh -t server01.example.com

# After renewing support contracts, refresh warranty
dracs -v refresh -s ABC1234

# Generate JSON report for external tools
dracs list --json > inventory.json

# Get list of all hostnames for scripting (e.g., to feed to xargs or a loop)
dracs list --host-only > hostnames.txt
for host in $(dracs list --model R650 --host-only); do echo "Processing $host"; done

# Find all R660 models
dracs list --model R660

# Detailed troubleshooting with debug output
dracs -d add -s ABC1234 -t server01 -m R660

⚙️ Command Reference

Global Arguments (apply to all commands)

Argument	Description
-h, --help	Show help message and exit
-d, --debug	Enable debug mode (most detailed output, includes SQL queries)
-v, --verbose	Enable verbose output (shows INFO level progress messages)
-w, --warranty	Path to a custom SQLite database file (defaults to warranty.db)

Command Aliases

Full Command	Alias	Required Arguments	Optional Arguments
add	a	-s/--svctag -t/--target -m/--model	None
discover	d	-t/--target	--add
edit	e	-s/--svctag OR -t/--target	--bios --idrac --model
init	i	None	None
lookup	l	-s/--svctag OR -t/--target	--full --bios --idrac
list	li	None	--model --regex --expires_in --expired --svctag --target --bios_* --idrac_* --json --host-only
refresh	rf	-s/--svctag OR -t/--target	None
remove	r	-s/--svctag OR -t/--target	None

Filter Options for list Command

BIOS Version Filters:

• --bios_lt VERSION - BIOS less than VERSION
• --bios_le VERSION - BIOS less than or equal to VERSION
• --bios_gt VERSION - BIOS greater than VERSION
• --bios_ge VERSION - BIOS greater than or equal to VERSION
• --bios_eq VERSION - BIOS equal to VERSION

iDRAC Firmware Filters:

• --idrac_lt VERSION - iDRAC less than VERSION
• --idrac_le VERSION - iDRAC less than or equal to VERSION
• --idrac_gt VERSION - iDRAC greater than or equal to VERSION
• --idrac_ge VERSION - iDRAC greater than VERSION
• --idrac_eq VERSION - iDRAC equal to VERSION

Other Filters:

• --model MODEL - Filter by server model (e.g., R650, R660)
• --regex PATTERN - Filter hostname by SQL LIKE pattern
• --expires_in DAYS - Systems with warranty expiring in N days (excludes already expired systems)
• --expired - Systems with warranties that have already expired

Output Options:

• --json - Output results as JSON instead of table
• --host-only - Output only hostnames, one per line (useful for scripting)

📡 Firmware Image Setup

The DRACS web interface can push iDRAC firmware updates to systems via HTTP. Firmware images are served by nginx from /var/lib/dracs/web/firmware/ on the DRACS host. No external FTP server is required.

• Download the desired iDRAC firmware from Dell support, e.g. iDRAC-with-Lifecycle-Controller_Firmware_924YT_WN64_7.30.10.50_A00.EXE

• Extract the firmware .EXE file using unzip to view its contents:

  unzip iDRAC-with-Lifecycle-Controller_Firmware_924YT_WN64_7.30.10.50_A00.EXE -d firmware_extracted
  

• Locate the firmware payload file inside the extracted directory at payload/firmimgFIT.d9

• Copy the firmimgFIT.d9 file to the DRACS firmware directory, renaming it to match the <MODEL>-<VERSION>.d9 convention:

  cp firmware_extracted/payload/firmimgFIT.d9 /var/lib/dracs/web/firmware/R660-7.30.10.50.d9
  chmod 444 /var/lib/dracs/web/firmware/R660-7.30.10.50.d9
  

• To make the new firmware version available for a model within DRACS, it must first be manually installed on at least one system using racadm. SSH to the iDRAC and issue the update command:

  ssh [e-mail]
  racadm update -f R660-7.30.10.50.d9 -l http://dracs.example.com/firmware/
  

• Once the manual update is complete, refresh that system in DRACS (dracs refresh -t host01.example.com). The new firmware version will then appear as available for all systems of the same model type in the DRACS web interface.

💾 BIOS Image Setup

The DRACS web interface can push BIOS updates to systems via HTTP. BIOS images are served by nginx from /var/lib/dracs/web/bios/ on the DRACS host. No external NFS server is required.

• Download the desired Dell BIOS image from Dell support, e.g. BIOS_G93PH_WN64_2.10.1.EXE

• Copy the image to the DRACS BIOS directory:

  cp BIOS_G93PH_WN64_2.10.1.EXE /var/lib/dracs/web/bios/
  chmod 444 /var/lib/dracs/web/bios/BIOS_G93PH_WN64_2.10.1.EXE
  

• To make the new BIOS version available for a model within DRACS, it must first be manually installed on at least one system using racadm. SSH to the iDRAC and issue the update command:

  ssh [e-mail]
  racadm update -f BIOS_G93PH_WN64_2.10.1.EXE -l http://dracs.example.com/bios/
  

• Connect to the console of the system and reboot to ensure the BIOS update completes.

• After the BIOS is updated, refresh the host in DRACS (dracs refresh -t host01.example.com). The new BIOS version will then appear as available for all systems of the same model type in the DRACS web interface.

Custom Image Server Configuration

By default, DRACS tells iDRACs to download firmware and BIOS images from the DRACS host itself using its FQDN (e.g. http://dracs.example.com/firmware/). If you need to serve images from a different server or URL path, the following optional environment variables can be set in your .env file:

Variable	Default	Description
DRACS_FIRMWARE_SERVER	System FQDN	Hostname or IP of the server serving firmware images
DRACS_FIRMWARE_URI	/firmware/	URI path to the firmware images on the server
DRACS_BIOS_SERVER	System FQDN	Hostname or IP of the server serving BIOS images
DRACS_BIOS_URI	/bios/	URI path to the BIOS images on the server

The resulting URL sent to iDRAC is constructed as http://<SERVER><URI>. For example, to serve images from a dedicated host:

DRACS_FIRMWARE_SERVER=images.example.com
DRACS_FIRMWARE_URI=/dell/firmware/
DRACS_BIOS_SERVER=images.example.com
DRACS_BIOS_URI=/dell/bios/

This would produce racadm update -f R660-7.30.10.50.d9 -l http://images.example.com/dell/firmware/ for firmware updates.

🌐 Web Proxy (nginx)

DRACS binds to 127.0.0.1:1888 by default, meaning it only accepts connections from localhost. For production deployments, use a reverse proxy such as nginx to handle TLS termination and expose the web interface to clients.

Sample nginx configuration files are provided in the nginx/ directory:

• dracs.conf.example — Redirects HTTP (port 80) to HTTPS
• dracs_ssl.conf.example — HTTPS reverse proxy to the DRACS backend on 127.0.0.1:1888

To use them:

cp nginx/dracs.conf.example /etc/nginx/conf.d/dracs.conf
cp nginx/dracs_ssl.conf.example /etc/nginx/conf.d/dracs_ssl.conf

Edit both files to replace dracs.example.com with your actual hostname and update the ssl_certificate / ssl_certificate_key paths to point to your TLS certificate and key. Then reload nginx:

nginx -t && systemctl reload nginx

📝 Tips & Troubleshooting

Using Verbose Output: Always use -v when running commands interactively to see progress:

dracs -v add -s ABC1234 -t server01 -m R660

SNMP Connectivity:

• Ensure the iDRAC interface is reachable using the DNS naming configured in DRACS_DNS_STRING and DRACS_DNS_MODE
• Default SNMP community is public (configure via SNMP_COMMUNITY env var)
• Port 161 must be accessible

Dell API Issues:

• Verify credentials in .env file
• Check service tag is valid (5-7 alphanumeric characters)
• Ensure system has an active Dell warranty/support contract

Database Location:

• Default: warranty.db in the current working directory
• Custom: Use -w /path/to/custom.db flag
• The database is created automatically on first use

Debug Mode: Use -d flag to see detailed debugging including:

• SQL queries and parameters
• SNMP OID requests and responses
• Dell API request/response details
• Internal data structures

dracs -d add -s ABC1234 -t server01 -m R660