# salt.modules.textfsm_mod

## TextFSM

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