salt.cache.mmap_key#

A memory-mapped backend specialised for the master's minion-key store (keys and denied_keys banks). Replaces the localfs_key directory layout with an O(1) hash table; salt-key -L and authentication probes drop from seconds to milliseconds at fleet scale. See Memory-Mapped Cache Backend for the full performance picture and migration runner.

mmap-native PKI key cache backend.

New in version 3009.0.

Replaces localfs_key as the keys.cache_driver when higher performance is needed. Unlike localfs_key, this backend stores everything — minion IDs, key state, and public key material — in a pair of memory-mapped files per bank. There is no filesystem fallback and no dual code path.

On-heap record layout for the keys bank:

[STATE: 1 byte][PUB: variable bytes]

State byte values:

0x01  accepted
0x02  pending
0x03  rejected

All other banks (denied_keys, master_keys) store raw bytes in the heap with no state prefix.

The master_keys bank stores private key material (PEM files). A separate MmapCache instance is used for master_keys so that its permissions can be locked down independently.

Configuration (all optional, can be set in /etc/salt/master):

keys.cache_driver: mmap_key

# Slots in the minion key index (default: 1 000 000)
mmap_key_size: 1000000

# Bytes per index slot (default: 96)
mmap_key_slot_size: 96

# Maximum minion ID length in bytes (default: 64)
mmap_key_id_size: 64
salt.cache.mmap_key.contains(bank, key, cachedir, **kwargs)#

Return True if bank contains key.

salt.cache.mmap_key.fetch(bank, key, cachedir, **kwargs)#

Return the stored value for bank/key.

keys bank returns {"state": str, "pub": str} or None. denied_keys returns a list of one pub key string, or {}. master_keys returns the raw PEM string, or {}.

salt.cache.mmap_key.flush_(bank, key=None, cachedir=None, **kwargs)#

Remove key from bank, or wipe the entire bank if key is None.

salt.cache.mmap_key.get_storage_id(kwargs)#

Return a unique identifier for this cache driver instance.

salt.cache.mmap_key.init_kwargs(kwargs)#

Return canonical kwargs; mirrors localfs_key.init_kwargs.

salt.cache.mmap_key.list_(bank, cachedir, **kwargs)#

Return all keys in bank.

salt.cache.mmap_key.list_all(bank, cachedir, include_data=False, **kwargs)#

Return {minion_id: data} for every entry in bank in a single pass.

Faster than list_(bank) + fetch(bank, k) per minion: walks the mmap roster once (O(occupied)) and decodes each heap entry inline, rather than re-probing the index for every key.

For the keys bank the value shape matches localfs_key.list_all:

  • include_data=False (default) — {"state": str} per minion; cheaper to deserialise but still requires reading the heap entry because state is the first byte of the packed value.

  • include_data=True — {"state": str, "pub": str}.

For denied_keys the value is always [pub_str] (denied payloads are small enough that the include_data distinction doesn't pay back).

master_keys is intentionally unsupported — callers that need master-side keys should iterate list_ and fetch explicitly.

salt.cache.mmap_key.rebuild_from_localfs(opts)#

One-time migration: scan the legacy pki directory layout and load all existing keys into the mmap backend.

Safe to call repeatedly — already-present keys are overwritten in-place. Returns (accepted, pending, rejected, denied) counts.

salt.cache.mmap_key.store(bank, key, data, cachedir, **kwargs)#

Store data for bank/key.

keys bank expects {"state": str, "pub": str}. denied_keys bank expects a list; the first element is stored. master_keys bank expects a raw string or bytes.

salt.cache.mmap_key.updated(bank, key, cachedir, **kwargs)#

Return the Unix timestamp (int) of the last write for bank/key, or None if not found.