salt.cache.mmap_key¶

mmap-native PKI key cache backend.

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.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.