[EPIC] Documented options in minion/master config files don't match minion/master config documentation, and vice versa

Description

There are options listed in the conf/minion file that are undocumented in the minion configuration documentation, doc/ref/configuration/minion.rst, and vice versa.

Setup

Clone the latest version of this repository.

Steps to Reproduce the behavior

See the information in Additional context below.

Expected behavior

The options listed in the minion configuration file and the minion configuration documentation should match, or at a minimum the minion configuration documentation should include information regarding all options listed in the conf/minion file. This is the bug.

An improvement/enhancement could be for the conf/minion file to also include all the options in the minion configuration documentation that are currently missing. This would be helpful for users, such as what was experienced in #57931

Additional context

I whipped up these scripts to find all options missing from the conf/minion file that are listed doc/ref/configuration/minion.rst, and vice versa.

Minion audit

#!/usr/bin/env bash
# Format for option names
cat doc/ref/configuration/minion.rst | \
    grep '\-\-\-' -B1 | \
    grep -v '\-\-' | \
    sed 's/``//g' | \
    sort > minion-options-docs.txt

# Grab all config options for minion conf from conf
cat conf/minion | \
    grep ':' | \
    egrep -v "^# |\." | \
    sed 's:#::g' | \
    cut -d':' -f1 | \
    sort | \
    uniq > minion-options-conf.txt

# What's potentially missing from minion conf docs?
diff minion-options-docs.txt minion-options-conf.txt | \
    grep '>' | \
    sed 's:>\ ::g' > settings-missing-from-minion-options-docs.txt

# What's missing from minion conf file?
diff minion-options-docs.txt minion-options-conf.txt | \
    grep '<' | \
    sed 's:<\ ::g' > settings-missing-from-minion-options-conf.txt

This ends up creating two files:

• settings-missing-from-minion-options-conf.txt
• settings-missing-from-minion-options-docs.txt

$ cat settings-missing-from-minion-options-docs.txt | wc -l
8
$ cat settings-missing-from-minion-options-conf.txt | wc -l
71

This seems to say that quite a few options are missing from the minion conf file, and some are missing from the minion configuration documentation.

Missing from conf/minion

Source file: https://github.com/saltstack/salt/blob/master/conf/minion

• conf/minion

always_verify_signature
cache_sreqs
cmd_blacklist_glob
cmd_whitelist_glob
color_theme
decrypt_pillar
decrypt_pillar_default
decrypt_pillar_delimiter
decrypt_pillar_renderers
default_include
default_top
docker.compare_container_networks
docker.update_mine
enable_fqdns_grains
enable_gpu_grains
enable_zip_modules
env_order
extmod_whitelist/extmod_blacklist
fibre_channel_grains
grains_blacklist
grains_cache_expiration
grains_dirs
http_connect_timeout
http_request_timeout
iscsi_grains
lock_saltenv
log_rotate_backup_count
log_rotate_max_bytes
master_sign_key_name
master_tops_first
master_type
master_uri_format
metadata_server_grains
minion_id_remove_domain
modules_max_memory
nvme_grains
on_demand_ext_pillar
optimization_order
pass_to_ext_pillars
pidfile
publish_port
recon_default
recon_max
recon_randomize
retry_dns
retry_dns_count
return_retry_timer
return_retry_timer_max
saltenv
snapper_states
snapper_states_config
source_address
source_interface_name
source_publish_port
source_ret_port
ssh_merge_pillar
state_top
state_top_saltenv
top_file_merging_strategy
transport
use_master_when_local
use_yamlloader_old
verify_master_pubkey_sign
winrepo_cache_expire_max
winrepo_cache_expire_min
winrepo_cachefile
winrepo_dir
winrepo_dir_ng
winrepo_remotes
winrepo_remotes_ng
winrepo_source_dir

Missing from doc/ref/configuration/minion.rst

Source file: https://github.com/saltstack/salt/blob/master/doc/ref/configuration/minion.rst

• doc/ref/configuration/minion.rst

color
environment
event_match_type
key_logfile
output
return
state_aggregate
state_output_profile

Other Thoughts

Are the minion configuration options auto-populated anywhere? If not, it would be a good idea to introduce automation that would autopopulate content in either the minion conf file, or the rst documentation page (or both, ideally). That, or audit to see whether there are currently conf options that aren't included in the minion conf, nor the rst documentation page.

Start by comparing conf/minion with doc/ref/configuration/minion.rst using the audit commands in the issue, then review the generated missing-option lists. Reconcile the documented and example configuration options, or establish the proposed automation if that is selected. Done means both sources consistently cover the relevant options and the audit reports no unexplained differences.