Name

openvpn — format of openvpn component configuration

DESCRIPTION

General syntax rules of Kernun Firewall configuration files are described in configuration(7). This man page describes types, sections and items specific for the openvpn component configuration.

Repeatable sections/items are marked by the '*' before section/item name.

TYPES

Configuration directives have attributes of several value-types. For the basic types description, see configuration(7).

Enumeration is a list of words (names) representing integer values. Some enumerations accept both names and direct integer values; in this case, enumeration description contains values for every name (in parenthesis next to name). For other enumerations, using of names is obligatory.

The following enumerations are used in openvpn configuration directives:

enabling (see common(5))

yes-no (see common(5))

time-cond (see common(5))

zip-mode (see common(5))

week-day (see time(5))

month (see time(5))

dbglev (see log(5))

logfail-mode (see log(5))

ovpn-protocols (name-usage obligatory)

udp

Use UDP protocol. UDP must be specified on both peers.

tcp-client

Use TCP protocol, be the TCP client (the other peer must use tcp-server). TCP client will attempt to connect, and if that fails, will sleep for a period and try it again.

tcp-server

Use TCP protocol, be the TCP server (the other peer must use tcp-client). TCP server will wait indefinitely for an incomming connection.

udp6

Use UDP protocol over IPv6. UDP6 must be specified on both peers.

tcp6-client

Use TCP protocol over IPv6, be the TCP client (the other peer must use tcp6-server). TCP client will attempt to connect, and if that fails, will sleep for a period and try it again.

tcp6-server

Use TCP protocol over IPv6, be the TCP server (the other peer must use tcp6-client). TCP server will wait indefinitely for an incomming connection.

ovpn-remote-proto (name-usage obligatory)

udp

Use UDP protocol

tcp

Use TCP protocol

udp6

Use UDP protocol over IPv6

tcp6

Use TCP protocol over IPv6

implicit

Use the protocol specified by the OPENVPN.PROTO item

ovpn-comp-lzo-mode (name-usage obligatory)

yes, no, adaptive

none

The comp-lzo directive is ommited in the openvpn configuration

ovpn-cert-types (name-usage obligatory)

client, server

ovpn-cipher-algs (name-usage obligatory)

DES-CBC

64 bit default key (fixed)

RC2-CBC

128 bit default key (variable)

DES-EDE-CBC

128 bit default key (fixed)

DES-EDE3-CBC

192 bit default key (fixed)

DESX-CBC

192 bit default key (fixed)

BF-CBC

128 bit default key (variable)

RC2-40-CBC

40 bit default key (variable)

CAST5-CBC

128 bit default key (variable)

RC5-CBC

128 bit default key (variable)

RC2-64-CBC

64 bit default key (variable)

AES-128-CBC

128 bit default key (fixed)

AES-192-CBC

192 bit default key (fixed)

AES-256-CBC

256 bit default key (fixed)

AES-128-GCM

128 bit key, 128 bit block, TLS client/server mode only

AES-192-GCM

192 bit key, 128 bit block, TLS client/server mode only

AES-256-GCM

256 bit key, 128 bit block, TLS client/server mode only

CAMELLIA-128-CBC

128 bit default key (fixed)

CAMELLIA-192-CBC

192 bit default key (fixed)

CAMELLIA-256-CBC

256 bit default key (fixed)

none

no encryption

ovpn-redirect-gateway-flags (name-usage optional)

local (0)

Add the local flag if both OpenVPN servers are directly connected via a common subnet, such as with wireless. The local flag will cause step 1 above to be omitted.

def1 (1)

Use this flag to override the default gateway by using 0.0.0.0/1 and 128.0.0.0/1 rather than 0.0.0.0/0. This has the benefit of overriding but not wiping out the original default gateway.

bypass-dhcp (2)

Add a direct route to the DHCP server (if it is non-local) which bypasses the tunnel (Available on Windows clients, may not be available on non-Windows clients).

bypass-dns (3)

Add a direct route to the DNS server(s) (if they are non-local) which bypasses the tunnel (Available on Windows clients, may not be available on non-Windows clients).

ovpn-dhcp-option (name-usage obligatory)

DOMAIN

Set connection-specific DNS suffix

DNS

Set domain name server address

WINS

Set WINS server address

NBDD

Set NBDD server address

NTP

Set NTP serveer address

NBT

Set NetBIOS over TCP/IP Node type

NBS

Set NetBIOS over TCP/IP Scope

DISABLE-NBT

Disable Netbios over TCP/IP

ovpn-topology (name-usage obligatory)

net30, subnet

ovpn-local-scope (name-usage obligatory)

any

Accept connections on all interfaces

addr

Accept connections on the particular IP adress

tls-mat-variants (name-usage obligatory)

pkcs12

Cryptographic material provided in a single pkcs12 file

ca-cert-key

Cryptographic material provided in three separated files in .pem format

ITEMS AND SECTIONS

Configuration of openvpn library component consists of following prototypes:


  ovpn-push { ... }
* ovpn-ccd name { ... }
  ovpn-summary { ... }
* openvpn name { ... }
    

Description:

ovpn-push {


* route ... ;
* route-ipv6 ... ;
  redirect-gateway ... ;
  redirect-gateway-ipv6 ... ;
* dhcp-option ... ;
* raw ... ;
}

        

Configuration options to be pushed to the client for remote execution

Items & subsections:

route network [gw];

Add route to routing table after connection is established. Multiple routes can be specified. Routes will be automatically torn down in reverse order prior to TUN/TAP device close. Use special value of [0.0.0.0] as gw for specifying the remote VPN endpoint (from the perspective of the client, see vpn_gateway in openvpn(8).

network (type: net)

Route destination.

gw (type: host, optional, default: [0.0.0.0])

Router IP address. Special value [0.0.0.0] can be used for the remote VPN endpoint (from the client's perspective).

route-ipv6 network [gw];

Add IPV6 route to routing table after connection is established. Multiple routes can be specified. Routes will be automatically torn down in reverse order prior to TUN/TAP device close. Use special value of [::] as gw for specifying the remote VPN endpoint (from the perspective of the client, see vpn_gateway in openvpn(8).

network (type: net)

Route destination.

gw (type: host, optional, default: [::])

Router IP address. Special value [::] can be used for the remote VPN endpoint (from the client's perspective).

redirect-gateway flags;

Automatically execute routing commands to cause all outgoing IP traffic to be redirected over the VPN. This option performs three steps: (1) Create a static route for the remote address which forwards to the pre-existing default gateway. This is done so that (3) will not create a routing loop. (2) Delete the default gateway route. (3) Set the new default gateway to be the VPN endpoint address

When the tunnel is torn down, all of the above steps are reversed so that the original default route is restored.

Using the def1 flag is highly recommended.

flags (type: ovpn-redirect-gateway-flags-list)

redirect-gateway-ipv6;

Automatically execute routing commands to cause all outgoing IPv6 traffic to be redirected over the VPN. The default route is overriden by specifying route for ::/1 and 8000::/1.

dhcp-option 0;

dhcp-option domain domain;

dhcp-option dns dns;

dhcp-option wins wins;

dhcp-option nbdd nbdd;

dhcp-option ntp ntp;

dhcp-option nbt nbt;

dhcp-option nbs nbs;

dhcp-option disable-nbt;

Set extended TAP-Win32 TCP/IP properties. This option can be used to set additional TCP/IP properties on the TAP-Win32 adapter, and is particularly useful for configuring an OpenVPN client to access a Samba server across the VPN.

Note that if dhcp-option is pushed via push to a non-windows client, the option will be saved in the client's environment before the up script is called, under the name "foreign_option_{n}".

<branching element> (type: ovpn-dhcp-option)

domain (type: str)

Set Connection-specific DNS Suffix.

dns (type: addr)

Set primary domain name server address. Repeat this option to set secondary DNS server addresses.

wins (type: addr)

Set primary WINS server address (NetBIOS over TCP/IP Name Server). Repeat this option to set secondary WINS server addresses.

nbdd (type: addr)

Set primary NBDD server address (NetBIOS over TCP/IP Datagram Distribution Server) Repeat this option to set secondary NBDD server addresses.

ntp (type: addr)

Set primary NTP server address (Network Time Protocol). Repeat this option to set secondary NTP server addresses.

nbt (type: uint8)

Set NetBIOS over TCP/IP Node type. Possible options: 1 = b-node (broadcasts), 2 = p-node (point-to-point name queries to a WINS server), 4 = m-node (broadcast then query name server), and 8 = h-node (query name server, then broadcast).

nbs (type: str)

Set NetBIOS over TCP/IP Scope. A NetBIOS Scope ID provides an extended naming service for the NetBIOS over TCP/IP (Known as NBT) module. The primary purpose of a NetBIOS scope ID is to isolate NetBIOS traffic on a single network to only those nodes with the same NetBIOS scope ID. The NetBIOS scope ID is a character string that is appended to the NetBIOS name. The NetBIOS scope ID on two hosts must match, or the two hosts will not be able to communicate. The NetBIOS Scope ID also allows computers to use the same computer name, as they have different scope IDs. The Scope ID becomes a part of the NetBIOS name, making the name unique. (This description of NetBIOS scopes courtesy of NeonSurge@abyss.com)

raw row;

An raw item to be put to the OpenVPN configuration file exactly as given as the "row" element.

row (type: str)

[End of section ovpn-push description.]

ovpn-ccd name {


  ifconfig-push ... ;
  ifconfig-ipv6-push ... ;
  disable ... ;
  push { ... }
  push-reset ... ;
* iroute ... ;
* iroute-ipv6 ... ;
* route ... ;
* schedule ... ;
* raw ... ;
  cn ... ;
}

        

Client-configuration-directives.

Set of the custom configuration directives to be used for the particular client. After the client has been authenticated, the ccd section with the same name as the client's X509 common name is used.

Constraints:

ROUTE can only be used with IFCONFIG-PUSH.

Items & subsections:

ifconfig-push local;

Push virtual local IP endpoint for client tunnel, overriding the ifconfig-pool dynamic allocation.

Note that the parameter local is from the perspective of the client, not the server.

For a tun interface, the remote address is constructed from the local IP address. For a tap interface, the netmask is taken from ^interface.ipv4.net. (Note that the eventual netmask is ignored for the local element).

local (type: addr)

ifconfig-ipv6-push local;

Push virtual local IPv6 endpoint for client tunnel, overriding the ifconfig-ipv6-pool dynamic allocation.

Note that the parameter local is from the perspective of the client, not the server.

For a tun interface, the remote address is constructed from the local IP address. For a tap interface, the netmask is taken from ^interface.ipv4.net. (Note that the eventual netmask is ignored for the local element).

local (type: addr)

disable;

Disable a particular client (based on the common name) from connecting. Don't use this option to disable a client due to key or password compromise. Use a CRL (certificate revocation list) instead (see the crl-verify option).

push {


* route ... ;
* route-ipv6 ... ;
  redirect-gateway ... ;
  redirect-gateway-ipv6 ... ;
* dhcp-option ... ;
* raw ... ;
}

            

The push section is derived from ovpn-push section prototype. For detail description of it, see above.

push-reset;

Don't inherit the global push list for a specific client instance.

This option will ignore push options at the global config file level.

iroute network;

Generate an internal route to a specific client.

This directive can be used to route a fixed subnet from the server to a particular client, regardless of where the client is connecting from. Remember that you must also add the route to the system routing table as well. The reason why two routes are needed is that the "system route" routes the packet fromthe kernel to OpenVPN. Once in OpenVPN, the iroute directive routes to the specific client.

The iroute directive also has an important interaction with push "route ...". iroute essentially defines a subnet which is owned by a particular client (we will call this client A). If you would like other clients to be able to reach A's subnet, you can use push "route ..." together with client-to-client to effect this. In order for all clients to see A's subnet, OpenVPN must push this route to all clients EXCEPT for A, since the subnet is already owned by A. OpenVPN accomplishes this by not not pushing a route to a client if it matches one of the client's iroutes.

network (type: net)

iroute-ipv6 ipv6addr;

For ccd per-client static IPv6 route configuration, see IROUTE for more details how to setup and use this, and how IROUTE and ROUTE interact.

ipv6addr (type: net)

route network;

The given network should be routed through this client as a gateway. The route is added as an iroute to the ccd section, as a route for the openvpn instance and as the system route.

network (type: net)

Route destination

schedule perm [day day] [month month] [wday [hhmm]];

Schedule the permissions. The order of this repeatable item is significant. The first matching schedule item is used. Depending on its perm element, the connection is either enabled or disabled. The permissions are checked either when the client is actually connecting as well as it is periodically checked in order to disconnect the clietns whose permission would eventually expire.

perm (type: enabling)

day day (type: uint8-set, optional, default: *)

day of month (1 - 31)

month month (type: month-set, optional, default: *)

month (Jan - Dec or 1 - 12)

wday (type: week-day-set, optional, default: *)

week-day (Sun - Sat or 0 - 6)

hhmm (type: time-set, optional, default: *)

time (in form hhmm)

raw row;

An raw item to be put to the OpenVPN configuration file exactly as given as the "row" element.

row (type: str)

cn cn;

Entry condition: Common name (CN).

If given, common name of the client is compared to the given string. Else, the name of the ccd section is compared to the CN. In that case, spaces (' ') and dots ('.') in the CN are substituted by underscore ('_').

cn (type: str)

[End of section ovpn-ccd description.]

ovpn-summary {


  top-clients ... ;
  top-users ... ;
  activity-report { ... }
}

        

The ovpn-summary section is derived from summary section prototype. For detail description of it, see application(5).

Changes to the ovpn-summary section:

Item top-groups is not valid.

Item top-servers is not valid.

Item top-categories is not valid.

Item top-senders is not valid.

Item top-recipients is not valid.

Item top-mime-types is not valid.

Item top-qnames is not valid.

Item top-qtypes is not valid.

Item top-callers is not valid.

Item top-receivers is not valid.

Item top-sids is not valid.

Item top-server-ports is not valid.

Item spam-threshold is not valid.

Item top-src-ips is not valid.

Item top-dst-ips is not valid.

Item top-rules is not valid.

openvpn name {


  stats-daily { ... }
  stats-weekly { ... }
  stats-monthly { ... }
  interface ... ;
  topology ... ;
  local ... ;
  nobind ... ;
  user ... ;
  group ... ;
  persist-tun ... ;
  persist-key ... ;
  log-debug { ... }
  log-stats { ... }
  mute ... ;
  ping-timer-rem ... ;
  keepalive ... ;
  proto ... ;
  tls-mat ... ;
  dh ... ;
  secret ... ;
  crl-verify ... ;
  server ... ;
  max-clients ... ;
  duplicate-cn ... ;
  client-to-client ... ;
  ccd-exclusive ... ;
  mlock ... ;
  float ... ;
  push { ... }
  ifconfig-pool ... ;
  ifconfig-ipv6-pool ... ;
  tls-server ... ;
  tls-client ... ;
* remote ... ;
  remote-random ... ;
  comp-lzo ... ;
  verify-x509-name ... ;
  ns-cert-type ... ;
  remote-cert-ku ... ;
  remote-cert-eku ... ;
  remote-cert-tls ... ;
  cipher ... ;
  client ... ;
  pull ... ;
  route-nopull ... ;
  no-ifconfig-noexec ... ;
  client-connect ... ;
  client-connect-socket ... ;
* ccd name { ... }
* raw ... ;
  phase ... ;
* tag ... ;
  socket-root ... ;
  fast-io ... ;
}

        

OpenVPN configuration.

For configuration attributes details, see openvpn(8).

Constraints:

INTERFACE must be specified.

ROUTE-NOPULL must be specified if CLIENT or PULL is used.

CLIENT, TLS-CLIENT, SERVER, TLS-SERVER and SECRET are mutually exclusive.

Cryptographic material (TLS-MAT) required for any of SERVER, TLS-SERVER, CLIENT, TLS-CLIENT.

tls options (DH, TLS-MAT, PKCS12, VERIFY-X509-NAME, CRL-VERIFY, NS-CERT-TYPE, REMOTE-CERT-KU, REMOTE-CERT-EKU) can only be specified in tls mode (SERVER, TLS-SERVER, CLIENT, TLS-CLIENT).

DH required for SERVER or TLS-SERVER.

Each of IFCONFIG-POOL, CLIENT-CONNECT, CCD, CCD-EXCLUSIVE, CLIENT-TO-CLIENT, DUPLICATE-CN requires SERVER.

CCD-EXCLUSIVE requires some CCD section.

SERVER may be used only with proto UDP or TCP-SERVER.

PULL can only be used with CLIENT, TLS-CLIENT or TLS-SERVER.

REMOTE ad SERVER are mutually exclusive.

REMOTE must be used in proto mode TCP-CLIENT.

proto mode TCP-SERVER allows at most one REMOTE.

NOBIND can only be used with REMOTE and without LOCAL.

Items PROTO, LOCAL and REMOTE must respect each other's address family.

Item SERVER is mutually exclusive with items IFCONFIG-POOL and IFCONFIG-IPV6-POOL.

Cipher AES-GCM is not supported in SECRET mode.

FAST-IO mode is allowed only in UDP.

Items & subsections:

stats-daily {


  top-clients ... ;
  top-users ... ;
  activity-report { ... }
}

            

The stats-daily section is derived from ovpn-summary section prototype. For detail description of it, see above.

stats-weekly {


  top-clients ... ;
  top-users ... ;
  activity-report { ... }
}

            

The stats-weekly section is derived from ovpn-summary section prototype. For detail description of it, see above.

stats-monthly {


  top-clients ... ;
  top-users ... ;
  activity-report { ... }
}

            

The stats-monthly section is derived from ovpn-summary section prototype. For detail description of it, see above.

interface ifname;

Interface to be used for the virtual network.

The interface must be of type TUN or TAP. The interface.ipv4.addr specifies the local IP addressin the VPN and the network range of the VPN. For TUN, the ipv4.dest address specifies the address of the peer in the tunnel.

ifname (type: name of interface, see interface(5))

topology topo;

OpenVPN network topology.

If omitted, default topology (net30) is used.

topo (type: ovpn-topology)

local any [port];

local [addr] addr [port];

Local IP address and port for bind. If specified, OpenVPN will bind to this address only. If unspecified, OpenVPN will bind to all interfaces, using the default port.

<branching element> (type: ovpn-local-scope, optional, default: addr)

addr (type: addr)

IP address to listen on

port (type: port, optional, default: 1194)

Port to listen on

nobind;

Do not bind to local address and port. This option is only suitable for peers which will be initiating connections by using remote intem.

user [user];

Change the user ID of the OpenVPN process to user after initialization, dropping privileges in the process. This option is useful to protect the system in the event that some hostile party was able to gain control of an OpenVPN session. Though OpenVPN's security features make this unlikely, it is provided as a second line of defense.

user (type: str, optional, default: "kernun")

group [group];

Change the group ID of the OpenVPN process to group after initialization, dropping privileges in the process. This option is useful to protect the system in the event that some hostile party was able to gain control of an OpenVPN session. Though OpenVPN's security features make this unlikely, it is provided as a second line of defense.

group (type: str, optional, default: "kernun")

persist-tun [persist-tun];

Don't close and reopen TUN/TAP device or run up/down scripts across SIGUSR1 or ping-restart restarts.

SIGUSR1 is a restart signal similar to SIGHUP, but which offers finer-grained control over reset options.

persist-tun (type: yes-no, optional, default: yes)

persist-key [persist-key];

Don't re-read key files across SIGUSR1 or ping-restart.

This option can be combined with user item to allow restarts triggered by the SIGUSR1 signal. Normally if you drop root privileges in OpenVPN, the daemon cannot be restarted since it will now be unable to reread protected key files.

This option solves the problem by persisting keys across SIGUSR1 resets, so they don't need to be re-read.

persist-key (type: yes-no, optional, default: yes)

log-debug {


  level ... ;
  mem-level ... ;
  facility ... ;
  file ... ;
  rotate ... ;
  mem-file ... ;
  syslog-failure ... ;
  data-limit ... ;
  dump-hold-time ... ;
}

            

The log-debug section is derived from log section prototype. For detail description of it, see log(5).

log-stats {


  level ... ;
  mem-level ... ;
  facility ... ;
  file ... ;
  rotate ... ;
  mem-file ... ;
  syslog-failure ... ;
  data-limit ... ;
  dump-hold-time ... ;
}

            

The log-stats section is derived from log section prototype. For detail description of it, see log(5).

mute [n];

Log at most n consecutive messages in the same category. This is useful to limit repetitive logging of similar message types.

n (type: uint16, optional, default: 10)

ping-timer-rem [ping-timer-rem];

Run the ping-exit /ping-restart timer only if we have a remote address. Use this option if you are starting the daemon in listen mode (i.e. without an explicit remote peer), and you don't want to start clocking timeouts until a remote peer connects.

ping-timer-rem (type: yes-no, optional, default: yes)

keepalive [ping [ping-restart]];

A helper directive designed to simplify the expression of ping and ping-restart. See openvpn(8) for details on ping, ping-restart and keepalive directives.

ping (type: uint16, optional, default: 10)

ping-restart (type: uint16, optional, default: 60)

proto [proto];

Specify the protocol to be used for communicating with remote host.

OpenVPN is designed to operate optimally over UDP, but TCP capability is provided for situations where UDP cannot be used. In comparison with UDP, TCP will usually be somewhat less efficient and less robust when used over unreliable or congested networks.

There are certain cases, however, where using TCP may be advantageous from a security and robustness perspective, such as tunneling non-IP or application-level UDP protocols, or tunneling protocols which don't possess a built-in reliability layer.

proto (type: ovpn-protocols, optional, default: udp)

tls-mat pkcs12 pkcs12;

tls-mat [ca-cert-key] ca cert key;

Specify the cryptographic material: root CA certificate, the local peer's certificate (signed by the CA), and the local peer's private key. It can be provided either as a single PKCS#12 file or as 3 files in .pem format.

<branching element> (type: tls-mat-variants, optional, default: ca-cert-key)

pkcs12 (type: name of shared-file, see common(5))

PKCS #12 file

ca (type: name of shared-file, see common(5))

Certificate authority

cert (type: name of shared-file, see common(5))

Local peer's certificate

key (type: name of shared-file, see common(5))

Local peer's private key

dh dh;

File containing Diffie Hellman parameters in .pem format Diffie Hellman parameters may be considered public.

dh (type: name of shared-file, see common(5))

secret secret;

Static Key encryption mode (non-TLS). The same pre-shared secret file is used by both peers.

secret (type: name of shared-file, see common(5))

crl-verify crl;

Check peer certificate against the file CRL (certificate revocation list) in PEM format. A CRL is used when a particular key is compromised but when the overall PKI is still intact.

crl (type: name of shared-file, see common(5))

server;

This directive will set up an OpenVPN server. It will allocate addresses to clients out of network/netmask specified in the referenced INTERFACE section. The server itself will take the first host address of the given network (which should be specified as the interface.ipv4.addr) for use as the server-side endpoint of the local TUN/TAP interface. For TUN, the next address (second host address of the given network) should be used as interface.ipv4.dest.

max-clients n;

Limit server to a maximum of n concurrent clients.

n (type: uint16)

duplicate-cn;

Allow multiple clients with the same common name to concurrently connect. In the absence of this option, OpenVPN will disconnect a client instance upon connection of a new client having the same common name.

client-to-client;

Because the OpenVPN server mode handles multiple clients through a single tun or tap interface, it is effectively a router. The client-to-client flag tells OpenVPN to internally route client-to-client traffic rather than pushing all client-originating traffic to the TUN/TAP interface.

When this option is used, each client will "see" the other clients which are currently connected. Otherwise, each client will only see the server. Don't use this option if you want to firewall tunnel traffic using custom, per-client rules.

ccd-exclusive;

Require, as a condition of authentication, that a connecting client has an explicit ccd section.

mlock;

Disable paging by calling the POSIX mlockall function.

Using this option ensures that key material and tunnel data are never written to disk due to virtual memory paging operations which occur under most modern operating systems. It ensures that even if an attacker was able to crack the box running OpenVPN, he would not be able to scan the system swap file to recover previously used ephemeral keys, which are used for a period of time, and then are discarded.

The downside of using mlock is that it will reduce the amount of physical memory available to other applications.

float;

Allow remote peer to change its IP address and/or port number, such as due to DHCP (this is the default if remote is not used). float when specified with remote allows an OpenVPN session to initially connect to a peer at a known address, however if packets arrive from a new address and pass all authentication tests, the new address will take control of the session. This is useful when you are connecting to a peer which holds a dynamic address such as a dial-in user or DHCP client.

Essentially, float tells OpenVPN to accept authenticated packets from any address, not only the address which was specified in the remote option.

push {


* route ... ;
* route-ipv6 ... ;
  redirect-gateway ... ;
  redirect-gateway-ipv6 ... ;
* dhcp-option ... ;
* raw ... ;
}

            

The push section is derived from ovpn-push section prototype. For detail description of it, see above.

ifconfig-pool start-ip end-ip [warn warn];

Set aside a pool of subnets to be dynamically allocated to connecting clients, similar to a DHCP server. For tun-style tunnels, each client will be given a /30 subnet (for interoperability with Windows clients). For tap-style tunnels, individual addresses will be allocated, and the netmask parameter will also be pushed to clients. The netmask value is taken from ^interface.ipv4.addr. (Note that the eventual netmask is ignored for both start-IP and end_ip elements).

start-ip (type: addr)

end-ip (type: addr)

warn warn (type: yes-no, optional, default: yes)

Warn on conflicts between ifconfig-pool and ccd.ifconfig-push items.

ifconfig-ipv6-pool ipv6addr [warn warn];

Specify an IPv6 address pool for dynamic assignment to clients. The pool starts at ipv6addr and increments by +1 for every new client (linear mode). The /bits setting controls the size of the pool.

ipv6addr (type: addr)

warn warn (type: yes-no, optional, default: yes)

Warn on conflicts between ifconfig-pool and ccd.ifconfig-push items.

tls-server;

Enable TLS and assume server role during TLS handshake. Note that OpenVPN is designed as a peer-to-peer application. The designation of client or server is only for the purpose of negotiating the TLS control channel.

tls-client;

Enable TLS and assume client role during TLS handshake.

remote host [port [proto]];

Remote host name or IP address. On the client, multiple remote items may be specified for redundancy, each referring to a different OpenVPN server.

If host is a DNS name which resolves to multiple IP addresses, one will be randomly chosen, providing a sort of basic load-balancing and failover capability.

host (type: host)

Host to connect to

port (type: uint16, optional, default: 1194)

Port to connect to

proto (type: ovpn-remote-proto, optional, default: implicit)

protocol to use when connecting with the remote

remote-random;

When multiple remote items are specified, initially randomize the order of the list as a kind of basic load-balancing measure.

comp-lzo [mode];

Use fast LZO compression. May add up to 1 byte per packet for incompressible data.

mode (type: ovpn-comp-lzo-mode, optional, default: adaptive)

verify-x509-name name;

Accept connections only from a host with X509 common name equal to name. The remote host must also pass all other tests of verification.

name (type: str)

ns-cert-type type;

Require that peer certificate was signed with an explicit nsCertType designation of "client" or "server".

This is a useful security option for clients, to ensure that the host they connect with is a designated server.

type (type: ovpn-cert-types)

remote-cert-ku ku;

Require that peer certificate was signed with an explicit key usage.

This is a useful security option for clients, to ensure that the host they connect to is a designated server.

The key usage should be encoded in hex, more than one key usage can be specified.

ku (type: str)

remote-cert-eku oid;

Require that peer certificate was signed with an explicit extended key usage.

This is a useful security option for clients, to ensure that the host they connect to is a designated server.

The extended key usage should be encoded in oid notation, or OpenSSL symbolic representation.

oid (type: str)

remote-cert-tls tls;

Require that peer certificate was signed with an explicit key usage and extended key usage based on RFC3280 TLS rules.

This is a useful security option for clients, to ensure that the host they connect to is a designated server.

The remote-cert-tls client option is equivalent to remote-cert-ku 80 08 88 remote-cert-eku "TLS Web Client Authentication"

The key usage is digitalSignature and/or keyAgreement.

The remote-cert-tls server option is equivalent to remotecert-ku a0 88 remote-cert-eku "TLS Web Server Authentication"

The key usage is digitalSignature and ( keyEncipherment or keyAgreement).

This is an important security precaution to protect against a man-in-the-middle attack where an authorized client attempts to connect to another client by impersonating the server. The attack is easily prevented by having clients verify the server certificate using any one of remote-cert-tls, verify-x509-name, or tls-verify.

tls (type: ovpn-cert-types)

cipher [alg];

Encrypt packets with cipher algorithm alg. The default is AES-256-CBC.

alg (type: ovpn-cipher-algs, optional, default: AES-256-CBC)

client;

A helper directive designed to simplify the configuration of OpenVPN's client mode. This directive is equivalent to using pull and tls-client.

pull;

This option must be used on a client which is connecting to a multi-client server. It indicates to OpenVPN that it should accept options pushed by the server, provided they are part of the legal set of pushable options (note that the pull option is implied by client).

route-nopull;

When used with client or pull, accept options pushed by server EXCEPT for routes.

When used on the client, this option effectively bars the server from adding routes to the client's routing table, however note that this option still allows the server to set the TCP/IP properties of the client's TUN/TAP interface.

no-ifconfig-noexec;

The interface configuration and management is independent on the OpenVPN in Kernun by default. This way, the TUN/TAP interface is configured constantly, as well as the routes specified in the routes section. Therefore, OpenVPN is not expected to configure the interface. In order to override this default (not to generate ifconfig-noexec into openvpn configuration), use this item

client-connect client-connect-script;

A script that is run upon each client's connection. The common name (cn) of the client being connected is passed to the script as the parameter. If the script exits with the exit code 0, the client connection is enabled (the client still can be denied by other items in the configuration, i.e. ccd.disable, etc.). If the script exits with the exit code not 0, the client connection is denied immediately. Be sure to re-generate the configuration after eventual change made to the script.

client-connect-script (type: name of shared-file, see common(5))

client-connect-socket filename;

The socket for determining whether the particular client is permitted to connect at the moment. Kernun opens the socket, writes a command in form 'cc instance common-name' to it. If Kernun reads back word 'accept' from the socket, the client is considered permitted by the client-connect-socket. The client is blocked otherwise. Notice that even if the client is permitted by client-connect-socket, it maight still be blocked by some other part of the configuration.

filename (type: str)

ccd name {


  ifconfig-push ... ;
  ifconfig-ipv6-push ... ;
  disable ... ;
  push { ... }
  push-reset ... ;
* iroute ... ;
* iroute-ipv6 ... ;
* route ... ;
* schedule ... ;
* raw ... ;
  cn ... ;
}

            

The ccd section is derived from ovpn-ccd section prototype. For detail description of it, see above.

raw row;

An raw item to be put to the OpenVPN configuration file exactly as given as the "row" element.

row (type: str)

phase [number];

Application Startup Phase.

number (type: uint8, optional, default: 40)

Phase number; the lower one, the earlier start.

tag value;

Configuration factorization tag.

This feature allows admin to create groups of Kernun applications (specially proxies and servers) according to various aspects (belonging to one customer, applications of particular network traffic etc.).

Each application can have several tag attributes and the KAT tool can run some commands (like 'ps', 'start' atc.) for applications with or without given tag.

value (type: str)

Constraints:

Tag must contain letters, digits, hyphens and dots, only.

socket-root [path];

Prefix of the path of the sockets used by openvpn. The sockets (ccd-provider, manage) are created in subdirectory openvpn.NAME within the directory given in the path element. The default is usually the desired value.

path (type: str, optional, default: "/usr/local/etc")

fast-io;

Optimize I/O writes to avoid polling.

Experimental OpenVPN feature, see openvpn(8).

[End of section openvpn description.]

SEE ALSO

configuration(7), application(5), common(5), interface(5), log(5), time(5), openvpn(8)