salt.modules.textfsm_mod

TextFSM

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

depends:
  • textfsm Python library

Note

Install textfsm library: pip install textfsm.

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.

template_path

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://

raw_text: None

The unstructured text to be parsed.

raw_text_file: 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.

saltenv: base

Salt fileserver environment 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.

command

The command executed on the device, to get the output.

platform

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.

platform_grain_name

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_column_name: 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.

output

The raw output from the device, to be parsed and extract the structured data.

output_file

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://.

textfsm_path

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_file: 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.

saltenv: base

Salt fileserver environment from which to retrieve the file. Ignored if textfsm_path is not a salt:// URL.

include_empty: False

Include empty files under the textfsm_path.

include_pat

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.

exclude_pat

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