This is the agent for the PCP Execution Protocol (PXP), based on the the Puppet Communications Protocol (PCP). It enables the execution of actions on remote nodes.
The PCP interface is provided by cpp-pcp-client which, in turn, relies on websocket++.
pxp-agent needs to be connected to a PCP broker to operate; please refer to the documentation below for how to do that.
- a C++11 compiler (clang/gcc 4.7)
- gnumake
- CMake
- Boost
- OpenSSL
- ruby (2.0 and newer)
- leatherman (0.5.1 or newer)
- cpp-pcp-client (master)
The following will install all required tools and libraries:
yum install boost-devel openssl-devel gcc-c++ make wget tar cmake
This assumes Clang is installed and the system OpenSSL libraries will be used.
The following will install all required libraries:
brew install cmake boost
The following will install most required tools and libraries:
apt-get install build-essential libboost-all-dev libssl-dev wget tar cmake
MinGW-w64 is used for full C++11 support, and Chocolatey can be used to install. You should have at least 2GB of memory for compilation.
-
choco install cmake 7zip.commandline -
install MinGW-w64
choco install mingw --params "/threads:win32"
For the remaining tasks, build commands can be executed in the shell from:
Start > MinGW-w64 project > Run Terminal
-
select an install location for dependencies, such as C:\tools or cmake\release\ext; we'll refer to it as $install
-
build Boost
.\bootstrap mingw .\b2 toolset=gcc --build-type=minimal install --prefix=$install --with-program_options --with-system --with-filesystem --with-date_time --with-thread --with-regex --with-log --with-locale --with-chrono boost.locale.iconv=off
In Powershell:
choco install cmake 7zip.commandline -y
choco install mingw --params "/threads:win32" -y
$env:PATH = "C:\tools\mingw64\bin;$env:PATH"
$install = "C:\tools"
(New-Object Net.WebClient).DownloadFile("https://downloads.sourceforge.net/boost/boost_1_54_0.7z", "$pwd/boost_1_54_0.7z")
7za x boost_1_54_0.7z
pushd boost_1_54_0
.\bootstrap mingw
.\b2 toolset=gcc --build-type=minimal install --prefix=$install --with-program_options --with-system --with-filesystem --with-date_time --with-thread --with-regex --with-log --with-locale --with-chrono boost.locale.iconv=off
popd
-
build & install leatherman
-
build & install cpp-pcp-client
-
build the pxp-agent
Thanks to the CMake, the project can be built out-of-source tree, which allows for multiple independent builds. Aside from the standard CMake switches the build supports the following options:
- TEST_VIRTUAL when set to ON certain class member functions become virtual to enable mocking for unit tests (default OFF)
- DEV_LOG_COLOR enables colorization for logging (development setting) (default OFF)
example release build:
mkdir release cd release cmake .. makeexample debug/test build:
mkdir debug cd debug cmake -DCMAKE_BUILD_TYPE=Debug -DTEST_VIRTUAL=ON -DDEV_LOG_COLOR=ON .. make
pxp-agent should be configured in your system to be executed automatically as a
service. In case you need to run it manually, you can invoke directly its
executable file; after building from source, it is located in the ./build/bin
directory; in case an installer was used, the default locations are:
- *nix: /opt/puppetlabs/puppet/bin/pxp-agent
- Windows: C:\Program Files\Puppet Labs\Puppet\pxp-agent\bin\pxp-agent.exe
Configuration options can be passed as command line arguments or by using a configuration file (see below).
The agent will execute as a background process by default; in that case, it prevents multiple instances running at the same time. Please refer to the following sections for platform-specific behavior.
In case --foreground is unflagged, pxp-agent will start as a daemon and its
PID will be stored in /var/run/puppetlabs/pxp-agent.pid, or in another
location if specified by --pidfile. pxp-agent will rely on such file to
prevent multiple daemon instances from executing at once. The PID file will be
removed if the daemon is stopped by using one of SIGINT, SIGTERM, or SIGQUIT
signals.
pxp-agent relies on nssm to execute as a service. In case --foreground
is unflagged, a mutex-based mechanism will prevent multiple instances of
pxp-agent. Note that no PID file will be created.
In POSIX, when the daemon is successfully instantiated, the parent process returns 0. In case of a daemonization failure, it returns 4.
In case of it fails to parse the command line options or the configuration file, pxp-agent returns 2.
In case of invalid configuration, say an option is set to an invalid value, it returns 3.
For all other failures it returns 1.
Actions are grouped in modules, by which they can be loaded and configured within pxp-agent. An example of module is given by the Puppet module; a trivial one is the reverse module that is used for testing.
A module is a file that provides an interface to retrieve information about its actions (we call such information metadata - it's a set of JSON schemas) and to execute actions.
The metadata is used by pxp-agent to acquire knowledge about the module's actions and validate its configuration. For each action, the metadata specifies the format of the input arguments and the output results. Please refer to this document for more details on requirements for modules.
To run a given action, pxp-agent invokes the module with the action name. The input specified in the PXP request and other parameters will be then passed to the module via stdin.
pxp-agent invokes modules directly, as executables. For determining the paths of
the executables, pxp-agent will inspect the --modules-dir directory and
look for:
- POSIX: files without any suffix;
- Windows: files with ".bat" extension.
Note that the transaction status module is
implemented natively; there is no module file for it. Also, as a side note,
status query requests must be of blocking.
Modules can be configured by placing a configuration file in the
--modules-config-dir named like <module_name>.conf. The content of a
configuration file must be in JSON format and conform with the configuration
schema provided by the module's metadata, otherwise the module will not be
loaded.
The PXP agent is configured with a config file. The values in the config file can be overridden by supplying arguments on the command line.
The agent will look for the default config file in:
- *nix: /etc/puppetlabs/pxp-agent/pxp-agent.conf
- Windows: C:\ProgramData\PuppetLabs\pxp-agent\etc\pxp-agent.conf
A different config file can be specified by passing the --config-file option.
The config files use the JSON format. Options must be specified as entries of a single JSON object. Example:
{
"broker-ws-uris" : ["wss://pcp_broker_cn:8142/pcp/", "wss://pcp_alt_broker_cn:8142/pcp/"],
"ssl-key" : "/etc/puppetlabs/puppet/ssl/private_keys/myhost.net.pem",
"ssl-ca-cert" : "/etc/puppetlabs/puppet/ssl/certs/ca.pem",
"ssl-cert" : "/etc/puppetlabs/puppet/ssl/certs/myhost.net.pem"
}
Note that you have to specify the WebSocket secure URI of the PCP broker and the certificate of the CA that is used by it, in order to establish the WebSocket connection on top of which the PCP communication will take place (PCP uses secure WebSocket). Also, the hostname used in the WebSocket URI must match the SSL identity used by the broker.
The simple instructions for setting up a test PCP broker use pre-
generated certs present in that repo. To connect to this test broker, you'll first
need to add a hosts config that redirects broker.example.com to the broker host
so that server certificate verification succeeds. Then point pxp-agent at ca
and a client certificate present in PCP broker. Example:
puppet resource host broker.example.com ip=<host ip>
pxp-agent --broker-ws-uri wss://broker.example.com:8142/pcp \
--ssl-ca-cert $pcp_broker/test-resources/ssl/certs/ca.pem \
--ssl-cert $pcp_broker/test-resources/ssl/certs/client01.example.com.pem \
--ssl-key $pcp_broker/test-resources/ssl/private_keys/client01.example.com.pem \
--spool-dir dev-resources/spool \
--modules-dir modules \
--logfile - --loglevel debug --foreground
By default, log messages will be written to:
- *nix: /var/log/puppetlabs/pxp-agent/pxp-agent.log
- Windows: C:\ProgramData\PuppetLabs\pxp-agent\var\log\pxp-agent.log.
You can specify a different file with the --logfile option.
When running in foreground mode, it is possible to display log messages on
console by using an hyphen instead of a file path: --logfile -.
The default log level is info. You can specify a different log level by
using the --loglevel option with one of the following strings: none,
trace, debug, info, warning, error, fatal.
The PXP agent has the following configuration options
config-file (optional)
Specify which config file to use.
broker-ws-uri (required to connect)
The WebSocket URI of the PXP broker you wish to connect the agent to, in the
wss://<broker identity>:8142/pcp/ format; example:
wss://pcp_broker_cn:8142/pcp/
broker-ws-uris (alternative to broker-ws-uri)
A config file only alternative to broker-ws-uri, that takes an array specifying multiple brokers the agent can connect to. When multiple brokers are specified, it will use them in a failover capacity, where if it's unable to connect to one it will try the next in the list, and repeat until a successful connection is made. In the event of a disconnect, the agent will retry that connection before trying a new broker.
connection-timeout (optional flag)
Maximum amount of time that may elapse when trying to establish a connection to the broker in seconds. Defaults to 5 seconds.
ssl-ca-cert (required to connect)
The location of your SSL Certificate Authority certificate, example /etc/puppet/ssl/ca/ca_crt.pem
ssl-cert (required to connect)
The location of the pxp-agent SSL certificate, example /etc/puppet/ssl/certs/bob_crt.pem
ssl-key (required to connect)
The location of the pxp-agent's SSL private key, example /etc/puppet/ssl/certs/bob_key.pem
logfile (optional)
The path of the log file.
loglevel (optional)
Specify one of the following logging levels: none, trace, debug, info, warning, error, or fatal; the default one is info
modules-dir (optional)
Specify the directory where modules are stored
modules-config-dir (optional)
Specify the directory containing the configuration files of modules
spool-dir (optional)
The location where the outcome of non-blocking requests will be stored; the default location is:
- *nix: /opt/puppetlabs/pxp-agent/spool
- Windows: C:\ProgramData\PuppetLabs\pxp-agent\var\spool Note that if the specified spool directory does not exist, pxp-agent will create it when starting.
spool-dir-purge-ttl (optional)
Automatically delete results subdirectories located in the spool directory
that have a start timestamp that has expired in respect to the specified TTL.
The TTL value must be an integer with one of the following suffixes:
- 'm' - minutes
- 'h' - hours
- 'd' - days The default TTL value is "14d" (14 days). Specifying a 0, with any of the above suffixes, will disable the purge functionality. Note that the purge will take place when pxp-agent starts and will be repeated at each 1.2*TTL interval.
foreground (optional flag)
Don't become a daemon and execute on foreground on the associated terminal.
*pidfile (optional; only on nix platforms)
The path of the PID file; the default is /var/run/puppetlabs/pxp-agent.pid
Please refer to this document.