|
| 1 | +# OpenVPN |
| 2 | +This role installs [the `openvpn-install.sh`` bash script from GitHub](https://github.com/angristan/openvpn-install) and optionally runs it in headless mode. |
| 3 | + |
| 4 | +## PAM authentication |
| 5 | +There are two options here, one is simple PAM authentication against Linux users, the other is PAM authentication with LDAP. If you want to provide a custom PAM configuration you should set `openvpn.pam.enabled` to `true` and create your own template to override the `openvpn.pam.j2` template provided. This file is placed in `/etc/pam.d/openvpn` and loaded by the OpenVPN authentication module to perform authorisation checks. |
| 6 | + |
| 7 | +The LDAP integration ships with a default configuration for PAM which, as above, can be overridden. It assumes the use of [our `pam_ldap` role](https://github.com/codeenigma/ce-provision/tree/2.x/roles/debian/pam_ldap) for the LDAP variables and defaults to those values, but they can be set explicitly if required. |
| 8 | + |
| 9 | +## Hardcoded values |
| 10 | +At the moment we do not support headless customisation of encryption settings. This seems possible [by setting the right variables](https://github.com/angristan/openvpn-install/blob/master/openvpn-install.sh#L392-L401) and we'll add it later if we can. The defaults are sane, but please note the default cipher is `AES-128-GCM`. We have allowed for finding and replacing this value as part of our role. |
| 11 | + |
| 12 | +[The client config directory is set to `/etc/openvpn/ccd`.](https://github.com/angristan/openvpn-install/blob/master/openvpn-install.sh#L900C19-L900C35) |
| 13 | + |
| 14 | +<!--ROLEVARS--> |
| 15 | +## Default variables |
| 16 | +```yaml |
| 17 | +--- |
| 18 | +openvpn: |
| 19 | + script_install_path: "/home/{{ user_provision.username }}" |
| 20 | + auto_install: true |
| 21 | + name: vpn.example.com |
| 22 | + ipv4_settings: "" # defaults to `10.8.0.0 255.255.255.0` - example, to use 192.168.140.0/24 set "192.168.140.0 255.255.255.0" |
| 23 | + cipher: "" # defaults to AES-128-GCM, see https://github.com/angristan/openvpn-install/blob/master/openvpn-install.sh#L404-L410 |
| 24 | + allow_floating_client_ip: true # allow for ISP address change with DHCP (option float) |
| 25 | + multiple_connections: false # set to true to enable multiple VPN connections (option duplicate-cn) |
| 26 | + approve_ip: "y" |
| 27 | + ipv6_support: "n" |
| 28 | + port_choice: "1" # 1 = use default 1194, 3 means use a random port |
| 29 | + protocol_choice: "1" # 1 = udp, 2 = tcp |
| 30 | + dns: "1" # 1 = system default, see options - https://github.com/angristan/openvpn-install/blob/master/openvpn-install.sh#L314-L327 |
| 31 | + compression_enabled: "n" |
| 32 | + compression_choice: "1" # only works if compression_enabled is "y", 1 = LZ4-v2, 2 = LZ4, 3 = LZ0 |
| 33 | + customize_enc: "n" |
| 34 | + pass: "1" |
| 35 | + #nat_endpoint: "$(curl -4 ifconfig.co)" # for servers behind NAT, see https://github.com/angristan/openvpn-install?tab=readme-ov-file#headless-install |
| 36 | + push_routes_ipv4: [] # list of VPN push routes for ipv4 networks |
| 37 | + # Examples: |
| 38 | + # - "192.168.1.0 255.255.255.0" # push range 192.168.1.0/24, format = "IP-address/range netmask" |
| 39 | + # - "1.2.3.4 255.255.255.255" # push specific IP 1.2.3.4 |
| 40 | + # - www.google-analytics.com # push any IP resolving to www.google-analytics.com |
| 41 | + push_routes_ipv6: [] # list of VPN push routes for ipv6 networks - ipv6_support must be "y" |
| 42 | + pam: |
| 43 | + enabled: false # relies on `openvpn-plugin-auth-pam.so` which is bundled with OpenVPN server for Debian |
| 44 | + module_path: /usr/lib/x86_64-linux-gnu/openvpn/plugins/openvpn-plugin-auth-pam.so # use `dpkg -L openvpn | grep '\bpam\b'` to discover the path |
| 45 | + config_template: openvpn.pam.j2 # allow override of PAM config template |
| 46 | + ldap: |
| 47 | + enabled: false # if true we assume the pam_ldap role is also being used on this server |
| 48 | + config_template: openvpn.pam.ldap.j2 # allow override of PAM config template for LDAP |
| 49 | + endpoints: "{{ pam_ldap.endpoints | default('[]') }}" |
| 50 | + lookup_base: "{{ pam_ldap.lookup_base | default('') }}" |
| 51 | + lookup_filter: "|(objectClass=inetOrgPerson)" # LDAP filter to apply to lookups |
| 52 | + login_attribute: uid # the LDAP attribute to check the OpenVPN username against |
| 53 | + group_base: "" # e.g. ou=Groups,dc=example,dc=com |
| 54 | + group_dn: "" # restrict to specific group, e.g. cn=admins,ou=Groups,dc=example,dc=com |
| 55 | + group_attribute: memberUid # the LDAP group attribute to check the OpenVPN username against |
| 56 | + ssl_certificate: "{{ pam_ldap.ssl_certificate | default('') }}" |
| 57 | + ssl_certificate_check: "{{ pam_ldap.ssl_certificate_check | default(true) }}" |
| 58 | + |
| 59 | +``` |
| 60 | + |
| 61 | +<!--ENDROLEVARS--> |
0 commit comments