From d0d43d182972706a46590b6f301fb537a3f088e5 Mon Sep 17 00:00:00 2001 From: Michael Harp Date: Mon, 7 Sep 2026 12:28:27 -0400 Subject: [PATCH 1/2] Document --environment in puppet agent help The agent help listed about twenty options in USAGE and nothing else, so it read as an exhaustive list. The only hint that any puppet.conf setting is accepted as a long argument was a prose note fifty lines further down at the top of OPTIONS, which is easy to miss when scanning for a flag. Add --environment to USAGE and OPTIONS. It is the one setting whose command-line form changes agent behaviour beyond overriding the config value: when set on the command line the agent skips both the last-run environment and the node request, which is the documented way to move an agent out of an environment it switched to on an earlier run. Note that an ENC can still redirect the run unless strict_environment_mode is set. Add a generic [-- ] to USAGE with a sentence pointing at OPTIONS, and drop the "Note the special 'no-' prefix" sentence from the --no-daemonize entry, which is itself the no- form and already covered by the OPTIONS intro. Regenerate man/man8/puppet-agent.8. Fixes #652 Co-Authored-By: Claude Fable 5.1 Signed-off-by: Michael Harp --- lib/puppet/application/agent.rb | 21 +++++++++++++++++---- man/man8/puppet-agent.8 | 10 +++++++--- 2 files changed, 24 insertions(+), 7 deletions(-) diff --git a/lib/puppet/application/agent.rb b/lib/puppet/application/agent.rb index 4d809b2174..a6a0095589 100644 --- a/lib/puppet/application/agent.rb +++ b/lib/puppet/application/agent.rb @@ -103,9 +103,13 @@ def help ----- puppet agent [--certname ] [-D|--daemonize|--no-daemonize] [-d|--debug] [--detailed-exitcodes] [--digest ] [--disable [MESSAGE]] [--enable] - [--fingerprint] [-h|--help] [-l|--logdest syslog|eventlog||console] + [--environment ] [--fingerprint] [-h|--help] + [-l|--logdest syslog|eventlog||console] [--serverport ] [--noop] [-o|--onetime] [--sourceaddress ] [-t|--test] - [-v|--verbose] [-V|--version] [-w|--waitforcert ] + [-v|--verbose] [-V|--version] [-w|--waitforcert ] [-- ] + + Any setting that is valid in puppet.conf is also accepted as a long argument, + not only the ones listed above. See OPTIONS below. DESCRIPTION @@ -199,8 +203,7 @@ def help * --no-daemonize: Do not send the process into the background. - (This is an OpenVox setting, and can go in puppet.conf. Note the special 'no-' - prefix for boolean settings on the command line.) + (This is an OpenVox setting, and can go in puppet.conf.) * --debug: Enable full debugging. @@ -249,6 +252,16 @@ def help 'puppet agent' exits after executing this. + * --environment: + Request a catalog for the given environment. When set on the command line, + the agent uses this environment directly and skips both the environment + recorded by the previous run and the node request to the server, which is + how it picks an environment otherwise. This is the usual way to move an + agent out of an environment it switched to on an earlier run. The server + can still return a catalog for a different environment, for example when + an ENC assigns one, unless 'strict_environment_mode' is set. + (This is an OpenVox setting, and can go in puppet.conf.) + * --evaltrace: Logs each resource as it is being evaluated. This allows you to interactively see exactly what is being done. (This is an OpenVox setting, and can go in diff --git a/man/man8/puppet-agent.8 b/man/man8/puppet-agent.8 index f28d514113..87414c700e 100644 --- a/man/man8/puppet-agent.8 +++ b/man/man8/puppet-agent.8 @@ -1,6 +1,6 @@ .\" generated with Ronn-NG/v0.10.1 .\" http://github.com/apjanke/ronn-ng/tree/0.10.1 -.TH "PUPPET\-AGENT" "8" "August 2026" "Vox Pupuli" "OpenVox manual" +.TH "PUPPET\-AGENT" "8" "September 2026" "Vox Pupuli" "OpenVox manual" .SH "NAME" \fBpuppet\-agent\fR \- The puppet agent daemon provided by OpenVox .SH "SYNOPSIS" @@ -8,7 +8,9 @@ Retrieves the client configuration from the OpenVox server and applies it to the .P This service may be run as a daemon, run periodically using cron (or something similar), or run interactively for testing purposes\. .SH "USAGE" -puppet agent [\-\-certname \fINAME\fR] [\-D|\-\-daemonize|\-\-no\-daemonize] [\-d|\-\-debug] [\-\-detailed\-exitcodes] [\-\-digest \fIDIGEST\fR] [\-\-disable [MESSAGE]] [\-\-enable] [\-\-fingerprint] [\-h|\-\-help] [\-l|\-\-logdest syslog|eventlog|\fIABS FILEPATH\fR|console] [\-\-serverport \fIPORT\fR] [\-\-noop] [\-o|\-\-onetime] [\-\-sourceaddress \fIIP_ADDRESS\fR] [\-t|\-\-test] [\-v|\-\-verbose] [\-V|\-\-version] [\-w|\-\-waitforcert \fISECONDS\fR] +puppet agent [\-\-certname \fINAME\fR] [\-D|\-\-daemonize|\-\-no\-daemonize] [\-d|\-\-debug] [\-\-detailed\-exitcodes] [\-\-digest \fIDIGEST\fR] [\-\-disable [MESSAGE]] [\-\-enable] [\-\-environment \fINAME\fR] [\-\-fingerprint] [\-h|\-\-help] [\-l|\-\-logdest syslog|eventlog|\fIABS FILEPATH\fR|console] [\-\-serverport \fIPORT\fR] [\-\-noop] [\-o|\-\-onetime] [\-\-sourceaddress \fIIP_ADDRESS\fR] [\-t|\-\-test] [\-v|\-\-verbose] [\-V|\-\-version] [\-w|\-\-waitforcert \fISECONDS\fR] [\-\-\fIsetting\fR \fIVALUE\fR] +.P +Any setting that is valid in puppet\.conf is also accepted as a long argument, not only the ones listed above\. See OPTIONS below\. .SH "DESCRIPTION" This is the main OpenVox client\. Its job is to retrieve the local machine's configuration from a remote server and apply it\. In order to successfully communicate with the remote server, the client must have a certificate signed by a certificate authority that the server trusts; the recommended method for this, at the moment, is to run a certificate authority as part of the OpenVox server (which is the default)\. The client will connect and request a signed certificate, and will continue connecting until it receives one\. .P @@ -45,7 +47,7 @@ See the configuration file documentation at https://docs\.openvoxproject\.org/op .IP "\(bu" 4 \-\-daemonize: Send the process into the background\. This is the default\. (This is an OpenVox setting, and can go in puppet\.conf\. Note the special 'no\-' prefix for boolean settings on the command line\.) .IP "\(bu" 4 -\-\-no\-daemonize: Do not send the process into the background\. (This is an OpenVox setting, and can go in puppet\.conf\. Note the special 'no\-' prefix for boolean settings on the command line\.) +\-\-no\-daemonize: Do not send the process into the background\. (This is an OpenVox setting, and can go in puppet\.conf\.) .IP "\(bu" 4 \-\-debug: Enable full debugging\. .IP "\(bu" 4 @@ -75,6 +77,8 @@ Disable can also take an optional message that will be reported by the 'puppet a .IP \&'puppet agent' exits after executing this\. .IP "\(bu" 4 +\-\-environment: Request a catalog for the given environment\. When set on the command line, the agent uses this environment directly and skips both the environment recorded by the previous run and the node request to the server, which is how it picks an environment otherwise\. This is the usual way to move an agent out of an environment it switched to on an earlier run\. The server can still return a catalog for a different environment, for example when an ENC assigns one, unless 'strict_environment_mode' is set\. (This is an OpenVox setting, and can go in puppet\.conf\.) +.IP "\(bu" 4 \-\-evaltrace: Logs each resource as it is being evaluated\. This allows you to interactively see exactly what is being done\. (This is an OpenVox setting, and can go in puppet\.conf\. Note the special 'no\-' prefix for boolean settings on the command line\.) .IP "\(bu" 4 \-\-fingerprint: Display the current certificate or certificate signing request fingerprint and then exit\. Use the '\-\-digest' option to change the digest algorithm used\. From a7196fd708fff16e25b78a22b6e3ea55422ff2f1 Mon Sep 17 00:00:00 2001 From: Michael Harp Date: Tue, 8 Sep 2026 10:23:11 -0400 Subject: [PATCH 2/2] Clarify strict_environment_mode in --environment help The previous wording implied that strict_environment_mode lets the command-line environment override an ENC assignment. It does not: the agent still cannot beat an ENC. Without strict mode it switches to the server's environment and re-requests the catalog; with strict mode it refuses the mismatched catalog and fails the run. Reword the entry to say that, and regenerate the agent man page. Addresses review feedback from @trefzer on #653. Co-Authored-By: Claude Fable 5.1 Signed-off-by: Michael Harp --- lib/puppet/application/agent.rb | 6 ++++-- man/man8/puppet-agent.8 | 2 +- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/lib/puppet/application/agent.rb b/lib/puppet/application/agent.rb index a6a0095589..6fca51dacb 100644 --- a/lib/puppet/application/agent.rb +++ b/lib/puppet/application/agent.rb @@ -258,8 +258,10 @@ def help recorded by the previous run and the node request to the server, which is how it picks an environment otherwise. This is the usual way to move an agent out of an environment it switched to on an earlier run. The server - can still return a catalog for a different environment, for example when - an ENC assigns one, unless 'strict_environment_mode' is set. + can still assign a different environment, for example through an ENC. In + that case the agent switches to the server's environment and requests + the catalog again. If 'strict_environment_mode' is set, the agent refuses + the mismatched catalog and fails the run instead of switching. (This is an OpenVox setting, and can go in puppet.conf.) * --evaltrace: diff --git a/man/man8/puppet-agent.8 b/man/man8/puppet-agent.8 index 87414c700e..f37bce60d0 100644 --- a/man/man8/puppet-agent.8 +++ b/man/man8/puppet-agent.8 @@ -77,7 +77,7 @@ Disable can also take an optional message that will be reported by the 'puppet a .IP \&'puppet agent' exits after executing this\. .IP "\(bu" 4 -\-\-environment: Request a catalog for the given environment\. When set on the command line, the agent uses this environment directly and skips both the environment recorded by the previous run and the node request to the server, which is how it picks an environment otherwise\. This is the usual way to move an agent out of an environment it switched to on an earlier run\. The server can still return a catalog for a different environment, for example when an ENC assigns one, unless 'strict_environment_mode' is set\. (This is an OpenVox setting, and can go in puppet\.conf\.) +\-\-environment: Request a catalog for the given environment\. When set on the command line, the agent uses this environment directly and skips both the environment recorded by the previous run and the node request to the server, which is how it picks an environment otherwise\. This is the usual way to move an agent out of an environment it switched to on an earlier run\. The server can still assign a different environment, for example through an ENC\. In that case the agent switches to the server's environment and requests the catalog again\. If 'strict_environment_mode' is set, the agent refuses the mismatched catalog and fails the run instead of switching\. (This is an OpenVox setting, and can go in puppet\.conf\.) .IP "\(bu" 4 \-\-evaltrace: Logs each resource as it is being evaluated\. This allows you to interactively see exactly what is being done\. (This is an OpenVox setting, and can go in puppet\.conf\. Note the special 'no\-' prefix for boolean settings on the command line\.) .IP "\(bu" 4