Skip to content

Document --environment in puppet agent help #653

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
miharp wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Document --environment in puppet agent help #653

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d0d43d1
Document --environment in puppet agent help
miharp Sep 7, 2026
a7196fd
Clarify strict_environment_mode in --environment help
miharp Sep 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 19 additions & 4 deletions lib/puppet/application/agent.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,9 +103,13 @@ def help
-----
puppet agent [--certname <NAME>] [-D|--daemonize|--no-daemonize]
[-d|--debug] [--detailed-exitcodes] [--digest <DIGEST>] [--disable [MESSAGE]] [--enable]
[--fingerprint] [-h|--help] [-l|--logdest syslog|eventlog|<ABS FILEPATH>|console]
[--environment <NAME>] [--fingerprint] [-h|--help]
[-l|--logdest syslog|eventlog|<ABS FILEPATH>|console]
[--serverport <PORT>] [--noop] [-o|--onetime] [--sourceaddress <IP_ADDRESS>] [-t|--test]
[-v|--verbose] [-V|--version] [-w|--waitforcert <SECONDS>]
[-v|--verbose] [-V|--version] [-w|--waitforcert <SECONDS>] [--<setting> <VALUE>]

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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -249,6 +252,18 @@ 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 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.)

@trefzer trefzer Sep 8, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think setting strict_environment_mode does make it fail. As far as I know it's not possible to switch the environment if it is set through ENC. (don't know if you can overwrite it if set in the cert).

@miharp miharp Sep 8, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're right, and the wording was misleading. --environment can't beat an ENC in either mode. Without strict_environment_mode the agent follows the ENC and re-requests the catalog; with it, the agent refuses the mismatched catalog and the run fails. Reworded in a7196fd to say exactly that.

On the cert: the pp_environment extension exists as an OID but nothing in the agent, node, or catalog code reads it to pick an environment. It only surfaces as a trusted fact, so an ENC or site.pp would have to act on it explicitly.

@bastelfreak bastelfreak Sep 10, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be a great openvox-server 9 feature to enforce the environment from pp_environment


* --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
Expand Down
10 changes: 7 additions & 3 deletions man/man8/puppet-agent.8
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,16 @@
.\" 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"
Retrieves the client configuration from the OpenVox server and applies it to the local host\.
.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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 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
\-\-fingerprint: Display the current certificate or certificate signing request fingerprint and then exit\. Use the '\-\-digest' option to change the digest algorithm used\.
Expand Down