Skip to main content

​
Quick Start Guide

This guide will walk you through generating your first Configuration Management Database using ansible-cmdb.

​
Prerequisites

Before you begin, ensure you have:
  • Ansible installed on your system
  • ansible-cmdb installed (see Installation)
  • SSH access to your hosts
  • Ansible inventory configured

​
Basic Workflow

1

Gather facts from your hosts

First, use Ansible to gather facts from all your hosts. This creates JSON files containing system information for each host.Create an output directory and gather facts:
mkdir out
ansible -m setup --tree out/ all
The -m setup module gathers facts from hosts, and --tree out/ saves each host’s facts to a separate file in the out/ directory. The all parameter targets all hosts in your inventory.
After running this command, you should see files like:
out/
├── host1.example.com
├── host2.example.com
└── host3.example.com
2

Generate the CMDB overview

Run ansible-cmdb on the facts directory to generate an HTML overview:
ansible-cmdb out/ > overview.html
This uses the default html_fancy template to create a dynamic, searchable HTML page.
3

View the results

Open the generated HTML file in your browser:
# Linux
xdg-open overview.html

# macOS
open overview.html

# Windows
start overview.html
You’ll see a searchable table with all your hosts, including:
  • Hostname and FQDN
  • Operating system and version
  • IP addresses
  • Memory and CPU information
  • And much more!
By default, ansible-cmdb uses the html_fancy template which provides an interactive, sortable table view with detailed host information.

​
Complete Working Example

Here’s a complete example showing the entire process: 
# Step 1: Create output directory
mkdir out

# Step 2: Gather facts from all hosts
ansible -m setup --tree out/ all

# Step 3: Generate HTML overview
ansible-cmdb out/ > overview.html

# Step 4: Open in browser
xdg-open overview.html

​
Using Inventory Files

To include host and group variables from your inventory, use the -i option: 
ansible-cmdb -i ./hosts out/ > overview.html
This will automatically include:
  • All groups a host belongs to
  • Host variables defined in the inventory
  • Variables from host_vars/ and group_vars/ directories

​
Example Inventory with Variables

hosts
[cust.megacorp]
db1.dev.megacorp.com   dtap=dev  comment="Old database server"
db2.dev.megacorp.com   dtap=dev  comment="New database server"
test.megacorp.com      dtap=test
acc.megacorp.com       dtap=acc  comment="24/7 support"
megacorp.com           dtap=prod comment="Hosting by Foo" ext_id="SRV_10029"

[os.redhat]
megacorp.com
acc.megacorp.com
test.megacorp.com
db2.dev.megacorp.com

[os.debian]
db1.dev.megacorp.com
Generate CMDB with this inventory: 
ansible-cmdb -i hosts out/ > overview.html
The html_fancy template supports special variables:
  • dtap - Environment type (development/test/acceptance/production)
  • comment - Host comment
  • ext_id - External identifier
  • groups - List of groups (automatically populated)

​
Template Options

​
HTML Fancy Parameters

Customize the HTML output with template parameters: 
# Use local JavaScript libraries instead of CDN
ansible-cmdb -t html_fancy -p local_js=1 out/ > overview.html

​
Selecting Columns

Show only specific columns in the output: 
ansible-cmdb -t txt_table --columns name,os,ip,mem,cpus out/
Example output: 
Name                    OS             IP             Mem  CPUs
----------------------  -------------  -------------  ---  ----
web01.example.com       Ubuntu 20.04   192.168.1.10   8g   4
db01.example.com        Debian 11      192.168.1.20   16g  8
app01.example.com       CentOS 8       192.168.1.30   4g   2
Exclude specific columns: 
ansible-cmdb -t html_fancy --exclude-cols mem_usage,swap_usage,disk_usage out/ > overview.html

​
Limiting Hosts

Generate output for specific hosts or groups: 
# Include only hosts in the 'webservers' group
ansible-cmdb -i hosts -l 'webservers' out/ > cmdb.html
Host limiting requires the -i inventory parameter to work. Wildcards (e.g., db*.example.com) and host expansions (e.g., db[0-3].example.com) are not currently supported.

​
Using Fact Cache

If you’re using Ansible’s fact caching feature, you can use those cached facts directly: 
ansible-cmdb -f /path/to/facts/cache > overview.html

​
Configure Ansible Fact Caching

Add to your ansible.cfg:
ansible.cfg
[defaults]
fact_caching=jsonfile
fact_caching_connection = /var/cache/ansible/facts
Then use with ansible-cmdb: 
ansible-cmdb -f /var/cache/ansible/facts > overview.html
The --fact-cache option applies to all fact directories you specify. You cannot mix fact-cache directories with normal setup directories.

​
Advanced: SQL Export

Generate SQL output for importing into a database:
1

Generate SQL file

ansible-cmdb -t sql -i hosts out/ > cmdb.sql
2

Create database

echo "CREATE DATABASE ansiblecmdb" | mysql
3

Import data

mysql ansiblecmdb < cmdb.sql

​
Advanced: Split Output

For large numbers of hosts, use the split template for better performance: 
ansible-cmdb -t html_fancy_split -i hosts out/
This creates a cmdb/ directory with:
  • index.html - Main overview page
  • Separate HTML files for each host’s details
The split template is ideal for environments with 50+ hosts, as it improves browser rendering performance.

​
Troubleshooting

​
No facts gathered

If ansible-cmdb shows no hosts, verify your facts were gathered correctly: 
ls -la out/
You should see files named after your hosts. If not, check your Ansible inventory and SSH connectivity.

​
Python interpreter issues

If you get Python-related errors, you can manually specify the Python interpreter: 
/usr/bin/python3 /usr/local/bin/ansible-cmdb.py out/ > overview.html

​
Template not found

Verify available templates: 
ansible-cmdb --help
Common templates:
  • html_fancy (default)
  • html_fancy_split
  • csv
  • json
  • markdown
  • sql
  • txt_table

​
Next Steps

Custom Columns

Learn how to add custom columns with JSONPath expressions

Extending Facts

Override and extend facts with custom data

Custom Templates

Create your own templates using Mako

Host Variables

Use special variables like dtap, comment, and ext_id

Build docs developers (and LLMs) love

Get started for freeTalk to us