NAME¶

ansible-cmdb - generate host overview from ansible facts

SYNOPSIS¶

ansible-cmdb [options] fact_dir [fact_dir]

DESCRIPTION¶

ansible-cmdb parses facts about machines gathered by Ansible and generates host overviews or other information based on those facts. It includes the ability to parse variables, groups and other information from Ansible's hosts inventory and dynamic inventories.

Output is rendered using templates. At the moment there are various templates available. You can create your own templates to completely customize ansible-cmdb's output.

OPTIONS¶

Ansible-cmdb supports the following options:

EXAMPLES¶

First, generate Ansible output for your hosts:

mkdir out \
ansible -m setup --tree out/ all

To generate a host overview with the default template (html_fancy):

ansible-cmdb out/ > overview.html

To make ansible-cmdb scan your hosts file, which will include group information and variables in the host overview:

ansible-cmdb -i /path/to/hosts out/ > overview.html

To select a different template, use the -t switch. The default template is html_fancy. If you want to use the txt_table template:

ansible-cmdb -t txt_table out/ > overview.html

If you want to refer to a template at some other location on your disk, you need to leave the .tpl extension of:

ansible-cmdb -t /home/test/some_template out/ > overview.html

To send parameters to a template, use the -p swtich. For example: to use local Javascript resources with the html_fancy template (so you can it offline):

ansible-cmdb -p local_js=1 -i /path/to/hosts out/ > overview.html

The ---columns (-c ) switch lets you specify which columns should appear in the overview. This must be supported by the template.

ansible-cmdb --columns name,os,ip,mem,cpus out/ > overview.html

You can specify multiple fact directories. You could, for example, include hosts that aren't scanned by ansible by manually creating JSON files, or add additional facts or variables to systems that are also present in the normal facts dir.

ansible-cmdb out/ manual_facts/ > overview.html

INVENTORY SCANNING¶

Ansible-cmdb can read your inventory file (hosts, by default), inventory directory or dynamic inventory and extract useful information from it such as:

Groups

All the groups a host belongs to.

Host variables

These are optional key/value pairs for each host which can be used in playbooks. They are scanned by ansible-cmdb and get added to a hosts discovered facts under the 'hostvars' section.

Reading the inventory is done using the -i switch to ansible-cmdb. It takes a single parameter: your hosts file, directory containing your hosts files or path to your dynamic inventory script.

See http://docs.ansible.com/intro_inventory.html#host-variables for more information on host variables.

TEMPLATES¶

Ansible-cmdb supports multiple different templates. You can choose which template to use with the -t switch

FACT CACHING¶

Ansible can cache facts from hosts when running playbooks. This is configured in Ansible like:

[defaults]
fact_caching=jsonfile
fact_caching_connection = /path/to/facts/dir

You can use these cached facts as facts directories with ansible-cmdb by specifying the -f (--fact-cache) option:

$ ansible-cmdb -f /path/to/facts/dir > overview.html

Please note that the --fact-cache option will apply to all fact directories you specify. This means you can't mix fact-cache fact directories and normal setup fact directories. Also, if you wish to manually extend facts (see the Extending chapter), you must omit the ansible_facts key and put items in the root of the JSON.

COLUMNS¶

Some templates, such as txt_table and html_fancy, support columns. If a template supports columns, you can use the --columns / -c command line option to specify which columns to show.

The --columns takes a comma-separated list of columns (no spaces!) which should be shown. The columns must be specified by their id field. For information on what id fields are supported by a template, take a look in the template. Usually it's the column title, but in lowercase and with spaces replaced by underscores.

You can add custom columns with the -C (--cust-cols) option. Please see the online user manual for more information.

EXTENDING¶

You can specify multiple directories that need to be scanned for output. This lets you add more custom information to existing hosts or even completely new hosts.

For example, you could create a directory called out_cust and put manually crafted JSON files in it:

$ mkdir out_cust
$ cat out_cust/test.megacorp.com
{


  "software": [


    "Apache2",


    "MySQL5.5"


  ]
}

Specify both directories when generating the output:

$ ansible-cmdb out/ out_cust/ > overview.html

our custom variables will be put in the root of the host information dictionary:

"test.megacorp.com": {


  "ansible_facts": {


    "ansible_all_ipv4_addresses": ["185.21.189.140"],


  },


  "changed": false,


  "groups": ["cust.flusso"],


  "software": [


    "Apache2",


    "MySQL5.5"


  ],


  "name": "ad6.flusso.nl"
}

If you're using the --fact-cache option, you must omit the ansible_facts key and put items in the root of the JSON. This also means that you can only extend native ansible facts and not information read from the hosts file by ansible-cmdb.

SEE ALSO¶

README.md, the main source of documentation

COPYRIGHT¶

ansible-cmdb is copyright 2015 by Ferry Boender

Ferry Boneder ferry.boender@gmail.com