Home

Awesome

pistrong

Simple, Secure Certificate-based authentication manager for the strongSwan VPN

Overview

pistrong dramatically simplifies installing and configuring the highly secure, high performance strongSwan IPSEC/IKEV2 VPN.

pistrong supports 3 different VPN server usage scenarios:

pistrong simplifies managing the strongSwan Certificate Authority (CA) and Certificates for remote user devices connecting to the VPN (Client/Server). pistrong fully supports the Cert-authenticated use case (users on devices), and can be used to create and manage certs for other strongSwan VPN scenarios, such as host-to-host or site-to-site tunnels, which can be easily configured with a provided tool.

The pistrong software package includes complete installation, configuration, and management support for Raspbian/RasPiOS and Debian-based distros. Other distros can be easily supported, since the only required changes are in the installer. Support for additional distros will be added based on inquiries.

Using pistrong, it's typically possible to have strongSwan up and running with clients securely connecting in less than an hour.

pistrong components include:

If you find pistrong useful, please consider starring this GitHub it so I can better understand how many people are using it. Thanks!

And, if you have questions, problems, or requests for enhancements, please open an issue on this github. I'm happy to help you get your VPN running.

Installation Videos

If you prefer to watch videos to learn, you'll find these interesting:

Debian Bullseye is out and stable, but some people are still running Buster. The strongSwan package in Buster is a bit old, so InstallPiStrong will download and install strongSwan from the source tarball. Watch this here. (Long wait times have been edited out of this video, so the 14-minute install on a Pi4 can be viewed in less than a minute.)

Up and Running Nearly Instantly!

Overview

Here are the steps you must complete to have a properly functioning VPN:

This README expands on these steps. You're more likely to be successful with your VPN if you read and understand the remainder of this document before starting.

How will your VPN be accessed from the Internet?

Before diving in, decide if you're going to use a DNS name (highly recommended!) for external VPN access. Your public DNS IP address can be static or dynamic, depending on your Internet connection or ISP. If you don't use a DNS name, then you'll need to use your external IP address to access the VPN. If you're planning to use an IP address, there are ramifications so please read the section below: Using an IP Address for VPN Access.

If you're going to use a DNS name, it's best to ensure this is properly set up before proceeding. If you don't have a static external IP address, you can use a dynamic DNS service such as www.dyn.com, www.noip.com, etc. NoIP, for example, provides a small Linux tool that will monitor your external IP address and if it changes, updates selected DNS names.

To access your VPN from outside your LAN, configure your router to forward UDP ports 500 and 4500 to the LAN IP address of your strongSwan server.

Install pistrong

Now that you've attended to the external network considerations, it's time to install and configure pistrong and strongSwan.

Download and run the installer on your local system:

sudo curl -L https://raw.githubusercontent.com/gitbls/pistrong/master/InstallPiStrong -o /usr/local/bin/InstallPiStrong
sudo chmod 755 /usr/local/bin/InstallPiStrong
sudo /usr/local/bin/InstallPiStrong

See Installation Log for a session log which is the result of installing and configuring pistrong and InstallPiStrong.

Create your CA

Use sudo makeMyCA to create a complete, secure, and ready-to-use CA for Android, iOS/macOS, Linux, and Windows clients. See below for details.

See makeMyCA log to see the configuration of a CA.

Create Certs for users

These examples assume the username is username, and are taking the default dev for the device name. You may find it simpler to use a meaningful name by adding --dev something which directs pistrong to add the string something to the name of this user. This is especially important if a user has multiple devices and you want to use a different cert on each device. Conversely, if a user's cert is going to be used across multiple devices, you don't need to use --dev, although you certainly can.

Create multiple certs for a user with multiple devices in the following manner. Note that the value provided to --dev is strictly for your use to keep track of different devices, so can be anything you want.

Once the certs for a client device or system have been created, you will install and configure the VPN on the client or device. Follow the OS-specific Cert installation instructions at Client Certificate Installation and VPN Configuration to install the Cert and configure the VPN.

Important IP Address Considerations

There are a couple of IP Address considerations that you should be aware of. These are due to the current IP routing implementation, and are under investigation.

For Client/Server VPNs (built with makeMyCA), The IP Address range for the VPN Server and the VPN Client must be different. By default many routers use 192.168.0.x or 192.168.1.x. If your VPN Client is on a LAN with the same IP Address range, you will be able to connect to the VPN, but will not be able to access any other hosts on the VPN Server LAN.

Similarly, for tunnels built with makeTunnel, the LANs on each end of a Site-to-Site tunnel can not be the same. For instance, both LANs can't be 192.168.1.0/24 networks.

However, the LANs on each end of a Host-to-Host tunnel CAN be the same, but the LAN IP addresses of the two VPN hosts must be different.

If your VPN Server LAN is a "common" IP Address range (.0.x, .1.x, etc), you should consider changing to a different, less commonly-used IP Address range to avoid this issue.

pistrong

Once strongSwan has been installed and configured, and the CA has been created, presumably using makeMyCA, use sudo pistrong to manage users. pistrong provides commands to manage the CA, add, revoke, delete, or list users, and simple strongSwan service management (start, stop, restart, enable, disable, status, and reload).

If you have a webserver and an email server installed locally or otherwise available, pistrong can send email to the user with a link to the certificates, and a separate email with the password for the certificate. See section below on Local Mail for a quick and easy way to install a local-only email on your system.

Example commands

InstallPiStrong

InstallPiStrong installs strongSwan, and downloads the remainder of the pistrong scripts. strongSwan can be installed in two different ways:

InstallPiStrong will display the version numbers of both, and ask you to choose which to install. The pros/cons of each method:

From apt package

From a source tarball

In general, unless you have a strong need for the latest/greatest, it's better to use the apt-provided packages, simply because of the install time and package management tools. But, both are supported, and pistrong works with both of them.

NOTE: If the version of strongSwan in your distro is less than 5.8.0, InstallPiStrong will not allow you to use the apt install.

When building from a source tarball, InstallPiStrong has several phases. If no phase is specified or all is the default, and all phases will be run. InstallPiStrong does not pause at the start of each phase. If you it to pause at the start of each phase, use allx as the command line argument. The phases include:

makeMyCA

makeMyCA builds a complete CA configured for use with Android, iOS/macOS, Linux, and Windows clients. makeMyCA prompts for all the configuration information and provides explanations of each item. makeMyCA will display the configuration information and ask if you want to continue to create the CA. In addition to the necessary Certs, makeMyCA also creates

Site-to-Site and Host-to-Host tunnels

Use sudo makeTunnel to configure Site-to-Site and Host-to-Host tunnels. You give each tunnel a name, which is used in the tunnel configuration files.

You'll also need the following configuration information:

Once all questions have been asked, makeTunnel will print the configuration information and ask if you want to continue.

After makeTunnel has completed, find the newly-generated tunnel file for the remote end in /etc/swanctl/pistrong/server-assets and copy it to the remote VPN system. On that system (which must also have pistrong installed), install the VPN configuration:

sudo pistrong client install Tunnel-tunnelname-remotename.zip

Once the configuration has been installed, start the VPN connection:

$ sudo pistrong client list
 remotename-Tunnel
$ sudo pistrong client start remotename

Site-to-Site and Host-to-Host tunnel IP Address restrictions

Reiterating, since mentioned above. The LANs on each end of a Site-to-Site tunnel can not be the same. For instance, both LANs can't be 192.168.1.0/24 networks.

The LANs on each end of a Host-to-Host tunnel CAN be the same, but the LAN IP addresses of the two VPN hosts must be different.

Starting a Site-To-Site Tunnel Automatically

It's easy to keep a site-to-site or host-to-host tunnel up and running using vpnmon (available on this github). Download vpnmon.service and vpnmon.sh to your system and then:

Generally, for any pair of tunnel endpoints, decide which will be the client (the one that initiates the VPN tunnel connection) and install vpnmon on that endpoint.

Resetting Everything

If you want to completely delete and reset the CA, you can do that relatively easily. This will completely invalidate all user certs!

Firewall Considerations

strongSwan requires changes to the Firewall on the VPN Server for proper operation. This is not required on the Linux VPN Client system, or any other client for that matter. In case you don't have a firewall installed, InstallPiStrong writes a new systemd service pistrong-iptables-load, which contains only the VPN-required Firewall rules. If you want to use this service, sudo systemctl enable pistrong-iptables-load before rebooting.

The minimal firewall rules are in /etc/swanctl/pistrong/CA-iptables. If your connection to the internet changes from what you specified in makeMyCA, you must sudoedit this file and change the network device (typically, eth0, but could be eth1) to the appropriate network adapter. There is no validity checking done on this by pistrong, and if it's incorrect, VPN traffic from remote clients will not be able to access the VPN Server's LAN.

Many users either have or want more than this very minimal firewall. In that case, the iptables rules in /etc/swanctl/pistrong/CA-iptables must be added to the Firewall rules for your system.

Hints

Security Considerations

For the most secure implementation, here are some things to consider:

Client Operating System Notes

Android

I have only tested Android using Lineage 17.1. Please report your experience with Android devices and pistrong!

iOS/macOS

There are no known issues using pistrong with iOS/macOS clients.

Linux

pistrong supports Linux Client devices connecting to the VPN. The easiest approach is to use strongSwan on the Linux client, and installing it via:

Windows

There are no known issues using pistrong with Windows clients.

Using an IP Address for VPN Access

While using a DNS name is the best way to access the VPN, that may not always be possible. pistrong makes using an Internet IP Address as painless as possible, but there are a few things to be aware of:

Tunnel Routing

A simple way to enable LAN clients to utilize the tunnel is to add a route to the remote server's IP address(es) to the router. It does cause outgoing traffic to hit the router twice, which may be a consideration on a heavily-utilized tunnel. It's easy to add routes to Linux clients, which can be used to ameliorate the router impact.

Sending Mail

If you want to send email to a user with their cert information, there are two approaches. You can either send it using your gmail or Outlook.com (or other Internet or ISP) email account, or you can set up your own local mail server.

Sending using gmail or Outlook.com

To send with gmail, perform these configuration steps:

To send with Outlook.com, perform these configuration steps:

Note that --mailfrom can be specified as just an email address as above, or you can include a pretty name such as: `--mailfrom "MyVPNServer<myemail@gmail.com>". This works for both Outlook.com and gmail.

Sending using local mail server

If you'd prefer to use your own mail server, you can configure pistrong to use that. If your system does not have the capability to send email, and you want it to, you can easily install a local-only email system. Here are the steps:

Not Yet Completed

If you're interested...

Please refer to the issues list if you have ideas for improving pistrong or have found a problem. I would be very happy to hear from you. There's always the possibility of a bug that I missed ;), or a great feature that should be added.

Or, if you're so inclined, do it yourself and leave a pull request.

Troubleshooting

If you're having problems and can't sort them out, please download and run the script pscollect and provide the output from it when you open an issue on this github. pscollect gathers up all the relevant information to help jump-start the process.