artsy/openvpn

Name: openvpn

Owner: Artsy

Description: Development repository for Chef cookbook, openvpn.

Forked from: sous-chefs/openvpn

Created: 2016-04-14 19:39:01.0

Updated: 2016-04-14 19:39:02.0

Pushed: 2016-02-21 12:21:49.0

Homepage: https://supermarket.chef.io/cookbooks/openvpn

Size: 358

Language: Ruby

GitHub Committers

UserMost Recent Commit# Commits

Other Committers

UserEmailMost Recent Commit# Commits

README

openvpn Cookbook

Build Status Cookbook Version Dependency Status Code Climate Test Coverage License

Installs OpenVPN and sets up a fairly basic configuration. Since OpenVPN is very complex, we provide a baseline only (see Customizing Server Configuration below).

Requirements

This cookbook is tested and supported with Chef 11 & 12.

Platform
Cookbooks

The yum cookbook by Chef Software provides recipe[yum::epel] that is used on RHEL-family systems to enable the EPEL repository containing the openvpn RPM. See Usage below.

Not Supported

This cookbook is designed to set up a basic installation of OpenVPN that will work for many common use cases. The following configurations are not supported by default with this cookbook:

For further modification of the cookbook see Usage below.

For more information about OpenVPN, see the official site.

Attributes

These attributes are set by the cookbook by default.

The following attributes are used to populate the easy-rsa vars file. Defaults are the same as the vars file that ships with OpenVPN.

The following are for the default values for fields place in the certificate from the vars file. Do not leave these blank.

The following lets you specify the message digest used for generating certificates by OpenVPN

Recipes
openvpn::default

Installs the OpenVPN package only.

openvpn::install

Installs the OpenVPN package only.

openvpn::server

Installs and configures OpenVPN as a server.

openvpn::client

Installs and configures OpenVPN as a client.

openvpn::service

Manages the OpenVPN system service (there is no need to use this recipe directly in your run_list).

openvpn::users

Utilizes a data bag called users to generate OpenVPN keys for each user. chef-solo-search is required in order to use this recipe with Chef-Solo, although it is not a dependency of this cookbook.

Usage

Create a role for the OpenVPN server. See above for attributes that can be entered here.

 "openvpn"
ription "The server that runs OpenVPN"
list("recipe[openvpn::server]")
ride_attributes(
penvpn" => {
"gateway" => "vpn.example.com",
"subnet" => "10.8.0.0",
"netmask" => "255.255.0.0",
"key" => {
  "country" => "US",
  "province" => "CA",
  "city" => "SanFrancisco",
  "org" => "Fort-Funston",
  "email" => "me@example.com"
}

Note: If you are using a Red Hat EL distribution, the EPEL repository is automatically enabled by Chef's recipe[yum::epel] to install the openvpn package.

To push routes to clients, add node['openvpn']['push_routes] as an array attribute, e.g. if the internal network is 192.168.100.0/24:

ride_attributes(
penvpn" => {
"push_routes => [
  "192.168.100.0 255.255.255.0"
]

To push other options to clients, use the node['openvpn']['push_options'] attribute and set an array of hashes or strings. For example:

ride_attributes(
penvpn" => {
"push_options" => {
  "dhcp-option" => [
    "DOMAIN domain.local",
    "DOMAIN-SEARCH domain.local"
  ],
  "string-option" => "string value"
}

This will render a config file that looks like:

 "dhcp-option DOMAIN domain.local"
 "dhcp-option DOMAIN-SEARCH domain.local"
 "string-option string value"

To automatically create new certificates and configurations for users, create data bags for each user. The only content required is the id, but this can be used in conjunction with other cookbooks by Chef Software such as users or samba. See SSL Certificates below for more about generating client certificate sets.


d": "jtimberman"

This cookbook also provides an 'up' script that runs when OpenVPN is started. This script is for setting up firewall rules and kernel networking parameters as needed for your environment. Modify to suit your needs, upload the cookbook and re-run chef on the openvpn server. For example, you'll probably want to enable IP forwarding (sample Linux setting is commented out). The attribute node['openvpn']["script_security"] must be set to 2 or higher to use this otherwise openvpn server startup will fail.

Customizing Server Configuration

To further customize the server configuration, there are two templates that can be modified in this cookbook.

The first is the OpenVPN server configuration file. Modify to suit your needs for more advanced features of OpenVPN. The second is an up script run when OpenVPN starts. This is where you can add firewall rules, enable IP forwarding and other OS network settings required for OpenVPN. Attributes in the cookbook are provided as defaults, you can add more via the openvpn role if you need them.

Using the LWRP

To create (possibly multiple) “conf” files on a server, use openvpn_conf “name”. See the conf.rb file in the resources directory to find the supported attributes, or add some of your own. If you don't want to use the default “server.conf” from the default recipe, set node['openvpn']["configure_default_server"] to false, then use the LWRP to configure as many as you like.

SSL Certificates

Some of the easy-rsa tools are copied to /etc/openvpn/easy-rsa to provide the minimum to generate the certificates using the default and users recipes. We provide a Rakefile to make it easier to generate client certificate sets if you're not using the data bags above. To generate new client certificates you will need rake installed (either as a gem or a package), then run:

cd /etc/openvpn/easy-rsa
source ./vars
rake client name="CLIENT_NAME" gateway="vpn.example.com"

Replace CLIENT_NAME and vpn.example.com with your desired values. The rake task will generate a tar.gz file with the configuration and certificates for the client.

License & Authors
right:: 2009-2015, Chef Software, Inc
right:: 2014-2015, Xhost Australia

nsed under the Apache License, Version 2.0 (the "License");
may not use this file except in compliance with the License.
may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

ss required by applicable law or agreed to in writing, software
ributed under the License is distributed on an "AS IS" BASIS,
OUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
the License for the specific language governing permissions and
tations under the License.
This work is supported by the National Institutes of Health's National Center for Advancing Translational Sciences, Grant Number U24TR002306. This work is solely the responsibility of the creators and does not necessarily represent the official views of the National Institutes of Health.