# salt.modules.grains

Return/control aspects of the grains data

Grains set or altered with this module are stored in the 'grains' file on the minions. By default, this file is located at: `/etc/salt/grains`

Note

This does NOT override any grains set in the minion config file.

salt.modules.grains.append(key, val, convert=False, delimiter=':')

  New in version 0.17.0.

  Append a value to a list in the grains config file. If the grain doesn't exist, the grain key is added and the value is appended to the new grain as a list item.

  key

    The grain key to be appended to

  val

    The value to append to the grain key

  convert

    If convert is True, convert non-list contents into a list. If convert is False and the grain contains non-list contents, an error is given. Defaults to False.

  delimiter

    The key can be a nested dict key. Use this parameter to specify the delimiter you use, instead of the default `:`. You can now append values to a list in nested dictionary grains. If the list doesn't exist at this level, it will be created.

    New in version 2014.7.6.

  CLI Example:

      salt '*' grains.append key val

salt.modules.grains.delkey(key, force=False)

  New in version 2017.7.0.

  Remove a grain completely from the grain system, this will remove the grain key and value

  key

    The grain key from which to delete the value.

  force

    Force remove the grain even when it is a mapped value. Defaults to False

  CLI Example:

      salt '*' grains.delkey key

salt.modules.grains.delval(key, destructive=False, force=False)

  New in version 0.17.0.

  Delete a grain value from the grains config file. This will just set the grain value to `None`. To completely remove the grain, run `grains.delkey` or pass `destructive=True` to `grains.delval`.

  key

    The grain key from which to delete the value.

  destructive

    Delete the key, too. Defaults to False.

  force

    Force remove the grain even when it is a mapped value. Defaults to False

  CLI Example:

      salt '*' grains.delval key

salt.modules.grains.equals(key, value)

  Used to make sure the minion's grain key/value matches.

  Returns `True` if matches otherwise `False`.

  New in version 2017.7.0.

  CLI Example:

      salt '*' grains.equals fqdn <expected_fqdn>
      salt '*' grains.equals systemd:version 219

salt.modules.grains.fetch(key, default='', delimiter=':', ordered=True)

  Attempt to retrieve the named value from grains, if the named value is not available return the passed default. The default return is an empty string.

  The value can also represent a value in a nested dict using a ":" delimiter for the dict. This means that if a dict in grains looks like this:

      {'pkg': {'apache': 'httpd'}}

  To retrieve the value associated with the apache key in the pkg dict this key can be passed:

      pkg:apache

  Parameters:

    - delimiter --

      Specify an alternate delimiter to use when traversing a nested dict. This is useful for when the desired key contains a colon. See CLI example below for usage.

      New in version 2014.7.0.

    - ordered --

      Outputs an ordered dict if applicable (default: True)

      New in version 2016.11.0.

  CLI Example:

      salt '*' grains.get pkg:apache
      salt '*' grains.get abc::def|ghi delimiter='|'

salt.modules.grains.filter_by(lookup_dict, grain='os_family', merge=None, default='default', base=None)

  New in version 0.17.0.

  Look up the given grain in a given dictionary for the current OS and return the result

  Although this may occasionally be useful at the CLI, the primary intent of this function is for use in Jinja to make short work of creating lookup tables for OS-specific data. For example:

      {% set apache = salt['grains.filter_by']({
          'Debian': {'pkg': 'apache2', 'srv': 'apache2'},
          'RedHat': {'pkg': 'httpd', 'srv': 'httpd'},
      }, default='Debian') %}

      myapache:
        pkg.installed:
          - name: {{ apache.pkg }}
        service.running:
          - name: {{ apache.srv }}

  Values in the lookup table may be overridden by values in Pillar. An example Pillar to override values in the example above could be as follows:

      apache:
        lookup:
          pkg: apache_13
          srv: apache

  The call to `filter_by()` would be modified as follows to reference those Pillar values:

      {% set apache = salt['grains.filter_by']({
          ...
      }, merge=salt['pillar.get']('apache:lookup')) %}

  Parameters:

    - lookup_dict --

      A dictionary, keyed by a grain, containing a value or values relevant to systems matching that grain. For example, a key could be the grain for an OS and the value could the name of a package on that particular OS.

      Changed in version 2016.11.0: The dictionary key could be a globbing pattern. The function will return the corresponding `lookup_dict` value where grain value matches the pattern. For example:

          # this will render 'got some salt' if Minion ID begins from 'salt'
          salt '*' grains.filter_by '{salt*: got some salt, default: salt is not here}' id

    - grain --

      The name of a grain to match with the current system's grains. For example, the value of the "os_family" grain for the current system could be used to pull values from the `lookup_dict` dictionary.

      Changed in version 2016.11.0: The grain value could be a list. The function will return the `lookup_dict` value for a first found item in the list matching one of the `lookup_dict` keys.

    - merge -- A dictionary to merge with the results of the grain selection from `lookup_dict`. This allows Pillar to override the values in the `lookup_dict`. This could be useful, for example, to override the values for non-standard package names such as when using a different Python version from the default Python version provided by the OS (e.g., `python26-mysql` instead of `python-mysql`).

    - default --

      default lookup_dict's key used if the grain does not exists or if the grain value has no match on lookup_dict. If unspecified the value is "default".

      New in version 2014.1.0.

    - base --

      A lookup_dict key to use for a base dictionary. The grain-selected `lookup_dict` is merged over this and then finally the `merge` dictionary is merged. This allows common values for each case to be collected in the base and overridden by the grain selection dictionary and the merge dictionary. Default is unset.

      New in version 2015.5.0.

  CLI Example:

      salt '*' grains.filter_by '{Debian: Debheads rule, RedHat: I love my hat}'
      # this one will render {D: {E: I, G: H}, J: K}
      salt '*' grains.filter_by '{A: B, C: {D: {E: F, G: H}}}' 'xxx' '{D: {E: I}, J: K}' 'C'
      # next one renders {A: {B: G}, D: J}
      salt '*' grains.filter_by '{default: {A: {B: C}, D: E}, F: {A: {B: G}}, H: {D: I}}' 'xxx' '{D: J}' 'F' 'default'
      # next same as above when default='H' instead of 'F' renders {A: {B: C}, D: J}

salt.modules.grains.get(key, default='', delimiter=':', ordered=True)

  Attempt to retrieve the named value from grains, if the named value is not available return the passed default. The default return is an empty string.

  The value can also represent a value in a nested dict using a ":" delimiter for the dict. This means that if a dict in grains looks like this:

      {'pkg': {'apache': 'httpd'}}

  To retrieve the value associated with the apache key in the pkg dict this key can be passed:

      pkg:apache

  Parameters:

    - delimiter --

      Specify an alternate delimiter to use when traversing a nested dict. This is useful for when the desired key contains a colon. See CLI example below for usage.

      New in version 2014.7.0.

    - ordered --

      Outputs an ordered dict if applicable (default: True)

      New in version 2016.11.0.

  CLI Example:

      salt '*' grains.get pkg:apache
      salt '*' grains.get abc::def|ghi delimiter='|'

salt.modules.grains.has_value(key)

  Determine whether a key exists in the grains dictionary.

  Given a grains dictionary that contains the following structure:

      {'pkg': {'apache': 'httpd'}}

  One would determine if the apache key in the pkg dict exists by:

      pkg:apache

  CLI Example:

      salt '*' grains.has_value pkg:apache

salt.modules.grains.item(*args, **kwargs)

  Return one or more grains

  CLI Example:

      salt '*' grains.item os
      salt '*' grains.item os osrelease oscodename

  Sanitized CLI Example:

      salt '*' grains.item host sanitize=True

salt.modules.grains.items(sanitize=False)

  Return all of the minion's grains

  CLI Example:

      salt '*' grains.items

  Sanitized CLI Example:

      salt '*' grains.items sanitize=True

salt.modules.grains.ls()

  Return a list of all available grains

  CLI Example:

      salt '*' grains.ls

salt.modules.grains.remove(key, val, delimiter=':')

  New in version 0.17.0.

  Remove a value from a list in the grains config file

  key

    The grain key to remove.

  val

    The value to remove.

  delimiter

    The key can be a nested dict key. Use this parameter to specify the delimiter you use, instead of the default `:`. You can now append values to a list in nested dictionary grains. If the list doesn't exist at this level, it will be created.

    New in version 2015.8.2.

  CLI Example:

      salt '*' grains.remove key val

salt.modules.grains.set(key, val='', force=False, destructive=False, delimiter=':')

  Set a key to an arbitrary value. It is used like setval but works with nested keys.

  This function is conservative. It will only overwrite an entry if its value and the given one are not a list or a dict. The `force` parameter is used to allow overwriting in all cases.

  New in version 2015.8.0.

  Parameters:

    - force -- Force writing over existing entry if given or existing values are list or dict. Defaults to False.

    - destructive -- If an operation results in a key being removed, delete the key, too. Defaults to False.

    - delimiter -- Specify an alternate delimiter to use when traversing a nested dict, the default being `:`

  CLI Example:

      salt '*' grains.set 'apps:myApp:port' 2209
      salt '*' grains.set 'apps:myApp' '{port: 2209}'

salt.modules.grains.setval(key, val, destructive=False, refresh_pillar=True)

  Set a grains value in the grains config file

  key

    The grain key to be set.

  val

    The value to set the grain key to.

  destructive

    If an operation results in a key being removed, delete the key, too. Defaults to False.

  refresh_pillar

    Whether pillar will be refreshed. Defaults to True.

  CLI Example:

      salt '*' grains.setval key val
      salt '*' grains.setval key "{'sub-key': 'val', 'sub-key2': 'val2'}"

salt.modules.grains.setvals(grains, destructive=False, refresh_pillar=True)

  Set new grains values in the grains config file

  destructive

    If an operation results in a key being removed, delete the key, too. Defaults to False.

  refresh_pillar

    Whether pillar will be refreshed. Defaults to True.

  CLI Example:

      salt '*' grains.setvals "{'key1': 'val1', 'key2': 'val2'}"