{"id":15022717,"url":"https://github.com/puppetlabs/pxp-agent","last_synced_at":"2025-08-12T10:11:03.084Z","repository":{"id":19964850,"uuid":"23231786","full_name":"puppetlabs/pxp-agent","owner":"puppetlabs","description":"PCP eXecution Protocol Agent","archived":false,"fork":false,"pushed_at":"2025-01-13T23:01:43.000Z","size":11241,"stargazers_count":22,"open_issues_count":0,"forks_count":59,"subscribers_count":150,"default_branch":"main","last_synced_at":"2025-03-30T05:09:00.903Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"luanfujun/deep-photo-styletransfer","license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/puppetlabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-08-22T16:25:01.000Z","updated_at":"2025-02-06T20:41:39.000Z","dependencies_parsed_at":"2023-02-19T14:10:40.050Z","dependency_job_id":"3ccb2176-6a10-4ae5-b938-c0aba9db9b7e","html_url":"https://github.com/puppetlabs/pxp-agent","commit_stats":{"total_commits":1535,"total_committers":76,"mean_commits":20.19736842105263,"dds":0.6807817589576548,"last_synced_commit":"eae4c326aefb1a0187760eec19409d6e0b66d405"},"previous_names":["puppetlabs-toy-chest/pxp-agent","puppetlabs/pxp-agent"],"tags_count":92,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpxp-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpxp-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpxp-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpxp-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/puppetlabs","download_url":"https://codeload.github.com/puppetlabs/pxp-agent/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247441063,"owners_count":20939239,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-24T19:58:18.361Z","updated_at":"2025-04-06T06:13:56.831Z","avatar_url":"https://github.com/puppetlabs.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PXP Agent\n\nThis repository is archived and Perforce will no longer be updating this repository. For more information, see https://www.puppet.com/blog/open-source-puppet-updates-2025.\n\nThis is the agent for the PCP Execution Protocol [(PXP)][pxp_specs_root], based\non the the Puppet Communications Protocol [(PCP)][pcp_specs_root]. It enables\nthe execution of [actions][pxp_specs_actions] on remote nodes.\n\nThe PCP interface is provided by [cpp-pcp-client][cpp-pcp-client] which, in\nturn, relies on [websocket++][websocketpp].\n\npxp-agent needs to be connected to a [PCP broker][pcp-broker] to operate; please\nrefer to the documentation below for how to do that.\n\nDependencies\n------------\n\n - a C++11 compiler (clang/gcc 4.7)\n - gnumake\n - CMake\n - Boost\n - OpenSSL\n - ruby (2.0 and newer)\n - [leatherman][leatherman] (0.5.1 or newer)\n - [cpp-pcp-client][cpp-pcp-client] (master)\n\nInitial Setup\n-------------\n\n#### Setup on Fedora 23\n\nThe following will install all required tools and libraries:\n\n    yum install boost-devel openssl-devel gcc-c++ make wget tar cmake\n\n#### Setup on Mac OSX El Capitan (homebrew)\n\nThis assumes Clang is installed and the system OpenSSL libraries will be used.\n\nThe following will install all required libraries:\n\n    brew install cmake boost\n\n#### Setup on Ubuntu 15.10 (Trusty)\n\nThe following will install most required tools and libraries:\n\n    apt-get install build-essential libboost-all-dev libssl-dev wget tar cmake\n\n#### Setup on Windows\n\n[MinGW-w64][MinGW-w64] is used for full C++11 support, and\n[Chocolatey][Chocolatey] can be used to install. You should have at least 2GB of\nmemory for compilation.\n\n* install [CMake][CMake-choco] \u0026 [7zip][7zip-choco]\n\n        choco install cmake 7zip.commandline\n\n* install [MinGW-w64][MinGW-w64-choco]\n\n        choco install mingw --params \"/threads:win32\"\n\nFor the remaining tasks, build commands can be executed in the shell from:\n\n        Start \u003e MinGW-w64 project \u003e Run Terminal\n\n* select an install location for dependencies, such as C:\\\\tools or cmake\\\\release\\\\ext; we'll refer to it as $install\n\n* build [Boost][Boost-download]\n\n        .\\bootstrap mingw\n        .\\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\n\nIn Powershell:\n\n    choco install cmake 7zip.commandline -y\n    choco install mingw --params \"/threads:win32\" -y\n    $env:PATH = \"C:\\tools\\mingw64\\bin;$env:PATH\"\n    $install = \"C:\\tools\"\n\n    (New-Object Net.WebClient).DownloadFile(\"https://downloads.sourceforge.net/boost/boost_1_54_0.7z\", \"$pwd/boost_1_54_0.7z\")\n    7za x boost_1_54_0.7z\n    pushd boost_1_54_0\n    .\\bootstrap mingw\n    .\\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\n    popd\n\nBuild\n-----\n\n* build \u0026 install [leatherman][leatherman]\n\n* build \u0026 install [cpp-pcp-client][cpp-pcp-client]\n\n* build the pxp-agent\n\n  Thanks to the CMake, the project can be built out-of-source tree, which allows for\n  multiple independent builds.\n  Aside from the standard CMake switches the build supports the following option:\n\n   * **DEV_LOG_COLOR** enables colorization for logging (development setting)\n     (default _OFF_)\n\n  example release build:\n\n      mkdir release\n      cd release\n      cmake ..\n      make\n\n  example debug/test build:\n\n      mkdir debug\n      cd debug\n      cmake -DCMAKE_BUILD_TYPE=Debug -DDEV_LOG_COLOR=ON ..\n      make\n\n  NOTE: If the versions of OpenSSL and libcurl conflict with each other, curl may fail\n  to load SSL files. On macOS this is common when using Homebrew. Invoke cmake with the\n  following commands to use the Homebrew versions of OpenSSL and libcurl:\n    cmake -DCMAKE_PREFIX_PATH=\"/usr/local/opt/openssl;/usr/local/opt/curl\" ..\n\nUsage\n-----\n\n### Starting the agent\n\npxp-agent should be configured in your system to be executed automatically as a\nservice. In case you need to run it manually, you can invoke directly its\nexecutable file; after building from source, it is located in the `./build/bin`\ndirectory; in case an installer was used, the default locations are:\n\n - \\*nix: */opt/puppetlabs/puppet/bin/pxp-agent*\n - Windows: *C:\\Program Files\\Puppet Labs\\Puppet\\pxp-agent\\bin\\pxp-agent.exe*\n\nConfiguration options can be passed as command line arguments or by using a\nconfiguration file (see below).\n\nThe agent will execute as a background process by default; in that case,\nit prevents multiple instances running at the same time. Please refer to the\nfollowing sections for platform-specific behavior.\n\n#### *nix\n\nIn case `--foreground` is unflagged, pxp-agent will start as a daemon and its\nPID will be stored in */var/run/puppetlabs/pxp-agent.pid*, or in another\nlocation if specified by `--pidfile`. pxp-agent will rely on such file to\nprevent multiple daemon instances from executing at once. The PID file will be\nremoved if the daemon is stopped by using one of SIGINT, SIGTERM, or SIGQUIT\nsignals.\n\n#### Windows\n\npxp-agent relies on [nssm][nssm] to execute as a service. In case `--foreground`\nis unflagged, a mutex-based mechanism will prevent multiple instances of\npxp-agent. Note that no PID file will be created.\n\n#### Exit code\n\nIn POSIX, when the daemon is successfully instantiated, the parent process\nreturns 0. In case of a daemonization failure, it returns 4.\n\nIn case of it fails to parse the command line options or the configuration file,\npxp-agent returns 2.\n\nIn case of invalid configuration, say an option is set to an invalid value, it\nreturns 3.\n\nFor all other failures it returns 1.\n\n### Modules\n\n[Actions][pxp_specs_actions] are grouped in modules, by which they can be loaded\nand configured within pxp-agent. An example of module is given by the\n[Puppet module][pxp-module-puppet_script]; a trivial one is the\n[reverse module][pxp-module-puppet_docs] that is used for testing.\n\n#### Modules interface\n\nA module is a file that provides an interface to retrieve information about\nits actions (we call such information metadata - it's a set of JSON schemas) and\nto execute actions.\n\nThe metadata is used by pxp-agent to acquire knowledge about the module's\nactions and validate its configuration. For each action, the metadata specifies\nthe format of the input arguments and the output results. Please refer to\n[this document][modules_docs] for more details on requirements for modules.\n\nTo run a given action, pxp-agent invokes the module with the action\nname. The input specified in the [PXP request][pxp_specs_request_response] and\nother parameters will be then passed to the module via stdin.\n\npxp-agent invokes modules directly, as executables. For determining the paths of\nthe executables, pxp-agent will inspect the `--modules-dir` directory and\nlook for:\n\n - **POSIX**: files without any suffix;\n - **Windows**: files with \".bat\" extension.\n\nNote that the [transaction status module][pxp_specs_transaction_status] is\nimplemented natively; there is no module file for it. Also, as a side note,\n`status query` requests must be of [blocking][pxp_specs_request_response].\n\n#### Modules configuration\n\nModules can be configured by placing a configuration file in the\n`--modules-config-dir` named like `\u003cmodule_name\u003e.conf`. The content of a\nconfiguration file must be in JSON format and conform with the `configuration`\nschema provided by the module's metadata, otherwise the module will not be\nloaded.\n\n### Configuring the agent\n\nThe PXP agent is configured with a config file. The values in the config file\ncan be overridden by supplying arguments on the command line.\n\nThe agent will look for the default config file in:\n - \\*nix: */etc/puppetlabs/pxp-agent/pxp-agent.conf*\n - Windows: *C:\\ProgramData\\PuppetLabs\\pxp-agent\\etc\\pxp-agent.conf*\n\nA different config file can be specified by passing the `--config-file` option.\n\nThe config files use the JSON format. Options must be specified as entries of a\nsingle JSON object. Example:\n\n```\n{\n    \"broker-ws-uris\" : [\"wss://pcp_broker_cn:8142/pcp/\", \"wss://pcp_alt_broker_cn:8142/pcp/\"],\n    \"ssl-key\" : \"/etc/puppetlabs/puppet/ssl/private_keys/myhost.net.pem\",\n    \"ssl-ca-cert\" : \"/etc/puppetlabs/puppet/ssl/certs/ca.pem\",\n    \"ssl-cert\" : \"/etc/puppetlabs/puppet/ssl/certs/myhost.net.pem\"\n}\n```\n\nNote that you have to specify the WebSocket secure URI of the\n[PCP broker][pcp-broker] and the certificate of the CA that is used by it, in\norder to establish the WebSocket connection on top of which the PCP\ncommunication will take place (PCP uses secure WebSocket). Also, the hostname\nused in the WebSocket URI must match the SSL identity used by the broker.\n\n### Testing against a test broker\n\nThe simple instructions for setting up a test [PCP broker][pcp-broker] use pre-\ngenerated certs present in that repo. To connect to this test broker, you'll first\nneed to add a hosts config that redirects `broker.example.com` to the broker host\nso that server certificate verification succeeds. Then point pxp-agent at `ca`\nand a client certificate present in [PCP broker][pcp-broker]. Example:\n\n```\npuppet resource host broker.example.com ip=\u003chost ip\u003e\npxp-agent --broker-ws-uri wss://broker.example.com:8142/pcp \\\n          --ssl-ca-cert $pcp_broker/test-resources/ssl/certs/ca.pem \\\n          --ssl-cert $pcp_broker/test-resources/ssl/certs/client01.example.com.pem \\\n          --ssl-key $pcp_broker/test-resources/ssl/private_keys/client01.example.com.pem \\\n          --spool-dir dev-resources/spool \\\n          --modules-dir modules \\\n          --logfile - --loglevel debug --foreground\n```\n\n#### Logging\n\nBy default, log messages will be written to:\n - \\*nix: */var/log/puppetlabs/pxp-agent/pxp-agent.log*\n - Windows: *C:\\ProgramData\\PuppetLabs\\pxp-agent\\var\\log\\pxp-agent.log*.\n\nYou can specify a different file with the `--logfile` option.\n\nWhen running in foreground mode, it is possible to display log messages on\nconsole by using an hyphen instead of a file path: `--logfile -`.\n\nThe default log level is `info`. You can specify a different log level by\nusing the `--loglevel` option with one of the following strings: `none`,\n`trace`, `debug`, `info`, `warning`, `error`, `fatal`.\n\n#### PCP Access Logging\n\nThe `pcp_access` logger provides information about incoming PCP messages.\nYou can enable it by setting the `log-pcp-access` flag.\n\nThe default location of the `pcp_access` log file is:\n - \\*nix: */var/log/puppetlabs/pxp-agent/pxp-access.log*\n - Windows: *C:\\ProgramData\\PuppetLabs\\pxp-agent\\var\\log\\pxp-access.log*.\nYou can specify a different file with the `pcp-access-logfile` option.\n\nEach pcp_access entry is composed of 6 fields:\n\n```\n[\u003cdate time\u003e] \u003caccess outcome\u003e \u003cbroker: WS URI\u003e \u003csender: PCP URI\u003e \u003cPCP messagetype\u003e \u003cPCP message id\u003e\n```\n\nFor example:\n\n```\n[2016-08-24 13:56:10.737760] AUTHORIZATION_SUCCESS wss://localhost:8142/pcp pcp:///server http://puppetlabs.com/associate_response 9766ba60-a51f-4910-9921-c76990aa9b38\n[2016-08-24 14:07:51.859244] AUTHORIZATION_SUCCESS wss://localhost:8142/pcp/vNext pcp://peg.example.com/peg-controller http://puppetlabs.com/rpc_blocking_request a06e371a-08a2-47f0-913c-15780d668e2f\n```\n\nThe second entry gives the outcome of the message validation; possible values\nare:\n\n| validation outcome | description\n|--------------------|------------\n| DESERIALIZATION_ERROR | invalid PCP message that can't be deserialized\n| AUTHORIZATION_SUCCESS | the message will be processed by pxp-agent\n\n#### List of all configuration options\n\nThe PXP agent has the following configuration options\n\n**config-file (optional)**\n\nSpecify which config file to use.\n\n**broker-ws-uri (required to connect)**\n\nThe WebSocket URI of the PXP broker you wish to connect the agent to, in the\n`wss://\u003cbroker identity\u003e:8142/pcp/` format; example:\n*wss://pcp_broker_cn:8142/pcp/*\n\n**broker-ws-uris (alternative to broker-ws-uri)**\n\nA config file only alternative to broker-ws-uri, that takes an array\nspecifying multiple brokers the agent can connect to. When multiple brokers\nare specified, it will use them in a failover capacity, where if it's unable\nto connect to one it will try the next in the list, and repeat until a\nsuccessful connection is made. In the event of a disconnect, the agent will\nretry that connection before trying a new broker.\n\n**broker-ws-proxy (optional)**\n\nProxy URI for websocket connection with PCP broker. \n\n**master-uris (optional)**\n\nAn array of HTTPS URIs of servers hosting task files for download. When multiple\nare specified, it will use them in a failover capacity, where if it's unable\nto connect to one it will try the next in the list until all have been tried.\nIf all are unavailable, task download will fail.\n\n**master-proxy (optional)**\n\nProxy URI for downloading tasks from master. \n\n**pcp-version (optional)**\n\nSpecifies whether to use PCP version 1 or 2. Only accepts '1' or '2'. Defaults to '1'.\n\n**connection-timeout (optional)**\n\nMaximum amount of time that may elapse when trying to establish a connection to\nthe broker in seconds. Defaults to 5 seconds.\n\n**ssl-ca-cert (required to connect)**\n\nThe location of your SSL Certificate Authority certificate, example\n/etc/puppet/ssl/ca/ca_crt.pem\n\n**ssl-cert (required to connect)**\n\nThe location of the pxp-agent SSL certificate, example /etc/puppet/ssl/certs/bob_crt.pem\n\n**ssl-key (required to connect)**\n\nThe location of the pxp-agent's SSL private key, example /etc/puppet/ssl/certs/bob_key.pem\n\n**ssl-crl (required for apply module)**\n\nThe location of the pxp-agent's SSL certificate revocation list, example /etc/puppetlabs/puppet/ssl/crl.pem\n\n**logfile (optional)**\n\nThe path of the log file.\n\n**loglevel (optional)**\n\nSpecify one of the following logging levels: *none*, *trace*, *debug*, *info*,\n*warning*, *error*, or *fatal*; the default one is *info*\n\n**log-pcp-access (optional flag)**\n\nEnable PCP access logging; the default is *false*.\n\n**pcp-access-logfile (optional)**\n\nThe path of the PCP access log file.\n\n**modules-dir (optional)**\n\nSpecify the directory where modules are stored\n\n**modules-config-dir (optional)**\n\nSpecify the directory containing the configuration files of modules\n\n**spool-dir (optional)**\n\nThe location where the outcome of non-blocking requests will be stored; the\ndefault location is:\n - \\*nix: */opt/puppetlabs/pxp-agent/spool*\n - Windows: *C:\\ProgramData\\PuppetLabs\\pxp-agent\\var\\spool*\n\nNote that if the specified spool directory does not exist, pxp-agent will create\nit when starting.\n\n**spool-dir-purge-ttl (optional)**\n\nAutomatically delete results subdirectories located in the `spool-dir` directory\nthat have a `start` timestamp that has expired in respect to the specified TTL.\nThe TTL value must be an integer with one of the following suffixes:\n - 'm' - minutes\n - 'h' - hours\n - 'd' - days\n\nThe default TTL value is \"14d\" (14 days). Specifying a 0, with any of the above\nsuffixes, will disable the purge functionality. Note that the purge will take\nplace when pxp-agent starts and will be repeated every hour or TTL, whichever\nis shorter.\n\n**task-cache-dir (optional)**\n\nThe location where the tasks are cached; the default location is:\n - \\*nix: */opt/puppetlabs/pxp-agent/tasks-cache*\n - Windows: *C:\\ProgramData\\PuppetLabs\\pxp-agent\\tasks-cache*\n\nNote that if the specified task-cache directory does not exist, pxp-agent will\ncreate it when starting. It will also be recreated before attempting to download\na task to it in case it was deleted without restarting pxp-agent.\n\n**task-cache-dir-purge-ttl (optional)**\n\nAutomatically delete cached tasks located in the `task-cache-dir` directory\nthat have a `start` timestamp that has expired in respect to the specified TTL.\nThe TTL value must be an integer with one of the following suffixes:\n - 'm' - minutes\n - 'h' - hours\n - 'd' - days\n\nThe default TTL value is \"14d\" (14 days). Specifying a 0, with any of the above\nsuffixes, will disable the purge functionality. Note that the purge will take\nplace when pxp-agent starts and will be repeated every hour or TTL, whichever\nis shorter.\n\n**foreground (optional flag)**\n\nDon't become a daemon and execute on foreground on the associated terminal.\n\n**pidfile (optional; only on *nix platforms)**\n\nThe path of the PID file; the default is */var/run/puppetlabs/pxp-agent.pid*\n\n## Contributing\n\nPlease refer to [this][contributing] document.\n\n[cpp-pcp-client]: https://github.com/puppetlabs/cpp-pcp-client\n[leatherman]: https://github.com/puppetlabs/leatherman\n[nssm]: https://nssm.cc\n[modules_docs]: https://github.com/puppetlabs/pxp-agent/blob/master/modules/README.md\n[pcp-broker]: https://github.com/puppetlabs/pcp-broker\n[pcp_specs_root]: https://github.com/puppetlabs/pcp-specifications/blob/master/pcp/versions/1.0/README.md\n[pxp-module-puppet_docs]: https://github.com/puppetlabs/pxp-agent/blob/master/lib/tests/resources/modules/reverse_valid\n[pxp-module-puppet_script]: https://github.com/puppetlabs/pxp-agent/blob/master/modules/pxp-module-puppet.md\n[pxp_specs_actions]: https://github.com/puppetlabs/pcp-specifications/blob/master/pxp/versions/1.0/actions.md\n[pxp_specs_request_response]: https://github.com/puppetlabs/pcp-specifications/blob/master/pxp/versions/1.0/request_response.md\n[pxp_specs_root]: https://github.com/puppetlabs/pcp-specifications/blob/master/pxp/versions/1.0/README.md\n[pxp_specs_transaction_status]: https://github.com/puppetlabs/pcp-specifications/blob/master/pxp/versions/1.0/transaction_status.md\n[websocketpp]: https://github.com/zaphoyd/websocketpp\n[MinGW-w64]: http://mingw-w64.sourceforge.net/\n[Chocolatey]: https://chocolatey.org\n[CMake-choco]: https://chocolatey.org/packages/cmake\n[7zip-choco]: https://chocolatey.org/packages/7zip.commandline\n[MinGW-w64-choco]: https://chocolatey.org/packages/mingw\n[Boost-download]: http://sourceforge.net/projects/boost/files/latest/download\n[contributing]: CONTRIBUTING.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fpxp-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpuppetlabs%2Fpxp-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fpxp-agent/lists"}