Forge Home

Modules

Puppet

Resources

PuppetEcosystemPuppet CommunityUpdates

libreswan

Manages IPSec VPN Tunnels
Project URLRSS FeedReport issues

14,652 downloads

75 latest version

5.0 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 3.10.0 (latest)
  • 3.8.0
  • 3.7.0
  • 3.6.0
  • 3.5.0
  • 3.4.2
  • 3.4.1
  • 3.4.0
  • 3.3.0
  • 3.2.1
  • 3.2.0
  • 3.1.1
  • 3.1.0
  • 3.0.2
  • 3.0.1
  • 3.0.0
  • 0.1.2
  • 0.1.1
released Sep 16th 2024
This version is compatible with:
  • Puppet Enterprise 2023.8.x, 2023.7.x, 2023.6.x, 2023.5.x, 2023.4.x, 2023.3.x, 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x
  • Puppet >= 7.0.0 < 9.0.0
  • , , , ,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'simp-libreswan', '3.10.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add simp-libreswan
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install simp-libreswan --version 3.10.0

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download
Tags: ipsec, pki, simp

Documentation

simp/libreswan — version 3.10.0 Sep 16th 2024

License CII Best Practices Puppet Forge Puppet Forge Downloads Build Status

Table of Contents

Overview

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

This is a SIMP module

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.

This module is optimally designed for use within a larger SIMP ecosystem, but it can be used independently:

  • When included within the SIMP ecosystem, security compliance settings will be managed from the Puppet server.
  • If used independently, all SIMP-managed security subsystems are disabled by default and must be explicitly opted into by administrators. Please see parameters mapped to simp_options::* items in init.pp for details.

Module Description

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.

Beginning with ipsec

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

Setup

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

Defaults

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

Configure the IPSEC service

Add the following to hiera:

---
simp_options::pki: true
simp_options::trusted_nets : <desired client nets>

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/

Setting up an IPSEC connection.

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.

Reference

See REFERENCE.md

Development

Please read our Contribution Guide.

Unit tests

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

bundle exec rake spec

Acceptance tests

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.