Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/aovpn/ansible-role-openvpn
Ansible role to install and configure OpenVPN server
https://github.com/aovpn/ansible-role-openvpn
ansible ansible-role openvpn playbook role
Last synced: about 1 month ago
JSON representation
Ansible role to install and configure OpenVPN server
- Host: GitHub
- URL: https://github.com/aovpn/ansible-role-openvpn
- Owner: aovpn
- License: mit
- Created: 2024-06-16T22:20:19.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2024-09-19T15:04:55.000Z (about 2 months ago)
- Last Synced: 2024-09-30T17:20:15.705Z (about 2 months ago)
- Topics: ansible, ansible-role, openvpn, playbook, role
- Language: Jinja
- Homepage:
- Size: 296 KB
- Stars: 13
- Watchers: 2
- Forks: 1
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
OpenVPN
=========
This role installs OpenVPN from default repositories, configures it as a server, sets up networking and firewalls (primarily firewalld, ufw and iptables - best effort), and generates client configuration files. It also optionally supports LDAP authentication.
Supported Operating Systems:
- Ubuntu 24.04 and higher
- CentOS 9 and higher
- Debian 11 and higher
# Requirements
OpenVPN must be available as a package in yum/dnf/apt! For CentOS users, this role will run `yum install epel-release` to ensure OpenVPN is available.
Ubuntu Precise has a [weird bug](https://bugs.launchpad.net/ubuntu/+source/iptables-persistent/+bug/1002078) that might cause the `iptables-persistent` installation to fail. There is a [workaround](https://forum.linode.com/viewtopic.php?p=58233#p58233).
## Ansible Core 2.10 and Higher
With Ansible 2.10, modules have been moved into collections. Aside from Ansible's built-in modules, additional collections are required for certain module like seboolean (now ansible.posix.seboolean). The required collections are:
- ansible.posix
- community.general (if using ufw)
Installation:
```bash
ansible-galaxy collection install ansible.posix
ansible-galaxy collection install community.general
```
If you're using a standard Ansible distribution, you won't need to install any additional collections.
# Support Notes/Expectations
This role is supported by a group of enthusiasts on a best-effort basis. Feel free to open an issue and contribute a related pull request with a fix.
# Role Variables
## Role options
These options change how the role works. This is a catch-all group, specific groups are broken out below.
| Variable | Type | Choices | Default | Comment |
|------------------------------|---------|-------------|-------------------|-------------------------------------------------------------------------------|
| clients | list | | [] | List of clients (kinda users) to add to OpenVPN |
| openvpn_base_dir | string | | /etc/openvpn | Path where your OpenVPN config will be stored |
| openvpn_client_config_no_log | boolean | true, false | true | Prevent client configuration files to be logged to stdout by Ansible |
| openvpn_key_dir | string | | /etc/openvpn/keys | Path where your server private keys and CA will be stored |
| openvpn_ovpn_dir | string | | /etc/openvpn | Path where your client configurations will be stored |
| openvpn_revoke_these_certs | list | | [] | List of client certificates to revoke. |
| openvpn_selinux_module | string | | my-openvpn-server | Set the SELinux module name |
| openvpn_service_name | string | | openvpn | Name of the service. Used by systemctl to start the service |
| openvpn_sync_certs | boolean | true, false | false | Revoke certificates not explicitly defined in 'clients' |
| openvpn_uninstall | boolean | true, false | false | Set to true to uninstall the OpenVPN service |
| openvpn_use_ldap | boolean | true, false | false | Active LDAP backend for authentication. Client certificate not needed anymore |
### Config fetching
Change these options if you need to adjust how the configs are download to your local system
| Variable | Type | Choices | Default | Comment |
|-------------------------------------|---------|-------------|--------------|-------------------------------------------------------------------------------------------------------------------------------------------|
| openvpn_fetch_client_configs | boolean | true, false | true | Download generated client configurations to the local system |
| openvpn_fetch_client_configs_dir | string | | /tmp/ansible | If openvpn_fetch_client_configs is true, the local directory to download the client config files into |
| openvpn_fetch_client_configs_suffix | string | | "" | If openvpn_fetch_client_configs is true, the suffix to append to the downloaded client config files before the trailing `.ovpn` extension |
### Firewall
Change these options if you need to force a particular firewall or change how the playbook interacts with the firewall.
| Variable | Type | Choices | Default | Comment |
|----------------------------------|---------|--------------------------------|----------|-------------------------------------------------------------------------------------------------------------|
| firewalld_default_interface_zone | string | | public | Firewalld zone where the "ansible_default_ipv4.interface" will be pushed into |
| iptables_service | string | | iptables | Override the iptables service name |
| manage_firewall_rules | boolean | true, false | true | Allow playbook to manage iptables |
| openvpn_firewall | string | auto, firewalld, ufw, iptables | auto | The firewall software to configure network rules. "auto" will attempt to detect it by inspecting the system |
## OpenVPN Config Options
These options change how OpenVPN itself works.
### Networking
| Variable | Type | Choices | Default | Comment |
|-----------------------------|--------------|-------------------|----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
| openvpn_client_register_dns | boolean | true, false | true | Add `register-dns` option to client config (Windows only). |
| openvpn_client_to_client | boolean | true, false | false | Set to true if you want clients to access each other. |
| openvpn_custom_dns | list[string] | | [] | List of DNS servers, only applied if `openvpn_set_dns` is set to true |
| openvpn_dualstack | boolean | | true | Whether or not to use a dualstack (IPv4 + v6) socket |
| openvpn_keepalive_ping | int | | 5 | Set `keepalive` ping interval seconds. |
| openvpn_keepalive_timeout | int | | 30 | Set `keepalive` timeout seconds |
| openvpn_local | string | | `unset` | Local host name or IP address for bind. If specified, OpenVPN will bind to this address only. If unspecified, OpenVPN will bind to all interfaces. |
| openvpn_port | int | | 1194 | The port you want OpenVPN to run on. If you have different ports on different servers, I suggest you set the port in your inventory file. |
| openvpn_proto | string | udp, tcp | udp | The protocol you want OpenVPN to use |
| openvpn_redirect_gateway | boolean | true, false | true | OpenVPN gateway push |
| openvpn_resolv_retry | int/string | any int, infinite | 5 | Hostname resolv failure retry seconds. Set "infinite" to retry indefinitely in case of poor connection or laptop sleep mode recovery etc. |
| openvpn_server_hostname | string | | `{{ inventory_hostname }}` | The server name to place in the client configuration file |
| openvpn_server_ipv6_network | string | | `unset` | If set, the network address and prefix of an IPv6 network to assign to clients. If True, IPv4 still used too. |
| openvpn_server_netmask | string | | 255.255.255.0 | Netmask of the private network |
| openvpn_server_network | string | | 10.9.0.0 | Private network used by OpenVPN service |
| openvpn_set_dns | boolean | true, false | true | Will push DNS to the client (Cloudflare and Google) |
| openvpn_tun_mtu | int | | `unset` | Set `tun-mtu` value. Empty for default. |
### Security
| Variable | Type | Choices | Default | Comment |
|------------------------------------|---------|-------------|-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| openvpn_auth_alg | string | | SHA256 | Set `auth` authentication algoritm. |
| openvpn_ca_key | dict | | `unset` | Contain "crt" and "key". If not set, CA cert and key will be automatically generated on the target system. |
| openvpn_cipher | string | | AES-256-CBC | Set `cipher` option for server and client. |
| openvpn_crl_path | string | | `unset` | Define a path to the CRL file for server revocation check. |
| openvpn_duplicate_cn | boolean | true, false | false | Add `duplicate-cn` option to server config - this allows clients to connect multiple times with the one key. NOTE: client ip addresses won't be static anymore! |
| openvpn_rsa_bits | int | | 2048 | Number of bits used to protect generated certificates |
| openvpn_script_security | int | | 1 | Set openvpn script security option |
| openvpn_tls_auth_key | string | | `unset` | Single item with a pre-generated TLS authentication key. |
| openvpn_use_crl | boolean | true, false | false | Configure OpenVPN server to honor certificate revocation list. |
| openvpn_use_hardened_tls | boolean | true, false | true | Require a minimum version of TLS 1.2 |
| openvpn_use_modern_tls | boolean | true, false | true | Use modern Cipher for TLS encryption (Not recommended with OpenVPN 2.4) |
| openvpn_use_pregenerated_dh_params | boolean | true, false | false | DH params are generted with the install by default |
| openvpn_verify_cn | boolean | true, false | false | Check that the CN of the certificate match the FQDN |
| tls_auth_required | boolean | true, false | true | Ask the client to push the generated ta.key of the server during the connection |
### Operations
| Variable | Type | Choices | Default | Comment |
|------------------------------------|---------|-------------|--------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| openvpn_addl_client_options | list | | empty | List of user-defined client options that are not already present in the client template. (e.g. `- mssfix 1400`) |
| openvpn_addl_server_options | list | | empty | List of user-defined server options that are not already present in the server template. (e.g. `- ping-timer-rem`) |
| openvpn_compression | string | | lzo | Set `compress` compression option. Empty for no compression. |
| openvpn_config_file | string | | openvpn_{{ openvpn\_proto }}\_{{ openvpn_port }} | The config file name you want to use (set in vars/main.yml) |
| openvpn_enable_management | boolean | true, false | false | |
| openvpn_ifconfig_pool_persist_file | string | | ipp.txt | |
| openvpn_management_bind | string | | /var/run/openvpn/management unix | The interface to bind on for the management interface. Can be unix or TCP socket. |
| openvpn_management_client_user | string | | root | Use this user when using a Unix socket for management interface. |
| openvpn_push | list | | empty | Set here a list of string that will be inserted into the config file as `push ""`. E.g `- route 10.20.30.0 255.255.255.0` will generate push "route 10.20.30.0 255.255.255.0" |
| openvpn_script_client_connect | string | | `unset` | Path to your openvpn client-connect script |
| openvpn_script_client_disconnect | string | | `unset` | Path to your openvpn client-disconnect script |
| openvpn_script_down | string | | `unset` | Path to your openvpn down script |
| openvpn_script_up | string | | `unset` | Path to your openvpn up script |
| openvpn_service_group | string | | nogroup | Set the openvpn service group. |
| openvpn_service_user | string | | nobody | Set the openvpn service user. |
| openvpn_status_version | int | 1, 2, 3 | 1 | Define the formatting of the openvpn-status.log file where are listed current client connection |
| openvpn_topology | string | | `unset` | the "topology" keyword will be set in the server config with the specified value. |
### OpenVPN custom client config (server pushed)
| Variable | Type | Choices | Default | Comment |
|---------------------------|---------|---------|---------|------------------------------------------------------|
| openvpn_client_config | Boolean | | false | Set to true if enable client configuration directory |
| openvpn_client_config_dir | string | | ccd | Path of `client-config-dir` |
| openvpn_client_configs | dict | | {} | Dict of settings custom client configs |
## Logrotate
Set your own custom logrotate options.
| Variable | Type | Choices | Default | Comment |
|--------------------------|--------|---------|-------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------|
| openvpn_log_dir | string | | /var/log | Set location of openvpn log files. This parameter is a part of `log-append` configuration value. |
| openvpn_log_file | string | | openvpn.log | Set log filename. This parameter is a part of `log-append` configuration value. |
| openvpn_logrotate_config | string | | rotate 4
weekly
missingok
notifempty
sharedscripts
copytruncate
delaycompress | Configure logrotate script. |
## Packaging
This role pulls in a bunch of different packages. Override the names as necessary.
| Variable | Type | Choices | Default | Comment |
|----------------------------------|--------|---------|---------------------|-----------------------------------------------------------------------------|
| epel_package_name | string | | epel-release | Name of the epel-release package to install from the package manager |
| iptables_persistent_package_name | string | | iptables-persistent | Name of the iptables-persistent package to install from the package manager |
| iptables_services_package_name | string | | iptables-services | Name of the iptables-services package to install from the package manager |
| openssl_package_name | string | | openssl | Name of the openssl package to install from the package manager |
| openvpn_ldap_plugin_package_name | string | | openvpn-auth-ldap | Name of the openvpn-auth-ldap package to install from the package manager |
| openvpn_package_name | string | | openvpn | Name of the openvpn package to install from the package manager |
| python_firewall_package_name | string | | python-firewall | Name of the python-firewall package to install from the package manager |
## LDAP object
| Variable | Type | Choices | Default | Comment |
|---------------------|--------|---------------------------|-----------------------------------------|----------------------------------------------------------------------------------------------|
| ldap | dict | | | Dictionary that contain LDAP configuration |
| url | string | | ldap://host.example.com | Address of you LDAP backend with syntax ldap[s]://host[:port] |
| anonymous_bind | string | False , True | False | This is not an Ansible boolean but a string that will be pushed into the configuration file. |
| bind_dn | string | | uid=Manager,ou=People,dc=example,dc=com | Bind DN used if "anonymous_bind" set to "False" |
| bind_password | string | | mysecretpassword | Password of the bind_dn user |
| tls_enable | string | yes , no | no | Force TLS encryption. Not necessary with ldaps addresses |
| tls_ca_cert_file | string | | /etc/openvpn/auth/ca.pem | Path to the CA ldap backend. This must have been pushed before |
| tls_cert_file | string | | | Path to client authentication certificate |
| tls_key_file | string | | | Path to client authentication key |
| base_dn | string | | ou=People,dc=example,dc=com | Base DN where the backend will look for valid user |
| search_filter | string | | (&(uid=%u)(accountStatus=active)) | Filter the ldap search |
| require_group | string | False , True | | This is not an Ansible boolean but a string that will be pushed into the configuration file. |
| group_base_dn | string | | ou=Groups,dc=example,dc=com | Precise the group to look for. Required if require_group is set to "True" |
| group_search_filter | string | | ((cn=developers)(cn=artists)) | Precise valid groups |
| verify_client_cert | string | none , optional , require | client-cert-not-required | In OpenVPN 2.4+ `client-cert-not-required` is deprecated. Use `verify-client-cert` instead. |
# Dependencies
Does not depend on any other roles
# How to use
## Example Playbook
Assume you've cloned this repository into the `ansible-role-openvpn` directory. Navigate to the directory one level above this using `..`. In this parent directory, create a new playbook named `ovpn.yaml`.
```yaml
---
- hosts: all
gather_facts: true
become: true
roles:
- role: ansible-role-openvpn
openvpn_port: 4300
openvpn_sync_certs: true
clients:
- myclient1
- myclient2
```
> **Note:** As the role will need to know the remote used platform (32 or 64 bits), you must set `gather_facts` to `true` in your play.
Each client listed in the playbook will have a separate configuration generated with unique certificates. Ensure you add as many clients as you have users.
## Apply Playbook
SSH key-based authentication is assumed. If using password authentication, add `-kK` to the command.
```bash
ansible-playbook -u USERNAME -i ip.add.re.ss, ./ovpn.yaml
```
Where:
- USERNAME — replace USERNAME with your SSH username.
- ip.add.re.ss — replace ip.add.re.ss with the IP address (or DNS name) of your OpenVPN server, followed by a comma.
## Configuration files for clients
Client configuration files are copied to the machine where you ran the ansible-playbook command. By default, you'll find them in the `/tmp/ansible` directory.
## More examples
More examples will be provided in future documentation, which will be linked here. Stay tuned!
# Contributing
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
Check out our [contributing guide](CONTRIBUTING.md) to get started.
Don't forget to give the project a star! Thanks again!
# License
MIT
# Author Information
Initially written by Kyle Lexmond