New in version 2018.3.0.
Execution module that processes plain text and extracts data using TextFSM templates. The output is presented in JSON serializable data, and can be easily re-used in other modules, or directly inside the renderer (Jinja, Mako, Genshi, etc.).
textfsm Python library
Note
For Python 2/3 compatibility, it is more recommended to
install the jtextfsm
library: pip install jtextfsm
.
salt.modules.textfsm_mod.
extract
(template_path, raw_text=None, raw_text_file=None, saltenv='base')¶Extracts the data entities from the unstructured raw text sent as input and returns the data mapping, processing using the TextFSM template.
The path to the TextFSM template. This can be specified using the absolute path to the file, or using one of the following URL schemes:
salt://
, to fetch the template from the Salt fileserver.
http://
or https://
ftp://
s3://
swift://
None
The unstructured text to be parsed.
None
Text file to read, having the raw text to be parsed using the TextFSM template.
Supports the same URL schemes as the template_path
argument.
base
Salt fileserver envrionment from which to retrieve the file.
Ignored if template_path
is not a salt://
URL.
CLI Example:
salt '*' textfsm.extract salt://textfsm/juniper_version_template raw_text_file=s3://junos_ver.txt
salt '*' textfsm.extract http://some-server/textfsm/juniper_version_template raw_text='Hostname: router.abc ... snip ...'
Jinja template example:
{%- set raw_text = 'Hostname: router.abc ... snip ...' -%}
{%- set textfsm_extract = salt.textfsm.extract('https://some-server/textfsm/juniper_version_template', raw_text) -%}
Raw text example:
Hostname: router.abc
Model: mx960
JUNOS Base OS boot [9.1S3.5]
JUNOS Base OS Software Suite [9.1S3.5]
JUNOS Kernel Software Suite [9.1S3.5]
JUNOS Crypto Software Suite [9.1S3.5]
JUNOS Packet Forwarding Engine Support (M/T Common) [9.1S3.5]
JUNOS Packet Forwarding Engine Support (MX Common) [9.1S3.5]
JUNOS Online Documentation [9.1S3.5]
JUNOS Routing Software Suite [9.1S3.5]
TextFSM Example:
Value Chassis (\S+)
Value Required Model (\S+)
Value Boot (.*)
Value Base (.*)
Value Kernel (.*)
Value Crypto (.*)
Value Documentation (.*)
Value Routing (.*)
Start
# Support multiple chassis systems.
^\S+:$$ -> Continue.Record
^${Chassis}:$$
^Model: ${Model}
^JUNOS Base OS boot \[${Boot}\]
^JUNOS Software Release \[${Base}\]
^JUNOS Base OS Software Suite \[${Base}\]
^JUNOS Kernel Software Suite \[${Kernel}\]
^JUNOS Crypto Software Suite \[${Crypto}\]
^JUNOS Online Documentation \[${Documentation}\]
^JUNOS Routing Software Suite \[${Routing}\]
Output example:
{
"comment": "",
"result": true,
"out": [
{
"kernel": "9.1S3.5",
"documentation": "9.1S3.5",
"boot": "9.1S3.5",
"crypto": "9.1S3.5",
"chassis": "",
"routing": "9.1S3.5",
"base": "9.1S3.5",
"model": "mx960"
}
]
}
salt.modules.textfsm_mod.
index
(command, platform=None, platform_grain_name=None, platform_column_name=None, output=None, output_file=None, textfsm_path=None, index_file=None, saltenv='base', include_empty=False, include_pat=None, exclude_pat=None)¶Dynamically identify the template required to extract the information from the unstructured raw text.
The output has the same structure as the extract
execution
function, the difference being that index
is capable
to identify what template to use, based on the platform
details and the command
.
The command executed on the device, to get the output.
The platform name, as defined in the TextFSM index file.
Note
For ease of use, it is recommended to define the TextFSM indexfile with values that can be matches using the grains.
The name of the grain used to identify the platform name in the TextFSM index file.
Note
This option can be also specified in the minion configuration
file or pillar as textfsm_platform_grain
.
Note
This option is ignored when platform
is specified.
Platform
The column name used to identify the platform,
exactly as specified in the TextFSM index file.
Default: Platform
.
Note
This is field is case sensitive, make sure to assign the correct value to this option, exactly as defined in the index file.
Note
This option can be also specified in the minion configuration
file or pillar as textfsm_platform_column_name
.
The raw output from the device, to be parsed and extract the structured data.
The path to a file that contains the raw output from the device,
used to extract the structured data.
This option supports the usual Salt-specific schemes: file://
,
salt://
, http://
, https://
, ftp://
, s3://
, swift://
.
The path where the TextFSM templates can be found. This can be either
absolute path on the server, either specified using the following URL
schemes: file://
, salt://
, http://
, https://
, ftp://
,
s3://
, swift://
.
Note
This needs to be a directory with a flat structure, having an
index file (whose name can be specified using the index_file
option)
and a number of TextFSM templates.
Note
This option can be also specified in the minion configuration
file or pillar as textfsm_path
.
index
The name of the TextFSM index file, under the textfsm_path
. Default: index
.
Note
This option can be also specified in the minion configuration
file or pillar as textfsm_index_file
.
base
Salt fileserver envrionment from which to retrieve the file.
Ignored if textfsm_path
is not a salt://
URL.
False
Include empty files under the textfsm_path
.
Glob or regex to narrow down the files cached from the given path.
If matching with a regex, the regex must be prefixed with E@
,
otherwise the expression will be interpreted as a glob.
Glob or regex to exclude certain files from being cached from the given path.
If matching with a regex, the regex must be prefixed with E@
,
otherwise the expression will be interpreted as a glob.
Note
If used with include_pat
, files matching this pattern will be
excluded from the subset of files defined by include_pat
.
CLI Example:
salt '*' textfsm.index 'sh ver' platform=Juniper output_file=salt://textfsm/juniper_version_example textfsm_path=salt://textfsm/
salt '*' textfsm.index 'sh ver' output_file=salt://textfsm/juniper_version_example textfsm_path=ftp://textfsm/ platform_column_name=Vendor
salt '*' textfsm.index 'sh ver' output_file=salt://textfsm/juniper_version_example textfsm_path=https://some-server/textfsm/ platform_column_name=Vendor platform_grain_name=vendor
TextFSM index file example:
salt://textfsm/index
Template, Hostname, Vendor, Command
juniper_version_template, .*, Juniper, sh[[ow]] ve[[rsion]]
The usage can be simplified,
by defining (some of) the following options: textfsm_platform_grain
,
textfsm_path
, textfsm_platform_column_name
, or textfsm_index_file
,
in the (proxy) minion configuration file or pillar.
Configuration example:
textfsm_platform_grain: vendor
textfsm_path: salt://textfsm/
textfsm_platform_column_name: Vendor
And the CLI usage becomes as simple as:
salt '*' textfsm.index 'sh ver' output_file=salt://textfsm/juniper_version_example
Usgae inside a Jinja template:
{%- set command = 'sh ver' -%}
{%- set output = salt.net.cli(command) -%}
{%- set textfsm_extract = salt.textfsm.index(command, output=output) -%}