Pritunl

Pritunl Documentation

Welcome to the Pritunl developer hub. You'll find comprehensive guides and documentation to help you start working with Pritunl as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Getting Started SSH

Install and configure Pritunl Zero SSH certificates with two-factor authentication

Pritunl Zero is a zero trust system that provides secure authenticated access to servers without needing to manage authorized SSH keys. Below is a tutorial for installing and configuring a single Pritunl Zero instance.

Refer to the Getting Started Service for securing internal web services with Pritunl Zero.

Refer to the Pritunl Zero Gitlab tutorial for securing Gitlab with Pritunl Zero.

SSH Certificates

SSH certificates are a replacement for managing individual keys stored in ~/.ssh/authorized_keys. Instead of storing individual keys on each server a public key for a certificate authority is used instead.

For a user to authenticate to a server the user will first need to obtain a certificate from the certificate authority. In this case the Pritunl Zero server functions as the certificate authority.

The certificate given by the Pritunl Zero server is issued to the public key of the users SSH key. This is similar to certificate authorities used to verify a domain in a web browser. With web browsers the web server administrator obtains a certificate for their web servers public key from one of the certificate authorities trusted by the browser such as LetsEncrypt. When a user visits the website the web browser will verify the servers public key is valid with one of the trusted certificate authorities.

Similarly when a user attempts to connect to a server with an SSH certificate the server will verify the users public key is valid with the trusted certificate authority. In the case the only trusted SSH certificate authority will be from the Pritunl Zero server.

The SSH server does not need have any information about the individual users or the public keys used by the users to authenticate users. When the user connects the user will provide their public key and the certificate for that public key. The server can determine if the user is permitted to connect by validating the users certificate with the certificate authority.

This moves the management of permitted users from the individual servers to the Pritunl Zero server. With one central system managing the authentication of individual users it is simple to handle the SSH access to hundreds or even thousands of servers and users without ever needed to modify servers as access needs change.

When handling authentication for large groups of users more control over which servers each user has access to is often needed. This is handled by SSH certificate principles which are referenced as roles in Pritunl Zero. Similar to how a web server certificate can apply to multiple domains an SSH certificate can be valid for multiple principles. When a user retrieves an SSH certificate from Pritunl Zero all the roles assigned to the user will be set in the certificates principles. On the server in addition to configuring the certificate authority a list of permitted principles will also be configured. When a user attempts to connect the server will verify that the certificate contains at least one of the permitted principles.

Create DNS Records

Create two DNS records pointing to the public IP address of the Pritunl Zero server. In this tutorial the domains used will be zero.pritunl.org and zero-user.pritunl.org. The first domain will be used to access the management console and the second domain will be used to access the user console to validate SSH keys. Configure the firewall to open ports 80 and 443. Port 80 must be open to all IP addresses for the Lets Encrypt certificate. IPv6 is fully support and servers with only an IPv6 address can be used.

Install

Pritunl Zero is packaged for several Linux distributions, below are the commands for each distribution. This will install both MongoDB and Pritunl Zero then start the services. If multiple hosts are being configured or the MongoDB server is not being run on the same server skip the steps installing MongoDB.

sudo tee -a /etc/pacman.conf << EOF
[pritunl]
Server = https://repo.pritunl.com/stable/pacman
EOF

sudo pacman-key --keyserver hkp://keyserver.ubuntu.com -r 7568D9BB55FF9E5287D586017AE645C0CF8E292A
sudo pacman-key --lsign-key 7568D9BB55FF9E5287D586017AE645C0CF8E292A
sudo pacman -Sy
sudo pacman -S --noconfirm pritunl-zero mongodb
sudo systemctl start mongodb pritunl-zero
sudo systemctl enable mongodb pritunl-zero
sudo tee /etc/yum.repos.d/mongodb-org-4.0.repo << EOF
[mongodb-org-4.0]
name=MongoDB Repository
baseurl=https://repo.mongodb.org/yum/amazon/2013.03/mongodb-org/4.0/x86_64/
gpgcheck=1
enabled=1
gpgkey=https://www.mongodb.org/static/pgp/server-4.0.asc
EOF

sudo tee /etc/yum.repos.d/pritunl.repo << EOF
[pritunl]
name=Pritunl Repository
baseurl=https://repo.pritunl.com/stable/yum/amazonlinux/1/
gpgcheck=1
enabled=1
EOF

sudo yum -y install epel-release
gpg --keyserver hkp://keyserver.ubuntu.com --recv-keys 7568D9BB55FF9E5287D586017AE645C0CF8E292A
gpg --armor --export 7568D9BB55FF9E5287D586017AE645C0CF8E292A > key.tmp; sudo rpm --import key.tmp; rm -f key.tmp
sudo yum -y install pritunl-zero mongodb-org
sudo service mongod start
sudo start pritunl-zero
sudo tee /etc/yum.repos.d/mongodb-org-4.0.repo << EOF
[mongodb-org-4.0]
name=MongoDB Repository
baseurl=https://repo.mongodb.org/yum/amazon/2/mongodb-org/4.0/x86_64/
gpgcheck=1
enabled=1
gpgkey=https://www.mongodb.org/static/pgp/server-4.0.asc
EOF

sudo tee /etc/yum.repos.d/pritunl.repo << EOF
[pritunl]
name=Pritunl 
baseurl=https://repo.pritunl.com/stable/yum/amazonlinux/2/
gpgcheck=1
enabled=1
EOF

sudo rpm -Uvh https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
gpg --keyserver hkp://keyserver.ubuntu.com --recv-keys 7568D9BB55FF9E5287D586017AE645C0CF8E292A
gpg --armor --export 7568D9BB55FF9E5287D586017AE645C0CF8E292A > key.tmp; sudo rpm --import key.tmp; rm -f key.tmp
sudo yum -y install pritunl-zero mongodb-org
sudo systemctl start mongod pritunl-zero
sudo systemctl enable mongod pritunl-zero
sudo tee /etc/yum.repos.d/mongodb-org-4.0.repo << EOF
[mongodb-org-4.0]
name=MongoDB Repository
baseurl=https://repo.mongodb.org/yum/redhat/7/mongodb-org/4.0/x86_64/
gpgcheck=1
enabled=1
gpgkey=https://www.mongodb.org/static/pgp/server-4.0.asc
EOF

sudo tee /etc/yum.repos.d/pritunl.repo << EOF
[pritunl]
name=Pritunl Repository
baseurl=https://repo.pritunl.com/stable/yum/centos/7/
gpgcheck=1
enabled=1
EOF

sudo rpm -Uvh https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
gpg --keyserver hkp://keyserver.ubuntu.com --recv-keys 7568D9BB55FF9E5287D586017AE645C0CF8E292A
gpg --armor --export 7568D9BB55FF9E5287D586017AE645C0CF8E292A > key.tmp; sudo rpm --import key.tmp; rm -f key.tmp
sudo yum -y install pritunl-zero mongodb-org
sudo systemctl start mongod pritunl-zero
sudo systemctl enable mongod pritunl-zero
sudo tee /etc/apt/sources.list.d/mongodb-org-4.0.list << EOF
deb http://repo.mongodb.org/apt/debian jessie/mongodb-org/4.0 main
EOF

sudo tee /etc/apt/sources.list.d/pritunl.list << EOF
deb http://repo.pritunl.com/stable/apt jessie main
EOF

sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com --recv 9DA31620334BD75D9DCB49F368818C72E52529D4
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com --recv 7568D9BB55FF9E5287D586017AE645C0CF8E292A
sudo apt-get update
sudo apt-get --assume-yes install pritunl-zero mongodb-org
sudo systemctl start mongod pritunl-zero
sudo systemctl enable mongod pritunl-zero
sudo tee /etc/apt/sources.list.d/mongodb-org-4.0.list << EOF
deb http://repo.mongodb.org/apt/debian stretch/mongodb-org/4.0 main
EOF

sudo tee /etc/apt/sources.list.d/pritunl.list << EOF
deb http://repo.pritunl.com/stable/apt stretch main
EOF

sudo apt-get install dirmngr
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com --recv 9DA31620334BD75D9DCB49F368818C72E52529D4
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com --recv 7568D9BB55FF9E5287D586017AE645C0CF8E292A
sudo apt-get update
sudo apt-get --assume-yes install pritunl-zero mongodb-server
sudo systemctl start mongodb pritunl-zero
sudo systemctl enable mongodb pritunl-zero
sudo tee /etc/yum.repos.d/mongodb-org-3.6.repo << EOF
[mongodb-org-4.0]
name=MongoDB Repository
baseurl=https://repo.mongodb.org/yum/redhat/7/mongodb-org/4.0/x86_64/
gpgcheck=1
enabled=1
gpgkey=https://www.mongodb.org/static/pgp/server-4.0.asc
EOF

sudo tee /etc/yum.repos.d/pritunl.repo << EOF
[pritunl]
name=Pritunl Repository
baseurl=https://repo.pritunl.com/stable/yum/oraclelinux/7/
gpgcheck=1
enabled=1
EOF

sudo rpm -Uvh https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
gpg --keyserver hkp://keyserver.ubuntu.com --recv-keys 7568D9BB55FF9E5287D586017AE645C0CF8E292A
gpg --armor --export 7568D9BB55FF9E5287D586017AE645C0CF8E292A > key.tmp; sudo rpm --import key.tmp; rm -f key.tmp
sudo yum -y install pritunl-zero mongodb-org
sudo systemctl start mongod pritunl-zero
sudo systemctl enable mongod pritunl-zero
sudo tee /etc/apt/sources.list.d/mongodb-org-4.0.list << EOF
deb https://repo.mongodb.org/apt/ubuntu xenial/mongodb-org/4.0 multiverse
EOF

sudo tee /etc/apt/sources.list.d/pritunl.list << EOF
deb http://repo.pritunl.com/stable/apt xenial main
EOF

sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com --recv 9DA31620334BD75D9DCB49F368818C72E52529D4
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com --recv 7568D9BB55FF9E5287D586017AE645C0CF8E292A
sudo apt-get update
sudo apt-get --assume-yes install pritunl-zero mongodb-org
sudo systemctl start pritunl-zero mongod
sudo systemctl enable pritunl-zero mongod
sudo tee /etc/apt/sources.list.d/mongodb-org-4.0.list << EOF
deb https://repo.mongodb.org/apt/ubuntu bionic/mongodb-org/4.0 multiverse
EOF

sudo tee /etc/apt/sources.list.d/pritunl.list << EOF
deb http://repo.pritunl.com/stable/apt bionic main
EOF

sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com --recv 9DA31620334BD75D9DCB49F368818C72E52529D4
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com --recv 7568D9BB55FF9E5287D586017AE645C0CF8E292A
sudo apt-get update
sudo apt-get --assume-yes install pritunl-zero mongodb-server
sudo systemctl start pritunl-zero mongodb
sudo systemctl enable pritunl-zero mongodb

Increase Open File Limit (Optional)

Increasing the open file limit will allow more idle/active HTTP connections and improve the reliability of the server. Run the commands below and restart the server.

sudo sh -c 'echo "* hard nofile 100000" >> /etc/security/limits.conf'
sudo sh -c 'echo "* soft nofile 100000" >> /etc/security/limits.conf'
sudo sh -c 'echo "root hard nofile 100000" >> /etc/security/limits.conf'
sudo sh -c 'echo "root soft nofile 100000" >> /etc/security/limits.conf'

Configure MongoDB (Optional)

If multiple hosts are being run or MongoDB is run on a different server the MongoDB URI must be set. The command below will set the MongoDB URI. The service then needs to be restarted using the distributions init system. The MongoDB URI should be quoted.

sudo pritunl-zero mongo "mongodb://user:pass@atlas.mongodb.net:27017/pritunl-zero?ssl=true&authSource=admin"

Initial Login

Open the web console running on HTTPS port 443. Login with the username and password pritunl.

Open the Users tab and edit the pritunl user. Then set a password and click Save.

Create Certificate

Open the Certificates tab and and click New. Set the Name to the domain in this example zero.pritunl.org. The set the Type to LetsEncrypt. Click Add Domain twice and set the domains configured earlier in this example zero.pritunl.org and zero-user.pritunl.org. This will require the DNS for these domains to be pointing to this server and port 80 to be open on the server. Click Save and wait for the server to retrieve the certificate from LetsEncrypt. If an error occurs you likely need to wait a few minutes for the DNS changes to become available to the LetsEncrypt servers. More information about the error will be available in the Logs tab.

After saving both the domains should be listed under the DNS Names.

Next go to the Nodes tab and enable Management and User. Once done set the Management Domain to the first domain from above and the User Domain to the second one. Then click Add Certificate to add the certificate from above to the node. Then click Save and wait a few seconds for the web server to reload the certificate then refresh the page. You may need to close and reopen the tab for Chrome to correctly show the certificate as valid. If the domain is configured incorrectly the node can become inaccessible, if this occurs remove /etc/pritunl-zero.json and restart the pritunl-zero service. This will create a new node and the old node can be removed.

Create Authority

Open the Authorities tab and click New. Set the Name to production. Leave the other fields empty and click Save. An additional authority can be created for development servers.

Create User

Open the Users tab and click New. Set the Username to user and set a Password. Then add cloud to the Roles. Once done click New.

Configure Duo Two-Factor Authentication (Optional)

This step is optional and requires a Duo account. The username above must match a Duo username, if it does not the username can be updated. Open the Settings tab and click Add Two-Factor Provider. Set the Name to duo and the Label to Duo. Then fill in the other fields from Duo. Enable Push authentication and any other methods that will be permitted. Once done click Save.

Then open the Policies tab and click New. Set the Name to two-factor and click Add Authority to add the authority created above. This will apply the policy to any users connecting using the SSH certificate authority. Then enable Authority two-factor authentication and select duo. This will require the user to validate with Duo when retrieving an SSH certificate.

Generate SSH Server Configuration

The Pritunl Zero web console has a generate deploy script function. This will generate a script with all the parameters. The script can be run as a startup script or manually run on the server to configure Pritunl Zero SSH access. To generate a script click Generate Deploy Script in the Authorities tab. The Roles will determine what users can access the server. The user must have at least one matching role to connect to the server. In the example below any users who have the cloud role will have access to this server.

Manually Configure SSH Server

Connect to a server that will be authenticated using Pritunl Zero and use the commands below to configure the server. Replace EXAMPLE_SSH_PUB_KEY with the Public Key from the Authorities tab such as ssh-rsa AAAAB3NzaC1.... This will configure the server with the cloud role that was added to the user above, additional roles can be added to the principals file. Once done ensure the SSH service is restarted.

sudo sed -i '/^TrustedUserCAKeys/d' /etc/ssh/sshd_config
sudo sed -i '/^AuthorizedPrincipalsFile/d' /etc/ssh/sshd_config
sudo tee -a /etc/ssh/sshd_config << EOF

TrustedUserCAKeys /etc/ssh/trusted
AuthorizedPrincipalsFile /etc/ssh/principals
EOF
sudo tee /etc/ssh/principals << EOF
emergency
cloud
EOF
sudo tee /etc/ssh/trusted << EOF
EXAMPLE_SSH_PUB_KEY
EOF

sudo systemctl restart sshd || true
sudo service sshd restart || true

Authenticate User

Refer to Install SSH Client for instructions on installing the Pritunl Zero SSH client on the users desktop. Once the client is installed run the command below to generate an SSH key. It's best to generate a new key for Pritunl Zero but an existing key can be used. Leave the key passphrase blank. If you are attempting to test a clean configuration this can also be done in a Docker contain as shown on the homepage.

ssh-keygen -t ed25519
# Enter file in which to save the key (/root/.ssh/id_ed25519):
# Enter passphrase (empty for no passphrase):
# Enter same passphrase again:

After generating an SSH key run the command below to configure the Pritunl Zero client. Replace zero-user.pritunl.org with the user domain set above. When prompted select the SSH key created above by the number of the left. Once done the browser will open the Pritunl Zero user login. If it does not open cmd or ctrl click the link shown.

# Configure pritunl-ssh using the values below
pritunl-ssh
# Enter Pritunl Zero user hostname: zero-user.pritunl.org
# Select SSH key:
# [1] id_ed25519.pub
# Enter key number or full path to key: 1

Login with the user created above and click Approve when prompted.

If you also configured two-factor authentication select a method when prompted.

After approving the SSH key the console should print Successfully validated SSH key. The client will then add the SSH certificate the ~/.ssh directory. The SSH client and tools that use SSH will automatically detect this certificate and include it when authenticating. This will allow SSH access to the server that was configured with the certificate authority above until the SSH certificate expires. The expiration time can be set in the Authorities tab. For more information about Pritunl Zero such as SSH host certificates and SSH bastion hosts refer to the Pritunl Zero section on the left.

Host Certificates and Bastion Host

The Getting Started Bastion Server guide is available for configuring automatic bastion servers. This is the recommended configuration for bastion servers.

A Getting Started Host Certificates guide is available for manually configuring host certificates and a bastion host. This is more advanced and difficult to deploy.

YubiKey U2F and Smart Card

Refer to YubiKey SSH for configuring SSH authentication with YubiKey U2F using a private key stored on the YubiKey Smart Card.