# salt.modules.grains

Return/control aspects of the grains data

`salt.modules.grains.` `append`(key, val)

  New in version 0.17.0.

  Append a value to a list in the grains config file

  CLI Example:

      salt '*' grains.append key val

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

  New in version 0.17.0.

  Delete a grain from the grains config file

  Parameters: | Destructive -- Delete the key, too. Defaults to False.

  CLI Example:

      salt '*' grains.delval key

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

  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': {'pkg': 'apache', 'srv': 'apache'},
      }) %}

      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. 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. merge -- A dictionary to merge with the `lookup_dict` before doing the lookup. 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. this parameter was added in version 0.17.2

  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'

`salt.modules.grains.` `get`(key, default='')

  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

  CLI Example:

      salt '*' grains.get pkg:apache

`salt.modules.grains.` `get_or_set_hash`(name, length=8, chars='abcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*(-_=+)')

  Perform a one-time generation of a hash and write it to the local grains. If that grain has already been set return the value instead.

  This is useful for generating passwords or keys that are specific to a single minion that don't need to be stored somewhere centrally.

  State Example:

      some_mysql_user:
        mysql_user:
          - present
          - host: localhost
          - password: {{ grains.get_or_set_hash('mysql:some_mysql_user') }}

  CLI Example:

      salt '*' grains.get_or_set_hash 'django:SECRET_KEY' 50

`salt.modules.grains.` `has_value`(key)

  Determine whether a named value 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)

  New in version 0.17.0.

  Remove a value from a list in the grains config file

  CLI Example:

      salt '*' grains.remove key val

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

  Set a grains value in the grains config file

  Parameters: | Destructive -- If an operation results in a key being removed, delete the key, too. Defaults to False.

  CLI Example:

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

Current Salt release: 0.17.1

#### Previous topic

salt.modules.glance

#### Next topic

salt.modules.groupadd

### Quick search

Enter search terms or a module, class or function name.

### Upcoming SaltStack Events

My conferences on Lanyrd