ocserv/src/ocserv-args.def

AutoGen Definitions options;
prog-name     = ocserv;
prog-title    = "OpenConnect VPN server";
prog-desc     = "OpenConnect VPN server.";
disable-save;
no-xlate = opt;
gnu-usage;
config-header = config.h;
long-opts;
no-misuse-usage;
short-usage   = "Usage: ocserv [options] -c [config]\nocserv --help for usage instructions.\n";
explain       = "";
#include version.inc

detail  = "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.
";

copyright = {
    date  = "2013, 2014";
    owner = "Nikos Mavrogiannopoulos";
    author = "Nikos Mavrogiannopoulos and others";
    eaddr  = "openconnect-devel@lists.infradead.org";
    type  = gpl;
};

flag = {
    name      = foreground;
    value     = f;
    descrip   = "Do not fork into background";
    doc      = "";
};

flag = {
    name      = debug;
    value     = d;
    arg-type  = number;
    arg-range = "0 -> 9999";
    descrip   = "Enable verbose network debugging information";
    doc      = "";
};

flag = {
    name      = config;
    value     = c;
    arg-type  = file;
    file-exists = yes;
    descrip   = "Configuration file for the server";
    doc   = "";
};

flag = {
    name      = pid-file;
    value     = p;
    arg-type  = file;
    descrip   = "Specify pid file for the server";
    doc   = "";
};

help-value    = h;


doc-section = {
  ds-type = 'FILES';
  ds-format = 'texi';
  ds-text   = <<-_EOT_
@subheading ocserv's configuration file format
By default, if no other file is specified, ocserv looks for its configuration file at @file{/etc/ocserv/ocserv.conf}.
An example configuration file follows.

@example

# 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. 
#auth = "certificate"
#auth = "pam"

# The gid-min option is used by auto-select-group option, in order to
# select the minimum group ID.
#auth = "pam[gid-min=1000]"

# 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' can be used
# to generate password entries.
#auth = "plain[/etc/ocserv/ocpasswd]"

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

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

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

# 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

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

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

# 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. The needs to
# be much 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-DeviceType'.
mobile-dpd = 1800

# MTU discovery (DPD must be enabled)
try-mtu-discovery = false

# 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

# 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

# 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

# In case PKCS #11 or TPM 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 Certificate Authority that will be used to verify
# client certificates (public keys) if certificate authentication
# is set.
#ca-cert = /path/to/ca.pem

# 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
#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. Useful OIDs are: 
#  OU (organizational unit) = 2.5.4.11 
#cert-group-oid = 2.5.4.11

# The revocation list of the certificates issued by the 'ca-cert' above.
# See the manual to generate an empty CRL initially.
#crl = /path/to/crl.pem

# GnuTLS priority string
tls-priorities = "NORMAL:%SERVER_PRECEDENCE:%COMPAT"

# To enforce perfect forward secrecy (PFS) on the main channel.
#tls-priorities = "NORMAL:%SERVER_PRECEDENCE:%COMPAT:-RSA"

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

# 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 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 = 2

# Cookie timeout (in seconds)
# Once a client is authenticated he's provided a cookie with
# which he can reconnect. That cookie will be invalided if not
# used within this timeout value. On a user disconnection, that
# cookie will also be active for this time amount prior to be
# invalid. That allows a reasonable amount of time for roaming between
# networks.
cookie-timeout = 300

# 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.
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, HOSTNAME (the hostname selected by client), 
# DEVICE, IP_REAL (the real IP of the client), 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_REMOVE (the IPv6 remote address), and
# ID (a unique numeric ID); REASON may be "connect" or "disconnect".

# The disconnect script will received 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

# 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

# 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

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

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

# socket file used for server IPC (worker-main), will be appended with .PID
# It must be accessible within the chroot environment (if any)
socket-file = /var/run/ocserv-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

# 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.
ipv4-network = 192.168.1.0
ipv4-netmask = 255.255.255.0

# 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 IPv6 subnet that leases will be given from.
#ipv6-network = fc00::
#ipv6-prefix = 16

# 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 enforce an MTU value to the incoming
# connections. Unset to use the default MTU of the TUN device.
#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 = 192.168.1.0/255.255.255.0
route = 192.168.5.0/255.255.255.0
#route = fef4:db8:1000:1001::/64

# 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 group that if selected it would allow to use
# the assigned by 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, ipv6-prefix, rx/tx-per-sec, iroute, route,
#  net-priority, deny-roaming, no-udp and cgroup.
#
# Note that the 'iroute' option allows 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.

#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 and %{D} with the (tun) device.
#
# The following example is from linux systems. %R should be something
# like 192.168.2.0/24

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

# This option allows 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}/

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

# This option must be set to true to support legacy CISCO clients.
# A side effect of this option is that it will no longer be required 
# for clients to present their certificate on every connection.
# That is they may resume a cookie without presenting a certificate
# (when certificate authentication is used).
#cisco-client-compat = true

# Client profile xml. A sample file exists in doc/profile.xml.
# It is required by some of the CISCO clients.
# This file must be accessible from inside the worker's chroot. 
#user-profile = /path/to/file.xml

# Binary files that may be downloaded by the CISCO client. Must
# be within any chroot environment. Normally you don't need
# to use this option.
#binary-files = /path/to/binaries

#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"

@end example

_EOT_;
};

doc-section = {
  ds-type = 'SYNOPSIS';
  ds-format = 'texi';
  ds-text   = <<-_EOT_
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.
_EOT_;
};

doc-section = {
  ds-type = 'DESCRIPTION';
  ds-format = 'texi';
  ds-text   = <<-_EOT_
This a standalone server that reads a configuration file (see below for more details),
and waits for client connections.

The server maintains two connections/channels with the client. The main VPN 
channel is established over TCP 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.
_EOT_;
};

doc-section = {
  ds-type = 'AUTHENTICATION';
  ds-format = 'texi';
  ds-text   = <<-_EOT_
Users can be authenticated in multiple ways, which are explained in the following
paragraphs. Connected users can be managed using the 'occtl' tool.

@subheading 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.

@subheading 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 @var{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 @var{cert-user-oid} configuration option 
must be set.

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

@subheading Generating the CA
@example
$ certtool --generate-privkey --outfile ca-key.pem
$ cat << _EOF_ >ca.tmpl
cn = "VPN CA"
organization = "Big Corp"
serial = 1
expiration_days = 9999
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
@end example

@subheading 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.
@example
$ certtool --generate-privkey --outfile server-key.pem
$ cat << _EOF_ >server.tmpl
cn = "www.example.com"
organization = "MyCompany"
serial = 2
expiration_days = 9999
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

@end example

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.

@subheading Generating an external CA-signed server certificate
@example
$ certtool --generate-privkey --outfile server-key.pem
$ cat << _EOF_ >server.tmpl
cn = "www.example.com"
organization = "MyCompany"
serial = 2
expiration_days = 9999
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

@end example

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

@subheading 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.
@example
$ certtool --generate-privkey --outfile user-key.pem
$ cat << _EOF_ >user.tmpl
cn = "user"
unit = "admins"
serial = 1824
expiration_days = 9999
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

@end example

@subheading Revoking a client certificate
To revoke the previous client certificate use:
@example
$ cat << _EOF_ >crl.tmpl
crl_next_update = 999
crl_number = 1
_EOF_
$ cat user-cert.pem >>revoked.pem
$ certtool --generate-crl --load-ca-privkey ca-key.pem \
	--load-ca-certificate ca.pem --load-certificate revoked.pem \
	--template crl.tmpl --outfile crl.pem
@end example
After that you may want to notify ocserv of the new CRL by using
the HUP signal.

When there are no revoked certificates an empty revocation list
should be generated as follows.
@example
$ certtool --generate-crl --load-ca-privkey ca-key.pem \
	--load-ca-certificate ca.pem \
	--template crl.tmpl --outfile crl.pem
@end example
_EOT_;
};

doc-section = {
  ds-type = 'IMPLEMENTATION NOTES';
  ds-format = 'texi';
  ds-text   = <<-_EOT_
The support for PAM is limited to authentication only. That is, PAM is
used for authentication but not for session control.

Note also, that while this server utilizes privilege separation and password
authentication occurs on the main server, this does not apply for TLS client 
certificate authentication. That is because the worker has no way to 
prove to the main server that it performed the certificate verification.
_EOT_;
};

doc-section = {
  ds-type = 'COMPATIBILITY';
  ds-format = 'texi';
  ds-text   = <<-_EOT_
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.
_EOT_;
};

doc-section = {
  ds-type   = 'SEE ALSO';
  ds-format = 'man';
  ds-text   = <<-_EOText_
ocpasswd(8), occtl(8)
_EOText_;
};