• Overview
• This is a SIMP module
• Breaking changes in 5.0.0
  • Path 1: opt in per-parameter
  • Path 2: bulk restore via the simp:defaults compliance_engine profile
• Module Description
• Beginning with ipsec
• Setup
  • Defaults
  • Configure the IPSEC service
  • Setting up an IPSEC connection.
• > delete it from the directory automatically.
• Reference
• Development
  • Unit tests
  • Acceptance tests

This module installs and configures Libreswan, an implementation of the VPN protocol, which supports IPSEC and IKE.

This module is a component of the System Integrity Management Platform, a compliance-management framework built on Puppet.

If you find any issues, they can be submitted to our JIRA.

Please read our Contribution Guide.

include libreswan is now safe to apply on a system that already has libreswan configured. A bare include installs the libreswan package and nothing else. The following used to happen automatically before 5.0.0 and now do not:

• /etc/ipsec.conf is no longer written from a template. Individual fields are managed in place with file_line, but only for the parameters you set.
• The five policy files under /etc/ipsec.d/policies/ are no longer written.
• The ipsec service is no longer enabled or started.
• Firewall rules (IKE/NAT-T/ESP/AH) are no longer declared.
• The PKI subsystem and NSS database wiring are no longer configured.
• haveged is no longer included.
• The NSS helper scripts under /usr/local/scripts/nss/ are no longer installed by a bare include. They are still installed automatically by libreswan::nss::init_db.
• Ownership and permissions are no longer forced on /etc/ipsec.conf (was root/0400), the ipsecdir (was root/0700), or the dumpdir (was root/0700) — the package-provided values are left alone. Set libreswan::manage_file_permissions: true to restore the old enforcement (the simp:defaults profile does).
• The secretsfile line is no longer written to ipsec.conf (same as ipsecdir/nssdir): the parameter default matches the package default, so the operational path is unchanged.
• The simp_options::* feature toggles (simp_options::firewall, simp_options::pki, simp_options::haveged) are no longer consulted — enabling those subsystems now requires the corresponding libreswan::* parameter. The data lookups (simp_options::trusted_nets, simp_options::fips) are still honored, since they only shape behavior you have already opted in to (firewall rules and NSS/PKI respectively) and declare nothing by themselves.

There are two ways to restore any subset of the old behavior.

Set the specific libreswan::* parameters you want managed. The module's behavior is now driven entirely by which parameters you provide. For example:

---
libreswan::service_ensure: running
libreswan::service_enable: true
libreswan::firewall:       true
libreswan::trusted_nets:   ['<desired client nets>']
libreswan::pki:            simp
libreswan::haveged:        true
libreswan::plutodebug:     'none'
libreswan::protostack:     'netkey'

classes:
  - 'libreswan'

Only the fields you list are written to /etc/ipsec.conf. To remove a previously-managed field, list its key in libreswan::purge_settings — using the name as it appears in the file (hyphenated, e.g. virtual-private, not virtual_private). To remove a policy file, list its name in libreswan::purge_policies.

For SIMP sites that want pre-5.0.0 behavior wholesale, the module ships a simp:defaults profile under SIMP/compliance_profiles/. Activating it restores: service running+enabled, the five hardcoded ipsec.conf fields (protostack, dumpdir, plutodebug, virtual_private, private_clear_cidrs), the five policy files, firewall, PKI ('simp' mode), haveged, the NSS helper scripts, and the pre-5.0.0 file ownership/permission enforcement (manage_file_permissions).

To activate, install the simp-compliance_engine gem (it provides a Hiera backend) and set:

---
compliance_engine::enforcement:
  - simp:defaults

classes:
  - 'libreswan'

The profile values resolve below your site's explicit Hiera entries (the exact position depends on where you place the compliance_engine level in your hiera.yaml), so explicit libreswan::* keys always win and you can layer the bulk restore with targeted opt-outs.

The profile is opinionated for SIMP sites — in particular it enables firewall, PKI, and haveged unconditionally. Pre-5.0.0, those subsystems followed the simp_options::firewall/simp_options::pki/ simp_options::haveged Hiera keys; those keys are no longer consulted, so a site that had them set to false must opt out with the libreswan::* keys instead:

---
compliance_engine::enforcement:
  - 'simp:defaults'

# Targeted opt-outs — explicit site Hiera beats the profile:
libreswan::firewall: false
libreswan::haveged: false
# The profile sets pki to 'simp' (include the `pki` class and copy certs).
# If your site used `simp_options::pki: true` (manually-supplied certs,
# no `pki` class), set that mode explicitly:
libreswan::pki: true

Non-SIMP adopters should use Path 1 with only the parameters they actually want.

Note (behavior since 4.0.0): on EL9+ the NSS database directory (libreswan::nssdir) follows the libreswan >= 4 package default, /var/lib/ipsec/nss (EL8 keeps the legacy /etc/ipsec.d). When PKI management is enabled, the NSS database is initialized at that path if no database exists there; a pre-existing database under /etc/ipsec.d is left in place, unmanaged. Override libreswan::nssdir if you need the legacy location on EL9+.

This module installs the libreswan IPSEC service. IPSEC is Internet Protocol SECurity. It uses strong cryptography to provide both authentication and encryption services.

This module installs the most recently RedHat approved version of libreswan, currently 3.15. It will configure the IPSEC daemon using the most up to date defaults and, if you are using SIMP, manage your certificates. Connections can be managed through the puppet modules or by hand.

Before installing pupmod-simp-libreswan, make sure you read the libreswan documentation thoroughly. After reading the introduction, select the Main Wiki Page link to get to the user documentation.

• All ipsec.conf options can be found in ipsec.conf(5).

• Ensure the libreswan and NSS packages are available.

Before installing pupmod-simp-libreswan, make sure you read the libreswan documentation thoroughly. After reading the introduction, select the Main Wiki Page link to get to the user documentation.

• IPSEC configuration file: /etc/ipsec.conf
• Configuration directory: /etc/ipsec.d/
• NSS database (containing peer certs and the CA): /etc/ipsec.d/[key4.db,cert9.db,pkcs11.txt]
• Policy files (clear, private): /etc/ipsec.d/policies/
• Secrets files (secret or key used by ipsec): /etc/ipsec.d/*.secrets
• Connection files (tunnel configurations): /etc/ipsec.d/*.conf
• Log file: /var/log/secure
• Libreswan starts an "ipsec" service, but it is listed as "pluto" in the process list.

See Breaking changes in 5.0.0 for the two ways to opt in to configuration management.

A minimal hiera example that actually configures something:

---
libreswan::service_ensure: running
libreswan::service_enable: true
libreswan::firewall:       true
libreswan::trusted_nets:   ['<desired client nets>']
libreswan::pki:            true

# Individual ipsec.conf fields you want managed:
libreswan::plutodebug: 'none'
libreswan::uniqueids:  'yes'

classes:
  - 'libreswan'

Make sure that you have all Certificate Authorities needed loaded into SIMP. If the side you are connecting to uses a different CA from yours, make sure you load their CA into your CA listing in PKI.
(See the SIMP documentation to see how to do this.)

You can verify the contents of the NSS database with:

certutil -L -d sql:/etc/ipsec.d/

To add a connection via puppet, create a definition file under the site manifest. A simple VPN tunnel host to host example is given here, named ipsec_tunne1.pp:

class site::ipsec_tunne1 {
  include 'libreswan'

  libreswan::connection{ 'default':
    leftcert      => $facts['fqdn'],
    left          => $facts['ipaddress'],
    leftrsasigkey => '%cert',
    leftsendcert  => 'always',
    authby        => 'rsasig'
  }

  libreswan::connection{ 'outgoing' :
     right          => '<the IP Address of the client you are connecting to.>'
     rightrsasigkey => '%cert',
     notify         => Service['ipsec'],
     auto           => 'start'
  }
}

This will add two files to the ipsec directory, default.conf and outgoing.conf. These are the connection files that will be used by the libreswan daemon.

NOTE: If you delete a connection from the site manifest, it will not delete it from the directory automatically.

See REFERENCE.md

Please read our Contribution Guide.

Unit tests, written in rspec-puppet can be run by calling:

bundle exec rake spec

To run the system tests, you need Vagrant installed. Then, run:

bundle exec rake beaker:suites

Some environment variables may be useful:

BEAKER_debug=true
BEAKER_provision=no
BEAKER_destroy=no
BEAKER_use_fixtures_dir_for_modules=yes

• BEAKER_debug: show the commands being run on the STU and their output.
• BEAKER_destroy=no: prevent the machine destruction after the tests finish so you can inspect the state.
• BEAKER_provision=no: prevent the machine from being recreated. This can save a lot of time while you're writing the tests.
• BEAKER_use_fixtures_dir_for_modules=yes: cause all module dependencies to be loaded from the spec/fixtures/modules directory, based on the contents of .fixtures.yml. The contents of this directory are usually populated by bundle exec rake spec_prep. This can be used to run acceptance tests to run on isolated networks.