Skip to content

Device Inventory Search

In version 6.9.0 of the ipfabric Python SDK a new ipf_device_search CLI tool was added which searches the Inventory > Devices table. After installing the package it can be run from the command line.

Requirements

Required environment variables exported (IPF_URL and IPF_TOKEN or IPF_USERNAME & IPF_PASSWORD) or a .env file located in the current working directory or your home directory.

Requires rich to be installed (pip install rich or pip install ipfabric[cli]).

Documentation

IPF Device Search Help
# ipf_device_search -h
usage: ipf_device_search [-h] [-o OPERATOR] [-C] [-a ADD_COLUMNS] [-r REMOVE_COLUMNS] [-A] [-B BOX_STYLE] [-s SNAPSHOT] [-b BASE_URL] [-t TOKEN] [-u USERNAME] [-p PASSWORD] [-c] [-v] [-j] [-R]
                         search [search ...]

Search the Inventory > Device table and return the results.

positional arguments:
  search                Search value: 'ipf_device_search rtr1'. Default uses 'hostname' for search. Example for different column: 'ipf_device_search vendor cisco'.

optional arguments:
  -h, --help            show this help message and exit
  -o OPERATOR, --operator OPERATOR
                        Operator used in searching; default is 'like'.
  -C, --csv             Export to CSV format.
  -a ADD_COLUMNS, --add-columns ADD_COLUMNS
                        Comma separated list of column names to add to output.
  -r REMOVE_COLUMNS, --remove-columns REMOVE_COLUMNS
                        Comma separated list of column names to remove from output.
  -A, --attribute       Do a Device Attribute search (operator chosen is applied to both name and value): 'ipf_device_search -A attribute_name attribute_value'.
  -B BOX_STYLE, --box-style BOX_STYLE
                        Table box style (see https://rich.readthedocs.io/en/stable/appendix/box.html#appendix-box for options).
  -s SNAPSHOT, --snapshot SNAPSHOT
                        Snapshot to use which can be a UUID or one of ['last', 'prev', 'lastLocked']with or without `$` for *nix compatability.
  -b BASE_URL, --base-url BASE_URL
                        Base URL for IPFabric API or IPF_URL env variable.
  -t TOKEN, --token TOKEN
                        IP Fabric API Token or IPF_TOKEN env variable.
  -u USERNAME, --username USERNAME
                        IP Fabric username (requires --password) or IPF_USERNAME env variable.
  -p PASSWORD, --password PASSWORD
                        IP Fabric password or IPF_PASSWORD env variable.
  -c, --count           Print count of rows instead of the actual data.
  -v, --verbose         Verbose output will enable debugging and print all tables even if no data.
  -j, --json            Enable JSON output which will also print all tables even if no data.
  -R, --rich-disable    Disable rich formatting if installed. Useful for sending JSON output to jq.
Valid column names for searching, '-a|--add-columns', or '-r|--add-columns' arguments.
[
  "uptime (float)",
  "model (str)",
  "reload (str)",
  "image (str)",
  "domain (str)",
  "platform (str)",
  "slug (str)",
  "hostname (str)",
  "fqdn (str)",
  "processor (str)",
  "sn (str)",
  "version (str)",
  "vendor (str)",
  "family (str)",
  "stpDomain|stp_domain (str)",
  "hostnameOriginal|hostname_original (str)",
  "loginIp|login_ip (str)",
  "snHw|sn_hw (str)",
  "memoryTotalBytes|mem_total_bytes (float)",
  "hostnameProcessed|hostname_processed (str)",
  "siteName|site (str)",
  "devType|dev_type (str)",
  "tsDiscoveryEnd|ts_discovery_end (float)",
  "configReg|config_reg (str)",
  "rd|routing_domain (str)",
  "memoryUsedBytes|mem_used_bytes (float)",
  "memoryUtilization|mem_utilization (float)",
  "secDiscoveryDuration|sec_discovery_duration (float)",
  "loginType|login_type (str)",
  "tsDiscoveryStart|ts_discovery_start (float)",
  "loginPort|login_port (int)",
  "objectId|object_id (str)",
  "taskKey|task_key (str)"
]
Valid operators (specify either the key '=' or the value 'eq').
{
  "string": {
    "=": "eq",
    "!=": "neq",
    "i=": "ieq",
    "i!=": "nieq",
    "~": "like",
    "!": "notlike",
    "=~": "reg",
    "!=~": "nreg",
    "i=~": "ireg",
    "i!=~": "nireg"
  },
  "numeric": {
    "=": "eq",
    "!=": "neq",
    ">": "gt",
    ">=": "gte",
    "<": "lt",
    "<=": "lte"
  }
}

For Windows you may be required to escape special characters (& \ < > ^ |) using a caret ^ ("^(10.0.0.1|192.168.0.1)$" becomes "^^(10.0.0.1^|192.168.0.1)$").

Usage

Find devices with hostname like 'L71EXR2'.
# ipf_device_search l71exR2 
                                               Device Inventory                                               

| hostname | siteName | vendor | family | platform    | model | version  | loginIp       | snHw    | devType |
|----------|----------|--------|--------|-------------|-------|----------|---------------|---------|---------|
| L71EXR2  | L71      | cisco  | ios    | i86bi_linux |       | 15.5(2)T | 10.71.103.102 | a47ff66 | router  |

                                  Filter: {"hostname": ["like", "l71exR2"]}
https://demo1.us.ipfabric.io/inventory/devices?options=%7B%22filters%22%3A%7B%22hostname%22%3A%5B%22like%22%2C%22l71exR2%22%5D%7D%7D
Find devices in site '35PRODUCTION'.
# ipf_device_search -o eq site 35PRODUCTION
                                                                Device Inventory                                                                
| siteName     | hostname | vendor | family | platform      | model | version                             | loginIp       | snHw    | devType  |
|--------------|----------|--------|--------|---------------|-------|-------------------------------------|---------------|---------|----------|
| 35PRODUCTION | L35EXR14 | cisco  | ios    | i86bi_linux   |       | 15.5(2)T                            | 10.35.255.114 | a23ff72 | router   |
| 35PRODUCTION | L35AC172 | cisco  | ios    | i86bi_linuxl2 |       | 15.2(20170809:194209)               | 10.35.179.186 | a23ffba | switch   |
| 35PRODUCTION | L35EXR13 | cisco  | ios    | i86bi_linux   |       | 15.5(2)T                            | 10.35.255.113 | a23ff71 | router   |
| 35PRODUCTION | L35SD176 | cisco  | ios    | i86bi_linuxl2 |       | 15.2(CML_NIGHTLY_20150703)FLO_DSGS7 | 10.35.255.168 | a23ffa8 | l3switch |

                                                  Filter: {"siteName": ["eq", "35PRODUCTION"]}
https://sa-integrations02a.ash-cloud.ipf.cx/inventory/devices?options=%7B%22filters%22%3A%7B%22siteName%22%3A%5B%22eq%22%2C%2235PRODUCTION%22%5D%7D%7D
Find devices with uptime less than 1 day, 3 hours, 5 minutes.
# ipf_device_search -o "<" uptime "1 day, 3 hours, and 5 minutes"
                                                 Device Inventory                                                  
| uptime | hostname | siteName | vendor | family | platform    | model | version  | loginIp   | snHw    | devType |
|--------|----------|----------|--------|--------|-------------|-------|----------|-----------|---------|---------|
| 1980   | NL8-R1   | unknown  | cisco  | ios    | i86bi_linux |       | 15.5(2)T | 10.1.1.12 | a01010c | router  |

                                         Filter: {"uptime": ["lt", 97500]}
https://sa-integrations02a.ash-cloud.ipf.cx/inventory/devices?options=%7B%22filters%22%3A%7B%22uptime%22%3A%5B%22lt%22%2C97500%5D%7D%7D

Attribute Searching

Specified Operator is applied to both the Attribute Name and Value during searches.

Search for devices with case insensitive regex matching Device Attribute named 'mgmt_ip|test' and with case insensitive regex matching value of '10.72.255.16|TEST|foobar'.
# ipf_device_search -A -o ireg "mgmt_ip|test" "10.72.255.16|TEST|foobar" -r version,model,platform
                                                                                           Device Inventory                                                                                            
| attributes                        | hostname                    | siteName     | vendor   | family    | loginIp       | snHw             | devType |
|-----------------------------------|-----------------------------|--------------|----------|-----------|---------------|------------------|---------|
| MGMT_IP=10.72.255.162             | L72AC11                     | L72          | cisco    | ios       | 10.72.129.162 | a48ffa2          | switch  |
| MGMT_IP=10.72.255.161             | L72AC24                     | L72          | cisco    | ios       | 10.72.119.161 | a48ffa1          | switch  |
| MGMT_IP=foobar,TEST=test_some_vrf | L35FW1                      | 35HEADOFFICE | cisco    | asa       | 10.35.253.43  | 9AMSST2E75V      | fw      |
| MGMT_IP=10.72.255.163             | L72AC12                     | L72          | cisco    | ios       | 10.72.129.163 | a48ffa3          | switch  |
| TEST=TEST                         | L71FW5_hasAVeryLongHostname | L71          | fortinet | fortigate | 10.71.109.105 | FOSVM1QWZRUM4EB7 | fw      |

Filtered URLs do not support Attributes so no link is provided.

Formatting

Modifying Columns

Find all devices with a version matching case insensitive regex of '6\.0\.\d*,BUILD' adding 'reload' column and removing 'devType' column.
# ipf_device_search -o ireg version "6\.0\.\d*,BUILD" -a reload -r devType 
                                                                Device Inventory                                                                
| version         | hostname              | siteName | vendor   | family    | platform     | model | loginIp       | snHw             | reload |
|-----------------|-----------------------|----------|----------|-----------|--------------|-------|---------------|------------------|--------|
| 6.0.5,build0268 | L71FW9/root           | L71      | fortinet | fortigate | fortigate-vm |       | 10.71.111.110 | FOSVM1HHJXBISQD7 | None   |
| 6.0.4,build0231 | L71FW13-HA1/root      | L71      | fortinet | fortigate | fortigate-vm |       | 10.71.106.115 | FOSVM1_ELPNYXP69 | None   |
| 6.0.5,build0268 | L71FW9/ipf            | L71      | fortinet | fortigate | fortigate-vm |       | 10.71.255.110 | FOSVM1HHJXBISQD7 | None   |
| 6.0.4,build0231 | L71FW13-HA1/mrjohnson | L71      | fortinet | fortigate | fortigate-vm |       | 10.71.106.115 | FOSVM1_ELPNYXP69 | None   |

                                              Filter: {"version": ["ireg", "6\\.0\\.\\d*,BUILD"]}
https://sa-integrations02a.ash-cloud.ipf.cx/inventory/devices?options=%7B%22filters%22%3A%7B%22version%22%3A%5B%22ireg%22%2C%226%5C%5C.0%5C%5C.%5C%5Cd%2A%2CBUILD%22%5D%7D%7D

JSON Output

If using JSON output disable rich with the -R|--rich-disable flag prior to sending to jq.

Find devices with hostname like 'l71exR2' and return unformatted JSON piping to 'jq'.
# ipf_device_search l71exR2 -j -R | jq .
[
  {
    "hostname": "L71EXR2",
    "siteName": "L71",
    "vendor": "cisco",
    "family": "ios",
    "platform": "i86bi_linux",
    "model": "",
    "version": "15.5(2)T",
    "loginIp": "10.71.103.102",
    "snHw": "a47ff66",
    "devType": "router"
  }
]

CSV Output

Find devices with hostname like 'l71exR2' and return CSV format.
# ipf_device_search l71exR2 -C
"Hostname","Site","Vendor","Family","Platform","Model","Version","Login IP","Serial Number","Type"
"L71EXR2","L71","cisco","ios","i86bi_linux","","15.5(2)T","10.71.103.102","a47ff66","router"