Summary
puppet agent --help (and the puppet-agent(8) man page generated from it) has two gaps that make the --environment argument hard to discover, raised by @defnull in OpenVoxProject/openvox-docs#477 (comment).
1. The USAGE line reads as an exhaustive list
The USAGE block in lib/puppet/application/agent.rb lists about twenty bracketed options and nothing else. There is no [--<setting> <VALUE>] or ... to hint that any configuration setting is also accepted as a long argument. The only mention of that is a prose note at the top of the OPTIONS section, fifty lines further down, which is easy to miss when scanning for a specific flag.
2. --environment is not listed, but its CLI form changes agent behaviour
Several plain settings are already listed in OPTIONS because they are commonly used on the command line (noop, serverport, sourceaddress, certname). environment is arguably the most important one to list, because passing it on the command line does more than override the puppet.conf value. In lib/puppet/configurer.rb the agent checks Puppet.settings.set_by_cli?(:environment) and, when true, skips both the last-run environment lookup (last_run_summary.yaml / use_last_environment) and the node request to the server. This is the documented way to reset an agent stuck in the wrong environment, and none of that is visible from the help text.
Note that it does not bypass the catalog environment check: an ENC can still redirect the run unless strict_environment_mode is set.
Proposed change
- Add an
--environment entry to the OPTIONS list in the agent help, noting that when given on the command line the agent uses that environment directly and skips the last-run environment and the node request.
- Make the USAGE line hint that settings are accepted, e.g. append
[--<setting> <VALUE>] with a pointer to the OPTIONS note.
- While there, drop the redundant "Note the special 'no-' prefix" sentence from the
--no-daemonize entry. That entry is itself the no- form, and the OPTIONS intro already uses --daemonize / --no-daemonize as its worked example.
- Regenerate
man/man8/puppet-agent.8.
Refs: OpenVoxProject/openvox-docs#477
Summary
puppet agent --help(and thepuppet-agent(8)man page generated from it) has two gaps that make the--environmentargument hard to discover, raised by @defnull in OpenVoxProject/openvox-docs#477 (comment).1. The USAGE line reads as an exhaustive list
The USAGE block in
lib/puppet/application/agent.rblists about twenty bracketed options and nothing else. There is no[--<setting> <VALUE>]or...to hint that any configuration setting is also accepted as a long argument. The only mention of that is a prose note at the top of the OPTIONS section, fifty lines further down, which is easy to miss when scanning for a specific flag.2.
--environmentis not listed, but its CLI form changes agent behaviourSeveral plain settings are already listed in OPTIONS because they are commonly used on the command line (
noop,serverport,sourceaddress,certname).environmentis arguably the most important one to list, because passing it on the command line does more than override thepuppet.confvalue. Inlib/puppet/configurer.rbthe agent checksPuppet.settings.set_by_cli?(:environment)and, when true, skips both the last-run environment lookup (last_run_summary.yaml/use_last_environment) and the node request to the server. This is the documented way to reset an agent stuck in the wrong environment, and none of that is visible from the help text.Note that it does not bypass the catalog environment check: an ENC can still redirect the run unless
strict_environment_modeis set.Proposed change
--environmententry to the OPTIONS list in the agent help, noting that when given on the command line the agent uses that environment directly and skips the last-run environment and the node request.[--<setting> <VALUE>]with a pointer to the OPTIONS note.--no-daemonizeentry. That entry is itself theno-form, and the OPTIONS intro already uses--daemonize/--no-daemonizeas its worked example.man/man8/puppet-agent.8.Refs: OpenVoxProject/openvox-docs#477