salt.wheel.key#

Wheel system wrapper for the Salt key system to be used in interactions with the Salt Master programmatically.

The key module for the wheel system is meant to provide an internal interface for other Salt systems to interact with the Salt Master. The following usage examples assume that a WheelClient is available:

import salt.config
import salt.wheel
opts = salt.config.master_config('/etc/salt/master')
wheel = salt.wheel.WheelClient(opts)

Note that importing and using the WheelClient must be performed on the same machine as the Salt Master and as the same user that runs the Salt Master, unless external_auth is configured and the user is authorized to execute wheel functions.

The function documentation starts with the wheel reference from the code sample above and use the WheelClient functions to show how they can be called from a Python interpreter.

The wheel key functions can also be called via a salt command at the CLI using the saltutil execution module.

Note

This module defines __func_alias__ to expose some functions under different public names. The Python function list_ is published as key.list and key_str is published as key.print. Always call the aliased name (key.list / key.print) when invoking these functions through salt-api, salt-call or the wheel client.

salt.wheel.key.accept(match, include_rejected=False, include_denied=False)#

Accept keys based on a glob match. Returns a dictionary.

match: The glob match of keys to accept.
include_rejected: To include rejected keys in the match along with pending keys, set this to True. Defaults to False.
include_denied: To include denied keys in the match along with pending keys, set this to True. Defaults to False.

>>> wheel.cmd('key.accept', ['minion1'])
{'minions': ['minion1']}

salt.wheel.key.accept_dict(match, include_rejected=False, include_denied=False)#

Accept keys based on a dict of keys. Returns a dictionary.

match: The dictionary of keys to accept.
include_rejected: To include rejected keys in the match along with pending keys, set this to True. Defaults to False.

New in version 2016.3.4.
include_denied: To include denied keys in the match along with pending keys, set this to True. Defaults to False.

New in version 2016.3.4.

Example to move a list of keys from the minions_pre (pending) directory to the minions (accepted) directory:

>>> wheel.cmd('key.accept_dict',
{
    'minions_pre': [
        'jerry',
        'stuart',
        'bob',
    ],
})
{'minions': ['jerry', 'stuart', 'bob']}

salt.wheel.key.delete(match)#

Delete keys based on a glob match. Returns a dictionary.

match: The glob match of keys to delete.

>>> wheel.cmd_async({'fun': 'key.delete', 'match': 'minion1'})
{'jid': '20160826201244808521', 'tag': 'salt/wheel/20160826201244808521'}

salt.wheel.key.delete_dict(match)#

Delete keys based on a dict of keys grouped by key status. Returns a dictionary describing the keys that remain after the deletion.

match

A dictionary keyed by key status. Recognized statuses are:

minions (accepted)
minions_pre (unaccepted / pending)
minions_rejected
minions_denied

Each value is a list of minion key names under that status. The wheel will iterate the dictionary as-is and attempt to remove each listed key from the directory named by the status. Keys that do not exist on disk under the requested status are silently skipped: delete_dict does not look the key up by name, so passing an unaccepted minion under minions will simply do nothing for that key (and the minion's pending key will remain in place).

If you want to delete keys regardless of their current status, either gather the dictionary with list_match() first, or use delete() with a glob match instead.

>>> wheel.cmd_async({'fun': 'key.delete_dict',
'match': {
    'minions': [
        'jerry',
        'stuart',
        'bob',
    ],
}})
{'jid': '20160826201244808521', 'tag': 'salt/wheel/20160826201244808521'}

Example using more than one status to delete a mix of accepted and pending keys in one call:

>>> wheel.cmd('key.delete_dict', [
...     {
...         'minions': ['accepted-1'],
...         'minions_pre': ['pending-1', 'pending-2'],
...     }
... ])

salt.wheel.key.finger(match, hash_type=None)#

Return the matching key fingerprints. Returns a dictionary.

match: The key for with to retrieve the fingerprint.
hash_type: The hash algorithm used to calculate the fingerprint

>>> wheel.cmd('key.finger', ['minion1'])
{'minions': {'minion1': '5d:f6:79:43:5e:d4:42:3f:57:b8:45:a8:7e:a4:6e:ca'}}

salt.wheel.key.finger_master(hash_type=None)#

Return the fingerprint of the master's public key

hash_type: The hash algorithm used to calculate the fingerprint

>>> wheel.cmd('key.finger_master')
{'local': {'master.pub': '5d:f6:79:43:5e:d4:42:3f:57:b8:45:a8:7e:a4:6e:ca'}}

salt.wheel.key.gen(id_=None, keysize=2048)#

Generate a key pair. No keys are stored on the master. A key pair is returned as a dict containing pub and priv keys. Returns a dictionary containing the pub and priv keys with their generated values.

id_: Set a name to generate a key pair for use with salt. If not specified, a random name will be specified.
keysize: The size of the key pair to generate. The size must be 2048, which is the default, or greater. If set to a value less than 2048, the key size will be rounded up to 2048.

>>> wheel.cmd('key.gen')
{'pub': '-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBC
...
BBPfamX9gGPQTpN9e8HwcZjXQnmg8OrcUl10WHw09SDWLOlnW+ueTWugEQpPt\niQIDAQAB\n
-----END PUBLIC KEY-----',
'priv': '-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEA42Kf+w9XeZWgguzv
...
QH3/W74X1+WTBlx4R2KGLYBiH+bCCFEQ/Zvcu4Xp4bIOPtRKozEQ==\n
-----END RSA PRIVATE KEY-----'}

salt.wheel.key.gen_accept(id_, keysize=2048, force=False)#

Generate a key pair then accept the public key. This function returns the key pair in a dict, only the public key is preserved on the master. Returns a dictionary.

id_: The name of the minion for which to generate a key pair.
keysize: The size of the key pair to generate. The size must be 2048, which is the default, or greater. If set to a value less than 2048, the key size will be rounded up to 2048.
force: If a public key has already been accepted for the given minion on the master, then the gen_accept function will return an empty dictionary and not create a new key. This is the default behavior. If force is set to True, then the minion's previously accepted key will be overwritten.

>>> wheel.cmd('key.gen_accept', ['foo'])
{'pub': '-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBC
...
BBPfamX9gGPQTpN9e8HwcZjXQnmg8OrcUl10WHw09SDWLOlnW+ueTWugEQpPt\niQIDAQAB\n
-----END PUBLIC KEY-----',
'priv': '-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEA42Kf+w9XeZWgguzv
...
QH3/W74X1+WTBlx4R2KGLYBiH+bCCFEQ/Zvcu4Xp4bIOPtRKozEQ==\n
-----END RSA PRIVATE KEY-----'}

We can now see that the foo minion's key has been accepted by the master:

>>> wheel.cmd('key.list', ['accepted'])
{'minions': ['foo', 'minion1', 'minion2', 'minion3']}

salt.wheel.key.gen_keys(keydir=None, keyname=None, keysize=None, user=None)#: Generate minion RSA public keypair

salt.wheel.key.gen_signature(priv, pub, signature_path, auto_create=False, keysize=None)#: Generate master public-key-signature

salt.wheel.key.glob_match(match)#: List all the keys based on a glob match

salt.wheel.key.key_str(match)#

Return information about the key. Returns a dictionary.

match: The key to return information about.

>>> wheel.cmd('key.print', ['minion1'])
{'minions': {'minion1': '-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0B
...
TWugEQpPt\niQIDAQAB\n-----END PUBLIC KEY-----'}}

salt.wheel.key.list_(match)#

List all the keys under a named status. Returns a dictionary.

match: The type of keys to list. The pre, un, and unaccepted options will list unaccepted/unsigned keys. acc or accepted will list accepted/signed keys. rej or rejected will list rejected keys. Finally, all will list all keys.

>>> wheel.cmd('key.list', ['accepted'])
{'minions': ['minion1', 'minion2', 'minion3']}

salt.wheel.key.list_all()#

List all the keys. Returns a dictionary containing lists of the minions in each salt-key category, including minions, minions_rejected, minions_denied, etc. Returns a dictionary.

>>> wheel.cmd('key.list_all')
{'local': ['master.pem', 'master.pub'], 'minions_rejected': [],
'minions_denied': [], 'minions_pre': [],
'minions': ['minion1', 'minion2', 'minion3']}

salt.wheel.key.master_key_str()#

Returns master's public key. Returns a dictionary

>>> wheel.cmd('key.master_key_str')
{'local': {'master.pub': '-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0B
...
TWugEQpPt\niQIDAQAB\n-----END PUBLIC KEY-----'}}

salt.wheel.key.name_match(match)#: Alias to glob_match

salt.wheel.key.reject(match, include_accepted=False, include_denied=False)#

Reject keys based on a glob match. Returns a dictionary.

match: The glob match of keys to reject.
include_accepted: To include accepted keys in the match along with pending keys, set this to True. Defaults to False.
include_denied: To include denied keys in the match along with pending keys, set this to True. Defaults to False.

>>> wheel.cmd_async({'fun': 'key.reject', 'match': 'minion1'})
{'jid': '20160826201244808521', 'tag': 'salt/wheel/20160826201244808521'}

salt.wheel.key.reject_dict(match, include_accepted=False, include_denied=False)#

Reject keys based on a dict of keys. Returns a dictionary.

match: The dictionary of keys to reject.
include_accepted: To include accepted keys in the match along with pending keys, set this to True. Defaults to False.

New in version 2016.3.4.
include_denied: To include denied keys in the match along with pending keys, set this to True. Defaults to False.

New in version 2016.3.4.

>>> wheel.cmd_async({'fun': 'key.reject_dict',
'match': {
    'minions': [
        'jerry',
        'stuart',
        'bob',
    ],
}})
{'jid': '20160826201244808521', 'tag': 'salt/wheel/20160826201244808521'}

Table of Contents

salt.wheel.key#