ocserv(8)

NAME
*[B-Font]ocserv - OpenConnect VPN server

SYNOPSIS
Openconnect VPN server (ocserv) is a VPN server compatible with the openconnect VPN client. It follows the AnyConnect VPN protocol which is used by several CISCO routers.

DESCRIPTION
This a standalone server that reads a configuration file (see below for more details), and waits for client connections. Log messages are redirected to daemon facility.

The server maintains two connections/channels with the client. The main VPN channel is established over TCP, HTTP and TLS. This is the control channel as well as the backup data channel. After its establishment a UDP channel using DTLS is initiated which serves as the main data channel. If the UDP channel fails to establish or is temporarily unavailable the backup channel over TCP/TLS is being used.

This server supports multiple authentication methods, including PAM and certificate authentication. Authenticated users are assigned an unprivileged worker process and obtain a networking (tun) device and an IP from a configurable pool of addresses.

Once authenticated, the server provides the client with an IP address and a list of routes that it may access. In order to allow high-speed transfers the server does not process or filter packets. It is expected that the server has or will set up any required routes or firewall rules.

It is possible to separate users into groups, which are either present on their certificate, or presented on login for the user to choose. That way a user may take advantage of the different settings that may apply per group. See the comments on the configuration file for more information.

OPTIONS

Do not fork into background.

Enable verbose network debugging information.
    This option takes an integer number as its argument. The value of *[I-Font]number is constrained to being:
    in the range  0 through 9999

Configuration file for the server.

Test the provided configuration file.

Specify pid file for the server.

Display usage information and exit.

Pass the extended usage information through a pager.

Output version of program and exit.  The default mode is `v', a simple
    version. The `c' mode will print copyright information and `n' will print the full copyright notice.

AUTHENTICATION
Users can be authenticated in multiple ways, which are explained in the following paragraphs. Connected users can be managed using the 'occtl' tool.

Password authentication
If your system supports Pluggable Authentication Modules (PAM), then ocserv will take advantage of it to password authenticate its users. Otherwise a plain password file similar to the UNIX password file is also supported. In that case the 'ocpasswd' tool can be used for its management. Note that password authentication can be used in conjunction with certificate authentication.

GSSAPI authentication
ocserv will take advantage of the MIT Kerberos project GSSAPI libraries, and allow authentication using any method GSSAPI supports. That is, mainly, Kerberos authentication. That is often more useful to be combined with PAM or other password authentication methods so that a fallback mechanism can be used when GSSAPI fails (e.g., when the user doesn't already have a Kerberos ticket). The GSSAPI authentication is implemented using SPNEGO over HTTP (RFC4559).

Public key (certificate) authentication
Public key authentication allows the user to be authenticated by the possession of the private key that corresponds to a known to the server public key. That allows the usage of common smart cards for user authentication.

In ocserv, a certificate authority (CA) is used to sign the client certificates. That certificate authority can be local, used only by the server to sign its user's known public keys which are then given to users in a form of certificates. That authority need also provide a CRL to allow the server to reject the revoked clients (see ca-cert, crl).

In certificate authentication each client presents a certificate and signs data provided by the server, as part of TLS authentication, to prove his possession of the corresponding private key. The certificate need also contain user identifying information, for example, the user ID of the client must be embedded in the certificate's Distinguished Name (DN), i.e., in the Common Name, or UID fields. For the server to read the name, the cert-user-oid configuration option must be set.

The following examples demonstrate how to use certtool from GnuTLS to generate such CA.

Generating the CA
$ certtool --generate-privkey --outfile ca-key.pem
$ cat << _EOF_ >ca.tmpl
cn = "VPN CA"
organization = "Big Corp"
serial = 1
expiration_days = -1
ca
signing_key
cert_signing_key
crl_signing_key
_EOF_
$ certtool --generate-self-signed --load-privkey ca-key.pem --template ca.tmpl --outfile ca-cert.pem

Generating a local server certificate
The following example generates the server key and certificate pair. The key generated is an RSA one, but different types can be used by specifying the 'ecdsa' or 'dsa' options to certtool.
$ certtool --generate-privkey --outfile server-key.pem
$ cat << _EOF_ >server.tmpl
cn = "VPN server"
dns_name = "www.example.com"
dns_name = "vpn1.example.com"
#ip_address = "1.2.3.4"
organization = "MyCompany"
expiration_days = -1
signing_key
encryption_key #only if the generated key is an RSA one
tls_www_server
_EOF_
$ certtool --generate-certificate --load-privkey server-key.pem --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem --template server.tmpl --outfile server-cert.pem

From this point the clients need ca-cert.pem to be able to securely connect to the server.

Note that it is a better practice to use two separate RSA keys, one with the signing_key option and another with the encryption_key.

Generating an external CA-signed server certificate
$ certtool --generate-privkey --outfile server-key.pem
$ cat << _EOF_ >server.tmpl
cn = "My server"
dns_name = "www.example.com"
organization = "MyCompany"
expiration_days = -1
signing_key
encryption_key #only if the generated key is an RSA one
tls_www_server
_EOF_
$ certtool --generate-request --load-privkey server-key.pem --template server.tmpl --outfile server-cert.csr

At this point you need to provide the server-cert.csr to your CA, and they will send you the server certificate.

Generating the client certificates
Note that it is recommended to leave detailed personal information out of the certificate as it is sent in clear during TLS authentication. The following process generates a certificate and converts it to PKCS #12 that is protected by a PIN and most clients are able to import (the 3DES cipher is used in the example because it is supported by far more devices than AES).

$ certtool --generate-privkey --outfile user-key.pem
$ cat << _EOF_ >user.tmpl
cn = "user"
unit = "admins"
expiration_days = 365
signing_key
tls_www_client
_EOF_
$ certtool --generate-certificate --load-privkey user-key.pem --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem --template user.tmpl --outfile user-cert.pem

$ certtool --to-p12 --load-privkey user-key.pem --pkcs-cipher 3des-pkcs12 --load-certificate user-cert.pem --outfile user.p12 --outder

Revoking a client certificate
To revoke the previous client certificate, i.e., preventing the user from accessing the VPN resources prior to its certificate expiration, use:
$ cat << _EOF_ >crl.tmpl
crl_next_update = 365
crl_number = 1
_EOF_
$ cat user-cert.pem >>revoked.pem
$ certtool --generate-crl --load-ca-privkey ca-key.pem --load-ca-certificate ca-cert.pem --load-certificate revoked.pem --template crl.tmpl --outfile crl.pem
After that you may want to notify ocserv of the new CRL by using the HUP signal, or wait for it to reload it.

When there are no revoked certificates an empty revocation list should be generated as follows.
$ certtool --generate-crl --load-ca-privkey ca-key.pem --load-ca-certificate ca-cert.pem --template crl.tmpl --outfile crl.pem

NETWORKING CONSIDERATIONS
In certain setups, where a firewall may be blocking ICMP responses, setting the MSS of TCP connections to MTU will eliminate the "black hole" connection issues. See http://lartc.org/howto/lartc.cookbook.mtu-mss.html for instructions to enable it on a Linux system.

IMPLEMENTATION NOTES
Note that while this server utilizes privilege separation and all authentication occurs on the security module, this does not apply for TLS client certificate authentication. That is due to TLS protocol limitation.

FILES
ocserv's configuration file format
By default, if no other file is specified, ocserv looks for its configuration file at /etc/ocserv/ocserv.conf. An example configuration file follows.

# User authentication method. Could be set multiple times and in
# that case all should succeed. To enable multiple methods use
# multiple auth directives. Available options: certificate,
# plain, pam, radius, gssapi. Note that authentication methods
# utilizing passwords cannot be combined (e.g., the plain, pam
# or radius methods).
#
# Note that authentication methods cannot be changed with reload.

# certificate:
#  This indicates that all connecting users must present a certificate.
#  The username and user group will be then extracted from it (see
#  cert-user-oid and cert-group-oid). The certificate to be accepted
#  it must be signed by the CA certificate as specified in 'ca-cert' and
#  it must not be listed in the CRL, as specified by the 'crl' option.
#
# pam[gid-min=1000]:
#  This enabled PAM authentication of the user. The gid-min option is used
# by auto-select-group option, in order to select the minimum valid group ID.
#
# plain[passwd=/etc/ocserv/ocpasswd,otp=/etc/ocserv/users.otp]
#  The plain option requires specifying a password file which contains
# entries of the following format.
# "username:groupname1,groupname2:encoded-password"
# One entry must be listed per line, and 'ocpasswd' should be used
# to generate password entries. The 'otp' suboption allows one to specify
# an oath password file to be used for one time passwords; the format of
# the file is described in https://code.google.com/p/mod-authn-otp/wiki/UsersFile
#
# radius[config=/etc/radiusclient/radiusclient.conf,groupconfig=true,nas-identifier=name]:
#  The radius option requires specifying freeradius-client configuration
# file. If the groupconfig option is set, then config-per-user/group will be overridden,
# and all configuration will be read from radius. That also includes the
# Acct-Interim-Interval, and Session-Timeout values.
#
# See doc/README-radius.md for the supported radius configuration atributes.
#
# gssapi[keytab=/etc/key.tab,require-local-user-map=false,tgt-freshness-time=900,gid-min=1000]
#  The gssapi option allows one to use authentication methods supported by GSSAPI,
# such as Kerberos tickets with ocserv. It should be best used as an alternative
# to PAM (i.e., have pam in auth and gssapi in enable-auth), to allow users with
# tickets and without tickets to login. The default value for require-local-user-map
# is true. The 'tgt-freshness-time' if set, it would require the TGT tickets presented
# to have been issued within the provided number of seconds. That option is used to
# restrict logins even if the KDC provides long time TGT tickets.
# The gid-min option is used by auto-select-group option, in order to select the minimum
# valid group ID.

#auth = "certificate"
#auth = "pam"
#auth = "pam[gid-min=1000]"
#auth = "plain[passwd=/etc/ocserv/ocpasswd]"
#auth = "radius[config=/etc/radiusclient/radiusclient.conf,groupconfig=true]"

# Specify alternative authentication methods that are sufficient
# for authentication. That is, if set, any of the methods enabled
# will be sufficient to login.
#enable-auth = "certificate"
#enable-auth = "gssapi"
#enable-auth = "gssapi[keytab=/etc/key.tab,require-local-user-map=true,tgt-freshness-time=900]"

# Accounting methods available:
# radius: can be combined with any authentication method, it provides
#      radius accounting to available users (see also stats-report-time).
#
# pam: can be combined with any authentication method, it provides
#      a validation of the connecting user's name using PAM. It is
#      superfluous to use this method when authentication is already
#      PAM.
#
# Only one accounting method can be specified.
#acct = "radius[config=/etc/radiusclient/radiusclient.conf]"

# Use listen-host to limit to specific IPs or to the IPs of a provided
# hostname.
#listen-host = [IP|HOSTNAME]

# TCP and UDP port number
tcp-port = 4443
udp-port = 4443

# Accept connections using a socket file. It accepts HTTP
# connections (i.e., without SSL/TLS unlike its TCP counterpart),
# and uses it as the primary channel. That option is experimental
# and it has many known issues.
#  * It can only be combined with certificate authentication, when receiving
#    channel information through proxy protocol (see listen-proxy-proto)
#  * It cannot derive any keys needed for the DTLS session (hence no support for dtls-psk)
#  * It cannot enforce the framing of the SSL/TLS packets, and that
#    breaks assumptions held by several openconnect clients.
# This option is not recommended for use, and may be removed
# in the future.
#
#listen-clear-file = /var/run/ocserv-conn.socket

# The user the worker processes will be run as. It should be
# unique (no other services run as this user).
run-as-user = nobody
run-as-group = nogroup

# The default server directory. Does not require any devices present.
#chroot-dir = /path/to/chroot

# socket file used for IPC with occtl. You only need to set that,
# if you use more than a single servers.
#occtl-socket-file = /var/run/occtl.socket

# socket file used for server IPC (worker - sec-mod), will be appended with .PID
# It must be accessible within the chroot environment (if any), so it is best
# specified relatively to the chroot directory.
socket-file = /var/run/ocserv-socket

# The key and the certificates of the server
# The key may be a file, or any URL supported by GnuTLS (e.g.,
# tpmkey:uuid=xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx;storage=user
# or pkcs11:object=my-vpn-key;object-type=private)
#
# The server-cert file may contain a single certificate, or
# a sorted certificate chain.
#
# There may be multiple server-cert and server-key directives,
# but each key should correspond to the preceding certificate.
server-cert = /path/to/cert.pem
server-key = /path/to/key.pem

# The server provides following URL handlers to obtain the certificates
# configured above:
#  /cert.pem   Returns the server's certificate in PEM format
#  /cert.der   Returns the server's certificate in DER format
#  /ca.pem     Returns the server's CA certificate in PEM format
#  /ca.der     Returns the server's CA certificate in DER format
#

# Diffie-Hellman parameters. Only needed if you require support
# for the DHE ciphersuites (by default this server supports ECDHE).
# Can be generated using:
# certtool --generate-dh-params --outfile /path/to/dh.pem
#dh-params = /path/to/dh.pem

# In case PKCS #11, TPM or encrypted keys are used the PINs should be available
# in files. The srk-pin-file is applicable to TPM keys only, and is the
# storage root key.
#pin-file = /path/to/pin.txt
#srk-pin-file = /path/to/srkpin.txt

# The password or PIN needed to unlock the key in server-key file.
# Only needed if the file is encrypted or a PKCS #11 object. This
# is an alternative method to pin-file.
#key-pin = 1234

# The SRK PIN for TPM.
# This is an alternative method to srk-pin-file.
#srk-pin = 1234

# The Certificate Authority that will be used to verify
# client certificates (public keys) if certificate authentication
# is set.
#ca-cert = /path/to/ca.pem

### All configuration options below this line are reloaded on a SIGHUP.
### The options above, will remain unchanged. Note however, that the
### server-cert, server-key, dh-params and ca-cert options will be reloaded
### if the provided file changes, on server reload. That allows certificate
### rotation, but requires the server key to remain the same for seamless
### operation. If the server key changes on reload, there may be connection
### failures during the reloading time.

# Whether to enable seccomp/Linux namespaces worker isolation. That restricts the number of
# system calls allowed to a worker process, in order to reduce damage from a
# bug in the worker process. It is available on Linux systems at a performance cost.
# The performance cost is roughly 2% overhead at transfer time (tested on a Linux 3.17.8).
# Note however, that process isolation is restricted to the specific libc versions
# the isolation was tested at. If you get random failures on worker processes, try
# disabling that option and report the failures you, along with system and debugging
# information at: https://gitlab.com/ocserv/ocserv/issues
isolate-workers = true

# A banner to be displayed on clients
#banner = "Welcome"

# Limit the number of clients. Unset or set to zero for unlimited.
#max-clients = 1024
max-clients = 16

# Limit the number of identical clients (i.e., users connecting
# multiple times). Unset or set to zero for unlimited.
max-same-clients = 2

# When the server has a dynamic DNS address (that may change),
# should set that to true to ask the client to resolve again on
# reconnects.
#listen-host-is-dyndns = true

# When the server receives connections from a proxy, like haproxy
# which supports the proxy protocol, set this to obtain the correct
# client addresses. The proxy protocol (v2) would then be expected in
# the TCP or UNIX socket (not the UDP one). Although both v1
# and v2 versions of proxy protocol are supported, the v2 version
# is recommended as it is more efficient in parsing.
#listen-proxy-proto = true

# Limit the number of client connections to one every X milliseconds
# (X is the provided value). Set to zero for no limit.
#rate-limit-ms = 100

# Stats report time. The number of seconds after which each
# worker process will report its usage statistics (number of
# bytes transferred etc). This is useful when accounting like
# radius is in use.
#stats-report-time = 360

# Stats reset time. The period of time statistics kept by main/sec-mod
# processes will be reset. These are the statistics shown by cmd
# 'occtl show stats'. For daily: 86400, weekly: 604800
# This is unrelated to stats-report-time.
server-stats-reset-time = 604800

# Keepalive in seconds
keepalive = 32400

# Dead peer detection in seconds.
# Note that when the client is behind a NAT this value
# needs to be short enough to prevent the NAT disassociating
# his UDP session from the port number. Otherwise the client
# could have his UDP connection stalled, for several minutes.
dpd = 90

# Dead peer detection for mobile clients. That needs to
# be higher to prevent such clients being awaken too
# often by the DPD messages, and save battery.
# The mobile clients are distinguished from the header
# 'X-AnyConnect-Identifier-Platform'.
mobile-dpd = 1800

# If using DTLS, and no UDP traffic is received for this
# many seconds, attempt to send future traffic over the TCP
# connection instead, in an attempt to wake up the client
# in the case that there is a NAT and the UDP translation
# was deleted. If this is unset, do not attempt to use this
# recovery mechanism.
switch-to-tcp-timeout = 25

# MTU discovery (DPD must be enabled)
# If set, this forces all UDP packets to carry the don't fragment
# (DF) bit.
try-mtu-discovery = false

# The revocation list of the certificates issued by the 'ca-cert' above.
# See the manual to generate an empty CRL initially. The CRL will be reloaded
# periodically when ocserv detects a change in the file. To force a reload use
# SIGHUP.
#crl = /path/to/crl.pem

# If you have a certificate from a CA that provides an OCSP
# service you may provide a fresh OCSP status response within
# the TLS handshake. That will prevent the client from connecting
# independently on the OCSP server.
# You can update this response periodically using:
# ocsptool --ask --load-cert=your_cert --load-issuer=your_ca --outfile response
# Make sure that you replace the following file in an atomic way.
#ocsp-response = /path/to/ocsp.der

# The object identifier that will be used to read the user ID in the client
# certificate. The object identifier should be part of the certificate's DN
# Useful OIDs are:
#  CN = 2.5.4.3, UID = 0.9.2342.19200300.100.1.1, SAN(rfc822name)
#cert-user-oid = 0.9.2342.19200300.100.1.1

# The object identifier that will be used to read the user group in the
# client certificate. The object identifier should be part of the certificate's
# DN. If the user may belong to multiple groups, then use multiple such fields
# in the certificate's DN. Useful OIDs are:
#  OU (organizational unit) = 2.5.4.11
#cert-group-oid = 2.5.4.11

# Uncomment this to enable compression negotiation (LZS, LZ4).
#compression = true

# Set the minimum size under which a packet will not be compressed.
# That is to allow low-latency for VoIP packets. The default size
# is 256 bytes. Modify it if the clients typically use compression
# as well of VoIP with codecs that exceed the default value.
#no-compress-limit = 256

# GnuTLS priority string; note that SSL 3.0 is disabled by default
# as there are no openconnect (and possibly anyconnect clients) using
# that protocol. The string below does not enforce perfect forward
# secrecy, in order to be compatible with legacy clients.
#
# Note that the most performant ciphersuites are the moment are the ones
# involving AES-GCM. These are very fast in x86 and x86-64 hardware, and
# in addition require no padding, thus taking full advantage of the MTU.
# For that to be taken advantage of, the openconnect client must be
# used, and the server must be compiled against GnuTLS 3.2.7 or later.
# Use "gnutls-cli --benchmark-tls-ciphers", to see the performance
# difference with AES_128_CBC_SHA1 (the default for anyconnect clients)
# in your system.

tls-priorities = "NORMAL:%SERVER_PRECEDENCE:%COMPAT:-VERS-SSL3.0"

# More combinations in priority strings are available, check
# http://gnutls.org/manual/html_node/Priority-Strings.html
# E.g., the string below enforces perfect forward secrecy (PFS)
# on the main channel.
#tls-priorities = "NORMAL:%SERVER_PRECEDENCE:%COMPAT:-RSA:-VERS-SSL3.0:-ARCFOUR-128"

# That option requires the established DTLS channel to use the same
# cipher as the primary TLS channel. This cannot be combined with
# listen-clear-file since the ciphersuite information is not available
# in that configuration. Note also, that this option implies that
# dtls-legacy option is false; this option cannot be enforced
# in the legacy/compat protocol.
#match-tls-dtls-ciphers = true

# The time (in seconds) that a client is allowed to stay connected prior
# to authentication
auth-timeout = 240

# The time (in seconds) that a client is allowed to stay idle (no traffic)
# before being disconnected. Unset to disable.
#idle-timeout = 1200

# The time (in seconds) that a client is allowed to stay connected
# Unset to disable. When set a client will be disconnected after being
# continuously connected for this amount of time, and its cookies will
# be invalidated (i.e., re-authentication will be required).
#session-timeout = 86400

# The time (in seconds) that a mobile client is allowed to stay idle (no
# traffic) before being disconnected. Unset to disable.
#mobile-idle-timeout = 2400

# The time (in seconds) that a client is not allowed to reconnect after
# a failed authentication attempt.
min-reauth-time = 120

# Banning clients in ocserv works with a point system. IP addresses
# that get a score over that configured number are banned for
# min-reauth-time seconds. By default a wrong password attempt is 10 points,
# a KKDCP POST is 1 point, and a connection is 1 point. Note that
# due to difference processes being involved the count of points
# will not be real-time precise.
#
# Score banning cannot be reliably used when receiving proxied connections
# locally from an HTTP server (i.e., when listen-clear-file is used).
#
# Set to zero to disable.
max-ban-score = 80

# The time (in seconds) that all score kept for a client is reset.
ban-reset-time = 1200

# In case you'd like to change the default points.
#ban-points-wrong-password = 10
#ban-points-connection = 1
#ban-points-kkdcp = 1

# Cookie timeout (in seconds)
# Once a client is authenticated he's provided a cookie with
# which he can reconnect. That cookie will be invalidated if not
# used within this timeout value. This cookie remains valid, during
# the user's connected time, and after user disconnection it
# remains active for this amount of time. That setting should allow a
# reasonable amount of time for roaming between different networks.
cookie-timeout = 300

# If this is enabled (not recommended) the cookies will stay
# valid even after a user manually disconnects, and until they
# expire. This may improve roaming with some broken clients.
#persistent-cookies = true

# Whether roaming is allowed, i.e., if true a cookie is
# restricted to a single IP address and cannot be re-used
# from a different IP.
deny-roaming = false

# ReKey time (in seconds)
# ocserv will ask the client to refresh keys periodically once
# this amount of seconds is elapsed. Set to zero to disable (note
# that, some clients fail if rekey is disabled).
rekey-time = 172800

# ReKey method
# Valid options: ssl, new-tunnel
#  ssl: Will perform an efficient rehandshake on the channel allowing
#       a seamless connection during rekey.
#  new-tunnel: Will instruct the client to discard and re-establish the channel.
#       Use this option only if the connecting clients have issues with the ssl
#       option.
rekey-method = ssl

# Script to call when a client connects and obtains an IP.
# The following parameters are passed on the environment.
# REASON, USERNAME, GROUPNAME, DEVICE, IP_REAL (the real IP of the client),
# IP_REAL_LOCAL (the local interface IP the client connected), IP_LOCAL
# (the local IP in the P-t-P connection), IP_REMOTE (the VPN IP of the client),
# IPV6_LOCAL (the IPv6 local address if there are both IPv4 and IPv6
# assigned), IPV6_REMOTE (the IPv6 remote address), IPV6_PREFIX, and
# ID (a unique numeric ID); REASON may be "connect" or "disconnect".
# In addition the following variables OCSERV_ROUTES (the applied routes for this
# client), OCSERV_NO_ROUTES, OCSERV_DNS (the DNS servers for this client),
# will contain a space separated list of routes or DNS servers. A version
# of these variables with the 4 or 6 suffix will contain only the IPv4 or
# IPv6 values. Only the exit code of the connect script is considered.
# An exit code of non-zero results the user being denied access.

# The disconnect script will receive the additional values: STATS_BYTES_IN,
# STATS_BYTES_OUT, STATS_DURATION that contain a 64-bit counter of the bytes
# output from the tun device, and the duration of the session in seconds.

#connect-script = /usr/bin/myscript
#disconnect-script = /usr/bin/myscript

# Script to call when the client is connected and provides a hostname. This
# is called after the connect-script, if a hostname is provided by the user,
# and in addition to the previously stated variables it provides a HOSTNAME
# environment variable. That can be used with nsupdate, for example, to
# register the hostname on a DNS server. The REASON variable will be "host-update".
# The exit code of this script is ignored.
#host-update-script = /usr/bin/myscript

# UTMP
# Register the connected clients to utmp. This will allow viewing
# the connected clients using the command 'who'.
#use-utmp = true

# Whether to enable support for the occtl tool (i.e., either through D-BUS,
# or via a unix socket).
use-occtl = true

# PID file. It can be overridden in the command line.
pid-file = /var/run/ocserv.pid

# Set the protocol-defined priority (SO_PRIORITY) for packets to
# be sent. That is a number from 0 to 6 with 0 being the lowest
# priority. Alternatively this can be used to set the IP Type-
# Of-Service, by setting it to a hexadecimal number (e.g., 0x20).
# This can be set per user/group or globally.
#net-priority = 3

# Set the VPN worker process into a specific cgroup. This is Linux
# specific and can be set per user/group or globally.
#cgroup = "cpuset,cpu:test"

#
# Network settings
#

# The name to use for the tun device
device = vpns

# Whether the generated IPs will be predictable, i.e., IP stays the
# same for the same user when possible.
predictable-ips = true

# The default domain to be advertised
default-domain = example.com

# The pool of addresses that leases will be given from. If the leases
# are given via Radius, or via the explicit-ip? per-user config option then
# these network values should contain a network with at least a single
# address that will remain under the full control of ocserv (that is
# to be able to assign the local part of the tun device address).
# Note that, you could use addresses from a subnet of your LAN network if you
# enable proxy arp in the LAN interface (see http://infradead.org/ocserv/recipes-ocserv-pseudo-bridge.html);
# in that case it is recommended to set ping-leases to true.
ipv4-network = 192.168.1.0
ipv4-netmask = 255.255.255.0

# An alternative way of specifying the network:
#ipv4-network = 192.168.1.0/24

# The IPv6 subnet that leases will be given from.
ipv6-network = fda9:4efe:7e3b:03ea::/48

# Specify the size of the network to provide to clients. It is
# generally recommended to provide clients with a /64 network in
# IPv6, but any subnet may be specified. To provide clients only
# with a single IP use the prefix 128.
#ipv6-subnet-prefix = 128
#ipv6-subnet-prefix = 64

# Whether to tunnel all DNS queries via the VPN. This is the default
# when a default route is set.
#tunnel-all-dns = true

# The advertized DNS server. Use multiple lines for
# multiple servers.
# dns = fc00::4be0
dns = 192.168.1.2

# The NBNS server (if any)
#nbns = 192.168.1.3

# The domains over which the provided DNS should be used. Use
# multiple lines for multiple domains.
#split-dns = example.com

# Prior to leasing any IP from the pool ping it to verify that
# it is not in use by another (unrelated to this server) host.
# Only set to true, if there can be occupied addresses in the
# IP range for leases.
ping-leases = false

# Use this option to set a link MTU value to the incoming
# connections. Unset to use the default MTU of the TUN device.
# Note that the MTU is negotiated using the value set and the
# value sent by the peer.
#mtu = 1420

# Unset to enable bandwidth restrictions (in bytes/sec). The
# setting here is global, but can also be set per user or per group.
#rx-data-per-sec = 40000
#tx-data-per-sec = 40000

# The number of packets (of MTU size) that are available in
# the output buffer. The default is low to improve latency.
# Setting it higher will improve throughput.
#output-buffer = 10

# Routes to be forwarded to the client. If you need the
# client to forward routes to the server, you may use the
# config-per-user/group or even connect and disconnect scripts.
#
# To set the server as the default gateway for the client just
# comment out all routes from the server, or use the special keyword
# 'default'.

route = 10.10.10.0/255.255.255.0
route = 192.168.0.0/255.255.0.0
#route = fef4:db8:1000:1001::/64
#route = default

# Subsets of the routes above that will not be routed by
# the server. Note, that this may currently be not be supported
# by openconnect clients.

no-route = 192.168.5.0/255.255.255.0

# Note the that following two firewalling options currently are experimental and
# available in Linux systems with iptables software.

# If set, the script /usr/bin/ocserv-fw will be called to restrict
# the user to its allowed routes and prevent him from accessing
# any other routes. In case of defaultroute, the no-routes are restricted.
# All the routes applied by ocserv can be reverted using /usr/bin/ocserv-fw
# --removeall. This option can be set globally or in the per-user configuration.
#restrict-user-to-routes = true

# This option implies restrict-user-to-routes set to true. If set, the
# script /usr/bin/ocserv-fw will be called to restrict the user to
# access specific ports in the network. This option can be set globally
# or in the per-user configuration.
#restrict-user-to-ports = "tcp(443), tcp(80), udp(443), sctp(99), tcp(583), icmp(), icmpv6()"

# You could also use negation, i.e., block the user from accessing these ports only.
#restrict-user-to-ports = "!(tcp(443), tcp(80))"

# When set to true, all client's iroutes are made visible to all
# connecting clients except for the ones offering them. This option
# only makes sense if config-per-user is set.
#expose-iroutes = true

# When set to true, all global routes and no-routeswill be appended to individual
# user or group configuration (in case you use the config-per-user
# or config-per-group options. In previous versions of ocserv this
# was the default.
#append-global-routes = true

# Groups that a client is allowed to select from.
# A client may belong in multiple groups, and in certain use-cases
# it is needed to switch between them. For these cases the client can
# select prior to authentication. Add multiple entries for multiple groups.
# The group may be followed by a user-friendly name in brackets.
#select-group = group1
#select-group = group2[My special group]

# The name of the (virtual) group that if selected it would assign the user
# to its default group.
#default-select-group = DEFAULT

# Instead of specifying manually all the allowed groups, you may instruct
# ocserv to scan all available groups and include the full list.
#auto-select-group = true

# Configuration files that will be applied per user connection or
# per group. Each file name on these directories must match the username
# or the groupname.
# The options allowed in the configuration files are dns, nbns,
#  ipv?-network, ipv4-netmask, rx/tx-per-sec, iroute, route, no-route,
#  explicit-ipv4, explicit-ipv6, net-priority, deny-roaming, no-udp,
#  keepalive, dpd, mobile-dpd, max-same-clients, tunnel-all-dns,
#  restrict-user-to-routes, user-profile, cgroup, stats-report-time,
#  mtu, idle-timeout, mobile-idle-timeout, restrict-user-to-ports,
#  hostname, and session-timeout.
#
# Note that the 'iroute' option allows one to add routes on the server
# based on a user or group. The syntax depends on the input accepted
# by the commands route-add-cmd and route-del-cmd (see below). The no-udp
# is a boolean option (e.g., no-udp = true), and will prevent a UDP session
# for that specific user or group. The hostname option will set a
# hostname to override any proposed by the user. Note also, that, any
# routes, no-routes, DNS or NBNS servers present will overwrite the global ones.
#
# Also explicit addresses, are only allowed when they are odd. In that
# case the next even address will be used as the remote address (in PtP).

#config-per-user = /etc/ocserv/config-per-user/
#config-per-group = /etc/ocserv/config-per-group/

# When config-per-xxx is specified and there is no group or user that
# matches, then utilize the following configuration.
#default-user-config = /etc/ocserv/defaults/user.conf
#default-group-config = /etc/ocserv/defaults/group.conf

# The system command to use to setup a route. %{R} will be replaced with the
# route/mask, %{RI} with the route in CIDR format, and %{D} with the (tun) device.
#
# The following example is from linux systems. %{R} should be something
# like 192.168.2.0/255.255.255.0 and %{RI} 192.168.2.0/24 (the argument of iroute).

#route-add-cmd = "ip route add %{R} dev %{D}"
#route-del-cmd = "ip route delete %{R} dev %{D}"

# This option allows one to forward a proxy. The special keywords '%{U}'
# and '%{G}', if present will be replaced by the username and group name.
#proxy-url = http://example.com/
#proxy-url = http://example.com/%{U}/

# This option allows you to specify a URL location where a client can
# post using MS-KKDCP, and the message will be forwarded to the provided
# KDC server. That is a translation URL between HTTP and Kerberos.
# You can have the same path used for multiple realms. To authenticate
# in client side, in MIT kerberos you'll need to add in krb5.conf:
#   EXAMPLE.COM = {
#     kdc = https://ocserv.example.com/KdcProxy
#     http_anchors = FILE:/etc/ocserv-ca.pem
#   }
# In some distributions the krb5-k5tls plugin of kinit is required.
#
# The following option is available in ocserv, when compiled with GSSAPI support.

#kkdcp = "SERVER-PATH KERBEROS-REALM PROTOCOL@SERVER:PORT"
#kkdcp = "/KdcProxy KERBEROS.REALM udp@127.0.0.1:88"
#kkdcp = "/KdcProxy KERBEROS.REALM tcp@127.0.0.1:88"
#kkdcp = "/KdcProxy KERBEROS.REALM tcp@[::1]:88"

# Client profile xml. This can be used to advertise alternative servers
# to the client. A minimal file can be:
# <?xml version="1.0" encoding="UTF-8"?>
# <AnyConnectProfile xmlns="http://schemas.xmlsoap.org/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://schemas.xmlsoap.org/encoding/ AnyConnectProfile.xsd">
#	<ServerList>
#		<HostEntry>
#	            <HostName>VPN Server name</HostName>
#	            <HostAddress>localhost</HostAddress>
#		</HostEntry>
#	</ServerList>
# </AnyConnectProfile>
#
# Other fields may be used by some of the CISCO clients.
# This file must be accessible from inside the worker's chroot.
# Note that enabling this option is not recommended as it will allow
# the worker processes to open arbitrary files (when isolate-workers is
# set to true).
#user-profile = profile.xml

#
# The following options are for (experimental) AnyConnect client
# compatibility.

# This option will enable the pre-draft-DTLS version of DTLS, and
# will not require clients to present their certificate on every TLS
# connection. It must be set to true to support legacy CISCO clients
# and openconnect clients < 7.08. When set to true, it implies dtls-legacy = true.
cisco-client-compat = true

# This option allows one to disable the DTLS-PSK negotiation (enabled by default).
# The DTLS-PSK negotiation was introduced in ocserv 0.11.5 to deprecate
# the pre-draft-DTLS negotiation inherited from AnyConnect. It allows the
# DTLS channel to negotiate its ciphers and the DTLS protocol version.
#dtls-psk = false

# This option allows one to disable the legacy DTLS negotiation (enabled by default,
# but that may change in the future).
# The legacy DTLS uses a pre-draft version of the DTLS protocol and was
# from AnyConnect protocol. It has several limitations, that are addressed
# by the dtls-psk protocol supported by openconnect 7.08+.
dtls-legacy = true

#Advanced options

# Option to allow sending arbitrary custom headers to the client after
# authentication and prior to VPN tunnel establishment. You shouldn't
# need to use this option normally; if you do and you think that
# this may help others, please send your settings and reason to
# the openconnect mailing list. The special keywords '%{U}'
# and '%{G}', if present will be replaced by the username and group name.
#custom-header = "X-My-Header: hi there"

EXIT STATUS
One of the following exit values will be returned:

Successful program execution.

The operation failed or the command syntax was not valid.

libopts had an internal operational error.  Please report
    it to autogen-users@lists.sourceforge.net. Thank you.

COMPATIBILITY
The server has been tested to be compatible with the openconnect VPN client. However, it is also known to be compatible with certain CISCO AnyConnect clients. To enable compatibility with CISCO's AnyConnect the cisco-client-compat and user-profile options must be set in ocserv's configuration.

SEE ALSO
ocpasswd(8), occtl(8)

AUTHORS
Nikos Mavrogiannopoulos and others

COPYRIGHT
Copyright (C) 2013-2017 Nikos Mavrogiannopoulos all rights reserved. This program is released under the terms of the GNU General Public License, version 2.

BUGS
Please send bug reports to: openconnect-devel@lists.infradead.org

NOTES
This manual page was AutoGen-erated from the ocserv option definitions.