satellite_pe_tools

Table of Contents

1. Description
2. Setup - The basics of getting started with satellite_pe_tools
   • Setup requirements
   • Beginning with satellite_pe_tools
3. Usage - Configuration options and additional functionality
4. Reference - An under-the-hood peek at what the module is doing and how
5. Limitations - OS compatibility, etc.
6. Development - Guide for contributing to the module

Description

The 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.

Setup

Setup requirements

This module requires Red Hat Satellite 6.2 and Puppet Enterprise (PE) 2016.4 or later.

Beginning with satellite_pe_tools

1. Classify Puppet servers
2. Set Puppet server facts terminus
3. Allow Puppet server to send data to Satellite
4. Allow Puppet server to verify Satellite server identity
5. Allow Satellite server to verify Puppet server identity
6. Enable pluginsync and reports in Puppet

To set up communication between Satellite and your Puppet servers, follow these steps:

1. Classify Puppet servers

   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.

2. Set Puppet server facts terminus

   In the PE server node group in the PE Console, add the facts_terminus parameter 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.

3. Allow the Puppet server to verify the Satellite server's identity

   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.

   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.

   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.

   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.

   If you do not wish to verify the identity of the Satellite server, you can set theverify_satellite_certificate parameter for the satellite_pe_tools class to false.

4. Allow the Satellite server to verify the Puppet server's identity

   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.

   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.

Note: In the following steps, replace puppet.example.com with the FQDN of your Puppet server.

a. On the Satellite server, run the following command:

capsule-certs-generate --capsule-fqdn "puppet.example.com" \
--certs-tar "~/puppet.example.com-certs.tar"

Note: Use --foreman-proxy-fqdn instead of --capsule-fqdn for Satellite 6.3

b. Untar the newly created file:

tar -xvf ~/puppet.example.com-certs.tar

This creates a new folder: ~/ssl-build. This may contain either raw .crt and .key file, or a number of RPM files.

c. If the ssl-build folder contains RPM files for the host, find and extract the contents of the puppet-client rpm file:

cd ~/ssl-build/puppet.example.com
rpm2cpio puppet.example.com-puppet-client-1.0-1.noarch.rpm | cpio -idmv

This creates a folder structure in the current directory beginning with ./etc/pki/katello-certs-tools/

d. Copy the .crt and .key files to your Puppet server, found either at:

~/ssl-build/puppet.example.com/puppet.example.com-puppet-client.crt

~/ssl-build/puppet.example.com/puppet.example.com-puppet-client.key

Or if you had to extract them from the RPM: ~/ssl-build/puppet.example.com/etc/pki/katello-certs-tools/certs/puppet.example.com-puppet-client.crt ~/ssl-build/puppet.example.com/etc/pki/katello-certs-tools/private/puppet.example.com-puppet-client.key

Copy the files to /etc/puppetlabs/puppet/ssl/satellite.

e. On your Puppet server, set the ownership of these two files to pe-puppet:

Example (adjust paths and filenames accordingly):

chown pe-puppet /etc/puppetlabs/puppet/ssl/satellite/puppet.example.com-puppet-client.crt
chown pe-puppet /etc/puppetlabs/puppet/ssl/satellite/puppet.example.com-puppet-client.key

f. In the Satellite UI, go to Administer -> Settings -> Auth and set the restrict_registered_smart_proxies parameter to true. Additionally, add your Puppet server's FQDN to the trusted_hosts array on the same page; for example, [puppet.example.com].

trusted_hosts has been given the label "Trusted hosts" in the UX. You can see the actual setting names by mousing over the label.

g. 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.

If you do not want the Satellite server to verify the Puppet server identity, then in the Satellite UI, go to Administer -> Settings -> Auth and set the restrict_registered_smart_proxies parameter to false.

Note 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.

5. Enable pluginsync and reports in Puppet

On each Puppet agent, make sure the pluginsync and report settings are enabled. These settings are usually enabled by default.

    [agent]
    report = true
    pluginsync = true

Usage

class {'satellite_pe_tools':
  satellite_url                => "https://puppet.example.com",
  verify_satellite_certificate => true,
}

This 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.

Debugging

In addition to the reports in the Puppet Enterprise Console, the Satellite API log and the Puppet server log can help you debug issues.

The Satellite API log file is located at /var/log/httpd/foreman-ssl_access_ssl.log on your Satellite server.

An example of a SSL authentication failure (note the '403'):

10.32.125.164 - - [03/Oct/2015:16:06:19 -0700] "POST /api/reports HTTP/1.1" 403 58 "-" "Ruby"

An example of a sucessful SSL authentication (note the '201'):

10.32.125.164 - - [03/Oct/2015:16:06:00 -0700] "POST /api/reports HTTP/1.1" 201 554 "-" "Ruby"

The Puppet server log file is located at /var/log/puppetlabs/puppetserver/puppetserver.log on your Puppet server.

An example of a DH PARAMETER failure:

2018-03-04 15:16:17,161 ERROR [qtp1111094392-103] [puppetserver] Puppet Could not send report to Satellite: Could not generate DH keypair

You can resolve this error by adding a DH PARAMETER block to the custom certificate on the Satellite server.

openssl dhparam 1024 >> /etc/pki/katello/certs/katello-apache.crt
satellite-maintain restart

Reference

For information on the classes and types, see the REFERENCE.md

Limitations

The satellite_pe_tools module requires Red Hat Satellite 6.2 and Puppet Enterprise 2016.4 or later.

For an extensive list of supported operating systems, see metadata.json

Development

This module was built by Puppet specifically for use with Puppet Enterprise (PE).

If you run into an issue with this module, or if you would like to request a feature, please file a ticket.

If you are having problems getting this module up and running, please contact Support.

Reference

Table of Contents

Classes

• satellite_pe_tools: This module provides and configures a report processor to send puppet agent reports to a Satellite server

Functions

• parse_url
• to_yaml

Plans

• satellite_pe_tools::test_01_provision
• satellite_pe_tools::test_02_server_setup
• satellite_pe_tools::test_03_test_run

Classes

satellite_pe_tools

This module provides and configures a report processor to send puppet agent reports to a Satellite server

Examples

class { 'satellite_pe_tools':
  satellite_url => 'https://satellite.example.domain',
  ssl_ca        => '/etc/puppetlabs/puppet/ssl/ca/katello-default-ca.crt',
  ssl_cert      => '/etc/puppetlabs/puppet/ssl/certs/satellite-server.example.domain.pem',
  ssl_key       => '/etc/puppetlabs/puppet/ssl/private_keys/puppet.domain.com.pem',
}

Parameters

The following parameters are available in the satellite_pe_tools class:

• satellite_url
• verify_satellite_certificate
• ssl_ca
• ssl_cert
• ssl_key
• manage_default_ca_cert

satellite_url

Data type: String

The full URL to the satellite server in format https://url.to.satellite

verify_satellite_certificate

Data type: Boolean

When set to false, allows the Satellite server to present an unsigned, unrecognized, or invalid SSL certificate. This creates the risk of a host falsifying its identity as the Satellite server. Valid values: true, false.

Default value: true

ssl_ca

Data type: Optional[String[1]]

The file path to the CA certificate used to verify the satellite server identitity. If not provided, the local Puppet Enterprise server's CA is used.

Default value: undef

ssl_cert

Data type: Optional[String[1]]

The file path to the certificate signed by the Satellite CA. It's used for Satellite to verify the identity of the Puppet Enterprise server

Default value: undef

ssl_key

Data type: Optional[String[1]]

The file path to the key for the Puppet Enterprise server generated by Satellite

Default value: undef

manage_default_ca_cert

Data type: Boolean

Applicable to Red Hat-based systems only. When set to true, the module transfers the Satellite server's default CA certificate from the Satellite server to the server. This uses an untrusted SSL connection.

Default value: true

Functions

parse_url

Type: Ruby 3.x API

The parse_url function.

parse_url()

The parse_url function.

Returns: Any This function parses a given URL and provides a hash of the parsed data.

to_yaml

Type: Ruby 3.x API

The to_yaml function.

to_yaml()

The to_yaml function.

Returns: Any This function takes a data structure and turns it into yaml

Plans

satellite_pe_tools::test_01_provision

The satellite_pe_tools::test_01_provision class.

satellite_pe_tools::test_02_server_setup

The satellite_pe_tools::test_02_server_setup class.

satellite_pe_tools::test_03_test_run

The satellite_pe_tools::test_03_test_run class.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

v4.2.0 - 2023-06-22

Full Changelog

Added

• pdksync - (MAINT) - Allow Stdlib 9.x #208 (LukasAud)

v4.1.0 - 2023-02-10

Full Changelog

Added

• (maint) Raise upper bound of stdlib #189 (david22swan)

Fixed

• (CONT-364) Syntax update #196 (LukasAud)

v4.0.2 - 2022-07-18

Full Changelog

Fixed

• (MAINT) Bump stdlib version #187 (chelnak)
• report processor: load utils via absolute path #180 (bastelfreak)

v4.0.1 - 2021-03-29

Full Changelog

Fixed

• Fix "Could not send report to Satellite: undefined method `each_value' for Puppet::Util::Metric" #160 (DavidS)

v4.0.0 - 2021-03-03

Full Changelog

Added

• pdksync - (feat) - Add support for Puppet 7 #142 (daianamezdrea)

Changed

• pdksync - Remove Puppet 5 from testing and bump minimal version to 6.0.0 #149 (carabasdaniel)

Fixed

• (IAC-1008) - Removal of Inappropriate Terminology #148 (david22swan)
• Update satellite.rb #139 (eppini)

v3.1.0 - 2019-12-10

Full Changelog

Added

• FM-8032 - add redhat8 support #112 (lionce)

v3.0.0 - 2019-05-17

Full Changelog

Added

• (FM-7937) Implement Puppet Strings #107 (carabasdaniel)

Changed

• pdksync - (MODULES-8444) - Raise lower Puppet bound #103 (david22swan)

2.3.0 - 2019-02-12

Full Changelog

Fixed

• Updated license terms #89 (turbodog)
• pdksync - (FM-7655) Fix rubygems-update for ruby < 2.3 #86 (tphoney)
• (FM-7529) - Updating metadata to reflect support #82 (pmcmaw)

2.2.0 - 2018-09-28

Full Changelog

Added

• pdksync - (MODULES-6805) metadata.json shows support for puppet 6 #75 (tphoney)

2.1.0 - 2018-07-05

Full Changelog

Fixed

• (FM-7080) - Making 2018.1 compatible #64 (pmcmaw)

2.0.0 - 2017-05-02

Full Changelog

Added

• (MODULES-4758) Update satellite for Puppet 4 #45 (eputnam)

1.0.1 - 2015-12-09

Full Changelog

Fixed

• Restart Puppet Server on config change #24 (ccaum)

1.0.0 - 2015-10-06

Full Changelog