cookbook 'openvpn', '= 4.0.0'
openvpn
(48) Versions
4.0.0
-
-
7.0.20
-
7.0.19
-
7.0.18
-
7.0.17
-
7.0.16
-
7.0.15
-
7.0.14
-
7.0.13
-
7.0.12
-
7.0.11
-
7.0.10
-
7.0.9
-
7.0.8
-
7.0.7
-
7.0.6
-
7.0.5
-
7.0.4
-
7.0.3
-
7.0.2
-
7.0.1
-
7.0.0
-
6.1.0
-
6.0.0
-
5.4.0
-
5.3.2
-
5.3.1
-
5.3.0
-
5.2.0
-
5.1.2
-
5.1.1
-
5.1.0
-
5.0.0
-
4.0.0
-
3.0.0
-
2.1.0
-
2.0.4
-
2.0.2
-
2.0.0
-
1.1.4
-
1.1.2
-
1.1.0
-
1.0.2
-
1.0.0
-
0.99.2
-
0.99.1
-
0.99.0
-
0.8.2
-
0.7.0
Follow55
- 7.0.20
- 7.0.19
- 7.0.18
- 7.0.17
- 7.0.16
- 7.0.15
- 7.0.14
- 7.0.13
- 7.0.12
- 7.0.11
- 7.0.10
- 7.0.9
- 7.0.8
- 7.0.7
- 7.0.6
- 7.0.5
- 7.0.4
- 7.0.3
- 7.0.2
- 7.0.1
- 7.0.0
- 6.1.0
- 6.0.0
- 5.4.0
- 5.3.2
- 5.3.1
- 5.3.0
- 5.2.0
- 5.1.2
- 5.1.1
- 5.1.0
- 5.0.0
- 4.0.0
- 3.0.0
- 2.1.0
- 2.0.4
- 2.0.2
- 2.0.0
- 1.1.4
- 1.1.2
- 1.1.0
- 1.0.2
- 1.0.0
- 0.99.2
- 0.99.1
- 0.99.0
- 0.8.2
- 0.7.0
Installs and configures openvpn and includes rake tasks for managing certs.
cookbook 'openvpn', '= 4.0.0', :supermarket
knife supermarket install openvpn
knife supermarket download openvpn
openvpn Cookbook
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
Platforms
- Debian 8+
- Ubuntu 14.04+
- RHEL 6.x and 7.x w/ (EPEL is enabled as required)
- CentOS 6.x, 7.x
- Fedora
- OpenSUSE 42+ (partial support/WIP)
- Arch Linux
- FreeBSD 11+ (partial support/WIP)
Note: we currently only test the latest minor release for the last 2 major releases of each OS/distribution using Test Kitchen.
Cookbooks
- sysctl
- yum-epel
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:
- setting up routers and other network devices
- ethernet-bridging (tap interfaces)
- dual-factor authentication
- many other advanced OpenVPN configurations
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.
-
node['openvpn']['client_cn']
- The client's Common Name used with theopenvpn::client
recipe (essentially a standalone recipe) for the client certificate and key. -
node['openvpn']['type']
- Valid values are 'client' (currently a work in progress), 'server' or 'server-bridge'. Default is 'server' and it will create a routed IP tunnel, and use the 'tun' device. 'server-bridge' will create an ethernet bridge and requires a tap0 device bridged with the ethernet interface, and is beyond the scope of this cookbook. -
node['openvpn']['subnet']
- Used for server mode to configure a VPN subnet to draw client addresses. Default is 10.8.0.0, which is what the sample OpenVPN config package uses. -
node['openvpn']['netmask']
- Netmask for the subnet, default is 255.255.0.0. -
node['openvpn']['gateway']
- FQDN for the VPN gateway server. Default isnode['fqdn']
. -
node['openvpn']['push_routes']
- Array of routes to to push to clients (aspush
statements) in the server.conf, e.g. '192.168.0.0 255.255.255.0'. Default is empty. -
node['openvpn']['push_options']
- Array of options to push to clients in the server.conf, e.g. [["dhcp-option DNS", ["8.8.8.8"]]]. Default is empty. -
node['openvpn']['configure_default_server']
- Boolean. Set this to false if you want to create all of your "conf" files with the LWRP. -
node['openvpn']['git_package']
- Boolean. Whether to use theopenvpn-git
package (Arch Linux only, default false). -
node['openvpn']['client_prefix']
- String. Name of the config that is created for clients. When imported into most vpn clients, this is the name that will be displayed for the connection. Default is 'vpn-prod'. -
node['openvpn']['cookbook_user_conf']
- String. The cookbook used by theopenvpn::users
recipe for theclient.conf.erb
template. You can override this to your own, such as your wrapper cookbook. Default is'openvpn'
. -
node['openvpn']['key_dir']
- Location to store keys, certificates and related files. Default/etc/openvpn/keys
. -
node['openvpn']['signing_ca_cert']
- CA certificate for signing, default/etc/openvpn/keys/ca.crt
-
node['openvpn']['signing_ca_key']
- CA key for signing, default/etc/openvpn/keys/ca.key
-
node['openvpn']['server_verification']
- Server certificate verification directive, can be anything mentioned in official doc. By defaultnil
. -
node['openvpn']['config']['local']
- IP to listen on, defaults tonode['ipaddress']
-
node['openvpn']['config']['proto']
- Valid values are 'udp' or 'tcp', defaults to 'udp'. -
node['openvpn']['config']['port']
- Port to listen on, defaults to '1194'. -
node['openvpn']['config']['log']
- Server log file. Default /var/log/openvpn.log -
node['openvpn']['config']['script-security']
- Script Security setting to use in server config. Default is 1. The "up" script will not be included in the configuration if this is 0 or 1. Set it to 2 to use the "up" script.
The following attributes are used to populate the easy-rsa
vars file. Defaults are the same as the vars file that ships with OpenVPN.
-
node['openvpn']['key']['ca_expire']
- In how many days should the root CA key expire -CA_EXPIRE
. -
node['openvpn']['key']['expire']
- In how many days should certificates expire -KEY_EXPIRE
. -
node['openvpn']['key"]['size']
- Default key size, set to 2048 if paranoid but will slow down TLS negotiation performance -KEY_SIZE
.
The following are for the default values for fields place in the certificate from the vars file. Do not leave these blank.
-
node['openvpn']['key']['country']
-KEY_COUNTRY
-
node['openvpn']['key']['province']
-KEY_PROVINCE
-
node['openvpn']['key']['city']
-KEY_CITY
-
node['openvpn']['key']['org']
-KEY_ORG
-
node['openvpn']['key']['email']
-KEY_EMAIL
The following lets you specify the message digest used for generating certificates by OpenVPN
-
node['openvpn']['key']['message_digest']
- Default issha256
for a high-level of security.
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.
openvpn::easy_rsa
Installs the easy-rsa package (a CLI utility to build and manage a PKI CA).
Usage
Create a role for the OpenVPN server. See above for attributes that can be entered here.
name "openvpn" description "The server that runs OpenVPN" run_list("recipe[openvpn::server]") override_attributes( "openvpn" => { "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:
override_attributes( "openvpn" => { "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:
override_attributes( "openvpn" => { "push_options" => { "dhcp-option" => [ "DOMAIN domain.local", "DOMAIN-SEARCH domain.local" ], "string-option" => "string value" } } )
This will render a config file that looks like:
push "dhcp-option DOMAIN domain.local"
push "dhcp-option DOMAIN-SEARCH domain.local"
push "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.
{ "id": "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.
Resources
openvpn_user
Implements a resource for creation of users and bundles.
Customizing Server Configuration
To further customize the server configuration, there are two templates that can be modified in this cookbook.
- templates/default/server.conf.erb
- templates/default/server.up.sh.erb
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
- Author:: Chris Fordham (chris@fordham-nagy.id.au)
- Author:: Joshua Timberman (joshua@chef.io)
Copyright:: 2009-2018, Chef Software, Inc Copyright:: 2018-2018, Xhost Australia Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
openvpn Cookbook CHANGELOG
This file is used to list changes made in each version of the openvpn cookbook.
v4.0.0 (Jan 21, 2019)
- Require Chef 13 or later
- Resolve compatibility with Chef 14
- Add Ubuntu 18.04 testing and remove Ubuntu 14.04
- Removes the dependency on the apt cookbook
- Added a new openvpn_user resource for setting up users
- Setup the official openvpn repo when on the debian platform_family
- Add a new attribute
default['openvpn']['use_databag']
to control setting up users from databag entries - Add CircleCI & Danger testing
v3.0.0
- Chef-13 compatibility
- Use local delivery for testing
- Fix file existence check
- Fix port attribute in Rakefile
- Archlinux openvpn-git support
- Lazy evaluation for key generation
- User configuration template can now be set to a user defined template
- Allow Override of global push settings
- Fix Debian 8 service
- Fix Fedora service
- EasyRSA recipe added
- Added ability to name configuration import file
- Generate CRL
- Don't set username in configuration template
- Enable 'up' script in server config
- Fix OpenVPN startup on Centos-7
- Enable Message digest configuration
- Install bridge utils when using server-bridge
- Add a method to configure and enable
ip_forwarding
v2.1.0
Updating to use cookbook yum ~> 3.0 Fixing up style issues Updating testing bits
v2.0.4
fixing metadata version error. locking to 3.0
v2.0.2
Locking yum dependency to '< 3'
v2.0.0
- [COOK-3691] Creating and using a openvpn_conf LWRP
v1.1.4
Bug
-
COOK-3317 - Fix and make
server.up.sh
useful and customizable
New Feature
- COOK-3315 - Remove hardcoded variables in configuration file
v1.1.2
Improvement
- COOK-2820 - Update metadata.rb for all attributes and recipes
v1.1.0
- [COOK-1231] - dont use up script if security isnt >1
- [COOK-2513] Changed user and group to attributes
v1.0.2
- [COOK-2288] - make attribute assignment in openvpn::default compatible w/ Chef 11
v1.0.0
- [COOK-1171] - use proper key size
- [COOK-1231] - add script_security attribute
v0.99.2
- [COOK-564] - fix users recipe search, add port attribute
- [COOK-621] - rename attribute "push" to "routes" - see below.
Collaborator Number Metric
4.0.0 passed this metric
Contributing File Metric
4.0.0 passed this metric
Foodcritic Metric
4.0.0 passed this metric
No Binaries Metric
4.0.0 passed this metric
Testing File Metric
4.0.0 passed this metric
Version Tag Metric
4.0.0 passed this metric
4.0.0 passed this metric
4.0.0 passed this metric
Foodcritic Metric
4.0.0 passed this metric
No Binaries Metric
4.0.0 passed this metric
Testing File Metric
4.0.0 passed this metric
Version Tag Metric
4.0.0 passed this metric
4.0.0 passed this metric
4.0.0 passed this metric
Testing File Metric
4.0.0 passed this metric
Version Tag Metric
4.0.0 passed this metric
4.0.0 passed this metric
4.0.0 passed this metric