dracs 1.7.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 with uv:

uv sync

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

uv sync --group dev

Source the virtual environment

source .venv/bin/activate

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
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)

📡 FTP Server Setup for Firmware Updates

The DRACS web interface can push iDRAC firmware updates to systems via an anonymous FTP server. Follow these steps to set up the FTP server and make firmware available.

• Set up an anonymous FTP server (e.g. vsftpd) as a service. This can run on the same host as DRACS. Ensure the DRACS_FTP_SERVER variable in your .env file points to the FTP server's IP address.

• 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 FTP server's public directory, renaming it to match the <MODEL>-<VERSION>.d9 convention:

  cp firmware_extracted/payload/firmimgFIT.d9 /var/ftp/pub/R660-7.30.10.50.d9
  chmod 444 /var/ftp/pub/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 fwupdate -f <FTP_SERVER_IP> ftp user -d pub/R660-7.30.10.50.d9
  

• 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.

💾 NFS Server Setup for BIOS Updates

The DRACS web interface can push BIOS updates to systems via an NFS server. Follow these steps to set up the NFS server and make BIOS images available.

• Set up an NFS server in your environment. This can be the DRACS host, an existing host, or any other host in your deployment. The NFS share must be accessible for read access from all iDRAC interfaces in your environment.

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

• Place the image on your NFS server under a model-specific subdirectory:

  cp BIOS_G93PH_WN64_2.10.1.EXE /path/to/nfs/R660/
  

• Ensure your .env file includes both NFS variables:

  DRACS_NFS_SERVER=192.168.1.100
  DRACS_NFS_PATH=/path/to/nfs
  

• 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 192.168.1.100:/srv/nfs/dell_bios/R660
  

• 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.

🌐 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