# salt.roster.cache

The `cache` roster provides a flexible interface to the Salt Masters' minion cache to access regular minions over `salt-ssh`.

Added in version 2017.7.0:

- grains, pillar, mine data matching

- SDB URLs

- IPv6 support

- roster_order per config key

- default order changed to industry-wide best practices

- CIDR range selection

## Targeting

This roster supports all matching and targeting of the Salt Master. The matching will be done using only the Salt Master's cache.

## The Roster Order

The roster's composition can be configured using `roster_order`. In the `roster_order` you can define any roster key and fill it with a parameter overriding the one in `roster_defaults`:

    roster_order:
        host: id          # use the minion id as hostname

You can define lists of parameters as well, the first result from the list will become the value.

### Selecting a host

    # default
    roster_order:
        host:
          - ipv6-private  # IPv6 addresses in private ranges
          - ipv6-global   # IPv6 addresses in global ranges
          - ipv4-private  # IPv4 addresses in private ranges
          - ipv4-public   # IPv4 addresses in public ranges
          - ipv4-local    # loopback addresses

This is the default `roster_order`. It prefers IPv6 over IPv4 addresses and private addresses over public ones. The relevant data will be fetched from the cache in-order, and the first match will fill the `host` key.

Other address selection parameters are also possible:

    roster_order:
      host:
        - global|public|private|local    # Both IPv6 and IPv4 addresses in that range
        - 2000::/3                       # CIDR networks, both IPv4 and IPv6 are supported

### Using cached data

Several cached libraries can be selected using the `library: `` prefix, followed by the library key. This can be referenced using the same ``:` syntax as e.g. `pillar.get`. Lists of references are also supported during the lookup, as are Salt SDB URLs.

This should be especially useful for the other roster keys:

    roster_order:
      host:
        - grain: fqdn_ip4                # Lookup this grain
        - mine: network.ip_addrs         # Mine data lookup works the same

      password: sdb://vault/ssh_pass     # Salt SDB URLs are also supported

      user:
        - pillar: ssh:auth:user          # Lookup this pillar key
        - sdb://osenv/USER               # Lookup this env var through sdb

      priv:
        - pillar:                        # Lists are also supported
            - salt:ssh:private_key
            - ssh:auth:private_key

salt.roster.cache.targets(tgt, tgt_type='glob', **kwargs)

  Return the targets from the Salt Masters' minion cache. All targets and matchers are supported.

  The resulting roster can be configured using `roster_order` and `roster_default`.