{"id":15156689,"url":"https://github.com/puppetlabs/puppetlabs-satellite_pe_tools","last_synced_at":"2025-06-12T00:39:09.702Z","repository":{"id":30150107,"uuid":"33700315","full_name":"puppetlabs/puppetlabs-satellite_pe_tools","owner":"puppetlabs","description":null,"archived":false,"fork":false,"pushed_at":"2024-10-17T14:50:08.000Z","size":341,"stargazers_count":2,"open_issues_count":4,"forks_count":15,"subscribers_count":98,"default_branch":"main","last_synced_at":"2025-01-30T00:23:35.677Z","etag":null,"topics":["hacktoberfest","module","supported"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/puppetlabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"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":"2015-04-10T00:50:53.000Z","updated_at":"2024-07-22T13:21:38.000Z","dependencies_parsed_at":"2024-03-13T15:56:07.523Z","dependency_job_id":"3b42380f-677b-4f54-a6b1-dbc3cc2d1bd5","html_url":"https://github.com/puppetlabs/puppetlabs-satellite_pe_tools","commit_stats":{"total_commits":251,"total_committers":45,"mean_commits":"5.5777777777777775","dds":0.8167330677290836,"last_synced_commit":"ea51a7ef58bc762f8a0a97e5895fe7a844cff2e3"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-satellite_pe_tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-satellite_pe_tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-satellite_pe_tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-satellite_pe_tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/puppetlabs","download_url":"https://codeload.github.com/puppetlabs/puppetlabs-satellite_pe_tools/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237181508,"owners_count":19268050,"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":["hacktoberfest","module","supported"],"created_at":"2024-09-26T19:40:56.161Z","updated_at":"2025-02-04T19:31:05.955Z","avatar_url":"https://github.com/puppetlabs.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# satellite_pe_tools\n\n#### Table of Contents\n\n1. [Description](#description)\n2. [Setup - The basics of getting started with satellite_pe_tools](#setup)\n    * [Setup requirements](#setup-requirements)\n    * [Beginning with satellite_pe_tools](#beginning-with-satellite_pe_tools)\n3. [Usage - Configuration options and additional functionality](#usage)\n4. [Reference - An under-the-hood peek at what the module is doing and how](#reference)\n5. [Limitations - OS compatibility, etc.](#limitations)\n6. [License](#license)\n7. [Development - Guide for contributing to the module](#development)\n\n## Description\n\nThe `satellite_pe_tools` module configures Puppet's report processor and facts indirector to allow you to send Puppet reports and facts to your Red Hat Satellite server.\n\n## Setup\n\n### Setup requirements\n\nThis module requires Red Hat Satellite 6.13 and Puppet Enterprise (PE) 2021.7.4 or later.\n\n### Beginning with satellite_pe_tools\n\n1. [Classify Puppet servers](#classify-puppet-servers)\n2. [Set Puppet server facts terminus](#set-puppet-server-facts-terminus)\n3. [Allow Puppet server to send data to Satellite](#allow-puppet–server-to-send-data-to-satellite)\n4. [Allow Puppet server to verify Satellite server identity](#allow-puppet-server-to-verify-satellite-server-identity)\n5. [Allow Satellite server to verify Puppet server identity](#allow-satellite-server-to-verify-puppet-server-identity)\n6. [Enable pluginsync and reports in Puppet](#enable-pluginsync-and-reports-in-puppet)\n\nTo set up communication between Satellite and your Puppet servers, follow these steps:\n\n1. Classify Puppet servers\n\n   Add the `satellite_pe_tools` class to the PE server node group in the PE Console. For details on adding classes to node groups, see the [Puppet Enterprise documentation](https://docs.puppet.com/pe/latest/console_classes_groups.html#adding-classes-to-a-node-group).\n\n2. Set Puppet server facts terminus\n\n   In the PE server node group in the PE Console, add the `facts_terminus`\nparameter to the `puppet_enterprise::profile::server` class with a string value of 'satellite'. This sets Puppet runs on your Puppet servers to forward the facts to Satellite.\n\n3. Allow the Puppet server to verify the Satellite server's identity\n\n   To use SSL verification so that the Puppet server can verify the Satellite server (to prevents man-in-the-middle attacks), the Certificate Authority (CA) certificate that signed the Satellite server's SSL certificate must be available on the Puppet server.\n\n   By default, the CA certificate is located on the Satellite CA server. On Red Hat-based systems, this is automatically managed by the module. Note that the CA cert is transferred over an untrusted SSL connection. If you wish to transfer the cert manually, see below. You must also set the `manage_default_ca_cert` parameter to `false`.\n\n   On non-Red Hat systems, or if you wish to manually transfer the cert, copy the file `/etc/pki/katello/certs/katello-default-ca.crt` from the Satellite CA server to `/etc/puppetlabs/puppet/ssl/ca/katello-default-ca.crt` on each Puppet server. If you place the certificate in a different location or give it a different name, you must set the `ssl_ca` parameter for the `satellite_pe_tools` class to the file path of the CA certificate.\n\n   If the Satellite SSL certificate is signed by a remote CA, copy the remote CA's certificate to each Puppet server, and then set the `ssl_ca` parameter for the `satellite_pe_tools` class to the file path of the CA certificate.\n\n   If you do not wish to verify the identity of the Satellite server, you can set the [`verify_satellite_certificate`](#verify_satellite_certificate) parameter for the `satellite_pe_tools` class to `false`.\n\n4. Allow the Satellite server to verify the Puppet server's identity\n\n   By default, Satellite is configured to verify the SSL identity of the PE servers connecting to it. If the PE report processor and facts indirector are not using a certificate signed with the Satellite server's CA, the verification fails.\n\n   To use SSL verification so that the Satellite server can verify the Puppet server, you must generate a SSL cert and key pair on the Satellite server, and then copy these files to your Puppet server.\n\n\u003e Note: In the following steps, replace `puppet.example.com` with the FQDN of your Puppet server.\n\na. On the Satellite server, run the following command:\n\n```\ncapsule-certs-generate --capsule-fqdn \"puppet.example.com\" \\\n--certs-tar \"~/puppet.example.com-certs.tar\"\n```\n\u003e Note: Use `--foreman-proxy-fqdn` instead of `--capsule-fqdn` for Satellite 6.3\n\nb. Untar the newly created file:\n\n```\ntar -xvf ~/puppet.example.com-certs.tar\n```\n\nThis creates a new folder: `~/ssl-build`. This may contain either raw `.crt` and `.key` file, or a number of RPM files.\n\nc. If the ssl-build folder contains RPM files for the host, find and extract the contents of the puppet-client rpm file:\n\n```\ncd ~/ssl-build/puppet.example.com\nrpm2cpio puppet.example.com-puppet-client-1.0-1.noarch.rpm | cpio -idmv\n```\n\nThis creates a folder structure in the current directory beginning with `./etc/pki/katello-certs-tools/`\n\nd. Copy the `.crt` and `.key` files to your Puppet server, found either at:\n\n`~/ssl-build/puppet.example.com/puppet.example.com-puppet-client.crt`\n\n`~/ssl-build/puppet.example.com/puppet.example.com-puppet-client.key`\n\nOr if you had to extract them from the RPM: \n   `~/ssl-build/puppet.example.com/etc/pki/katello-certs-tools/certs/puppet.example.com-puppet-client.crt`\n     `~/ssl-build/puppet.example.com/etc/pki/katello-certs-tools/private/puppet.example.com-puppet-client.key`\n\nCopy the files to `/etc/puppetlabs/puppet/ssl/satellite`.\n\ne. On your Puppet server, set the ownership of these two files to `pe-puppet`:\n\n\nExample (adjust paths and filenames accordingly):\n\n```\nchown pe-puppet /etc/puppetlabs/puppet/ssl/satellite/puppet.example.com-puppet-client.crt\nchown pe-puppet /etc/puppetlabs/puppet/ssl/satellite/puppet.example.com-puppet-client.key\n```\n\nf. In the Satellite UI, go to *Administer -\u003e Settings -\u003e Auth* and set the `restrict_registered_smart_proxies` parameter to `Yes`. Additionally, add your Puppet server's FQDN to the `trusted_hosts` array on the same page; for example, `[puppet.example.com]`.\n\n`trusted_hosts` has been given the label \"Trusted hosts\" in the UX. You can see the actual setting names by mousing over the label.\n\ng. Set the `ssl_cert` and `ssl_key` parameters in your `satellite_pe_tools` class to the location on your Puppet server of the two files respectively.\n\nIf you do not want the Satellite server to verify the Puppet server identity, then in the Satellite UI, go to *Administer -\u003e Settings -\u003e Auth* and set the `restrict_registered_smart_proxies` parameter to `No`.\n\nNote that this setting presents a security risk. False reports and facts can be sent to Satellite by a malicious system masquerading as a current Puppet server on your infrastructure that's been added to Satellite as a safe server.\n\n5. Configure Satellite Service to onboading hosts\nTo onboard a host to the Satellite server, you will need to configure an activation key and two global variables:\n`puppet_server= Puppet Master FQDN` \n`enable-puppet7=true`.\n*Activation Key*\n```\nhammer --username \u003cusername\u003e --password \u003cpassword\u003e activation-key create --name \u003cactivation-key-name\u003e --unlimited-hosts --description 'Example Stack in the Development Environment' --lifecycle-environment 'Library' --content-view 'Default Organization View' --organization-label \u003corganization_label_name\u003e\n```\n*Global Parameters*\n```\nhammer --username admin --password puppetlabs global-parameter set --name puppet_server --value \u003cPuppet-Server-FQDN\u003e\nhammer --username admin --password puppetlabs global-parameter set --name enable-puppet7 --value true\n```\n\n6. Enable reports in Puppet\n\nOn each Puppet agent, make sure the [`report`](https://www.puppet.com/docs/puppet/7/reporting_about.html) setting is enabled. This setting is usually enabled by default.\n\n        [agent]\n        report = true\n\n## Usage\n\n~~~puppet\nclass {'satellite_pe_tools':\n  satellite_url                =\u003e \"https://puppet.example.com\",\n  verify_satellite_certificate =\u003e true,\n}\n~~~\n\nThis example tells the Puppet server the location of the Satellite server (`https://puppet.example.com`) and instructs it to verify the Satellite server's identity.\n\n## Debugging\n\nIn addition to the reports in the Puppet Enterprise Console, the Satellite API log and the Puppet server log can help you debug issues.\n\nThe Satellite API log file is located at `/var/log/httpd/foreman-ssl_access_ssl.log` on your Satellite server.\n\nAn example of a SSL authentication failure (note the '403'):\n\n```puppet\n10.32.125.164 - - [03/Oct/2015:16:06:19 -0700] \"POST /api/reports HTTP/1.1\" 403 58 \"-\" \"Ruby\"\n```\n\nAn example of a sucessful SSL authentication (note the '201'):\n\n```puppet\n10.32.125.164 - - [03/Oct/2015:16:06:00 -0700] \"POST /api/reports HTTP/1.1\" 201 554 \"-\" \"Ruby\"\n```\n\nThe Puppet server log file is located at `/var/log/puppetlabs/puppetserver/puppetserver.log` on your Puppet server. \n\nAn example of a DH PARAMETER failure:\n\n```puppet\n2018-03-04 15:16:17,161 ERROR [qtp1111094392-103] [puppetserver] Puppet Could not send report to Satellite: Could not generate DH keypair\n```\n\nYou can resolve this error by adding a DH PARAMETER block to the custom certificate on the Satellite server.\n\n```bash\nopenssl dhparam 1024 \u003e\u003e /etc/pki/katello/certs/katello-apache.crt\nsatellite-maintain restart\n```\n\n## Reference\nFor information on the classes and types, see the [REFERENCE.md](https://github.com/puppetlabs/puppetlabs-satellite_pe_tools/blob/main/REFERENCE.md)\n\n## Limitations\n\nThe `satellite_pe_tools` module requires Red Hat Satellite 6.2 and Puppet Enterprise 2016.4 or later. \n\nFor an extensive list of supported operating systems, see [metadata.json](https://github.com/puppetlabs/puppetlabs-satellite_pe_tools/blob/main/metadata.json)\n\n## License\n\nThis codebase is licensed under the Apache2.0 licensing, however due to the nature of the codebase the open source dependencies may also use a combination of [AGPL](https://opensource.org/license/agpl-v3/), [BSD-2](https://opensource.org/license/bsd-2-clause/), [BSD-3](https://opensource.org/license/bsd-3-clause/), [GPL2.0](https://opensource.org/license/gpl-2-0/), [LGPL](https://opensource.org/license/lgpl-3-0/), [MIT](https://opensource.org/license/mit/) and [MPL](https://opensource.org/license/mpl-2-0/) Licensing.\n\n## Development\n\nThis module was built by Puppet specifically for use with Puppet Enterprise (PE).\n\nIf you run into an issue with this module, or if you would like to request a feature, please [file a ticket](https://tickets.puppet.com/browse/MODULES/).\n\nIf you are having problems getting this module up and running, please [contact Support](http://puppet.com/services/customer-support).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fpuppetlabs-satellite_pe_tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpuppetlabs%2Fpuppetlabs-satellite_pe_tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fpuppetlabs-satellite_pe_tools/lists"}