salt-key

List all accepted, unaccepted and rejected minion keys

$ salt-key [[-L|--list-all]]

$ salt-key [[-a|--accept-all]] [MINION_ID]

$ salt-key [[-r|--reject]] [MINION_ID]

$ salt-key [[-F|--finger-all]]

salt-key [options] [arguments]

Common usage patterns:
salt-key -L
salt-key -a minion_id
salt-key -d minion_id
salt-key -A
salt-key -D

-h, --help
    Show the help message and exit.

-V, --version
    Show the program's version number and exit.

-c CONFIG_DIR, --config-dir=CONFIG_DIR
    Specify the directory for the Salt master configuration files. Defaults to /etc/salt.

-L, --list-all
    List all accepted, pending, and rejected minion keys.

-l STATUS, --list=STATUS
    List keys by their status. STATUS can be pending, accepted, rejected, all, or preaccepted.

-a KEY_ID, --accept=KEY_ID
    Accept a specified minion key by its ID.

-A, --accept-all
    Accept all currently pending minion keys.

-d KEY_ID, --delete=KEY_ID
    Delete a specified minion key by its ID (from pending, accepted, or rejected lists).

-D, --delete-all
    Delete all accepted, pending, and rejected minion keys. Use with extreme caution!

-r KEY_ID, --reject=KEY_ID
    Reject a specified minion key by its ID, moving it to the rejected list.

-R, --reject-all
    Reject all currently pending minion keys.

--thumb KEY_ID
    Display the SHA256 thumbprint of a specified key. This is useful for out-of-band verification.

--finger KEY_ID
    Display the SHA256 finger (same as thumbprint) of a specified key. Alias for --thumb.

-y, --yes
    Assume 'yes' to all questions; non-interactive mode. Use with caution, especially with bulk operations.

--key-logfile PATH
    Specify a separate log file path for key actions.

salt-key is a command-line utility for managing Salt minion public keys on a Salt master server. In the SaltStack architecture, minions (client machines) connect to the Salt master (server) using public-key cryptography. When a minion first attempts to connect, it sends its public key to the master. The master, for security reasons, does not automatically accept this key. salt-key provides the interface to review, accept, reject, or delete these pending, accepted, or rejected keys.

This tool is crucial for maintaining the security and integrity of a SaltStack environment. Administrators use salt-key to authorize new minions, remove decommissioned minions, or re-accept keys for minions that might have had their keys revoked or regenerated. It offers various options for listing keys by their status (pending, accepted, rejected), accepting all pending keys, or acting on specific key IDs. Effective use of salt-key is fundamental for secure and robust SaltStack deployments.

Requires root privileges or appropriate permissions on the Salt master's key directory (typically /etc/salt/pki/master/).
Deleting keys (-d or -D) is permanent and will prevent the associated minion from connecting until its key is regenerated and re-accepted.
The --yes (-y) option should be used with extreme caution, especially with -A, -D, or -R, as it bypasses crucial confirmation prompts.

The typical lifecycle of a Salt minion key involves:
1. A new Salt minion starts and attempts to connect to the master.
2. The minion sends its public key to the master.
3. The master lists this key as 'pending' when queried with salt-key -L.
4. An administrator verifies the minion's identity and uses salt-key -a minion_id (or -A) to accept the key.
5. The key moves to the 'accepted' list, allowing the minion to communicate securely with the master.
6. If a minion is decommissioned or compromised, its key can be deleted with salt-key -d minion_id.

Always verify the identity of a minion before accepting its key. This can be done by cross-referencing the minion's ID and its key's thumbprint (obtained via salt-key --thumb minion_id) with information from the minion itself (e.g., from /etc/salt/pki/minion/minion.pem or by running salt-call key.finger on the minion). Accepting unauthorized keys can lead to security vulnerabilities and unauthorized access to your Salt environment.

salt-key has been a fundamental component of the SaltStack project since its initial release in 2011 by Thomas Hatch. As secure communication is central to Salt's architecture, key management was an early and essential feature. Its core functionality has remained consistent over time, with ongoing enhancements focused on robustness, clarity of output, and expanded filtering options, reflecting SaltStack's commitment to powerful and user-friendly command-line administration tools.

salt(1), salt-master(1), salt-minion(1), salt-call(1)