ocserv/src/ocserv-args.def

AutoGen Definitions options;
prog-name     = ocserv;
prog-title    = "OpenConnect 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";
    owner = "Nikos Mavrogiannopoulos";
    author = "Nikos Mavrogiannopoulos";
    eaddr  = "openconnect-devel@lists.infradead.org";
    type  = gplv2;
};

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

flag = {
    name      = tls-debug;
    descrip   = "Enable verbose TLS debugging information";
    doc      = "";
};

flag = {
    name      = http-debug;
    descrip   = "Enable verbose HTTP debugging information";
    doc      = "";
};

flag = {
    name      = debug;
    value     = d;
    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.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 plain option requires specifying a password file which contains
# entries of the following format.
# "username:groupname:encoded-password"
# One entry must be listed per line, and 'ocpasswd' can be used
# to generate password entries.
#auth = "plain[/etc/ocserv-passwd]"

# 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
dpd = 240

# 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)
#
# There may be multiple certificate and key pairs and 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 clients 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.
#crl = /path/to/crl.pem

# GnuTLS priority string
tls-priorities = "PERFORMANCE:%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 not allowed to reconnect after 
# a failed authentication attempt.
#min-reauth-time = 2

# Cookie validity time (in seconds)
# Once a client is authenticated he's provided a cookie with
# which he can reconnect. This option sets the maximum lifetime
# of that cookie.
cookie-validity = 172800

# Script to call when a client connects and obtains an IP
# 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). REASON
# may be "connect" or "disconnect".
#connect-script = /usr/bin/myscript
#disconnect-script = /usr/bin/myscript

# UTMP
use-utmp = true

# PID file
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 IPC, 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

#
# Network settings
#

# The name of the tun device
device = vpns

# 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 DNS advertized server
# Use the keywork local to advertize the local P-t-P address as DNS server
# ipv4-dns = local
ipv4-dns = 192.168.1.2

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

# The same, but for IPv6.
#ipv6-network = 
#ipv6-dns = 
#ipv6-nbns = 

# The IPv6 subnet prefix
#ipv6-prefix =

# 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.
ping-leases = false

# Unset to assign the default MTU of the device
# mtu = 

# 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 connect 
# and disconnect scripts.
route = 192.168.1.0/255.255.255.0
route = 192.168.5.0/255.255.255.0

# 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 ipv?-dns, ipv?-nbns,
#  ipv?-network, ipv?-netmask, ipv6-prefix, rx/tx-per-sec, iroute and route.
#
# 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).

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

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

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

# Client profile xml. A sample file exists in doc/profile.xml.
# This file must be accessible from inside the worker's chroot. 
# It is not used by the openconnect client.
#user-profile = /path/to/file.xml

# Binary files that may be downloaded by the CISCO client. Must
# be within any chroot environment.
#binary-files = /path/to/binaries

# Unless set to false it is required for clients to present their
# certificate even if they are authenticating via a previously granted
# cookie. Legacy CISCO clients do not do that, and thus this option
# should be set for them.
#always-require-cert = false


@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. 
_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. Once authenticated users can be disconnected by killing their worker process. 
The pid of that process is available from the command 'who -u' if utmp logging is enabled.

@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 Certificate authentication
In order to support certificate authentication you will need in addition to 
the server certificate and key for TLS, a certificate authority (CA) to sign
the client certificates. That authority should also provide a CRL to
allow the server to reject the revoked clients (see @var{ca-cert, crl}).

In certificate authentication each client holds a key and certificate that 
identifies him. The user ID of the client must be embedded in the certificate's Distinguished
Name (DN), e.g. 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 the client certificates
@example
$ certtool --generate-privkey --outfile user-key.pem
$ cat << _EOF_ >user.tmpl
cn = "user"
ou = "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 user-cert.pem >>revoked.pem
$ certtool --generate-crl --load-ca-privkey ca-key.pem \
	--load-ca-certificate ca.pem --load-certificate revoked.pem \
	--outfile crl.pem
@end example
After that you may want to notify ocserv of the new CRL by using
the HUP signal.

_EOT_;
};

doc-section = {
  ds-type = 'IMPLEMENTATION NOTES';
  ds-format = 'texi';
  ds-text   = <<-_EOT_
Note 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. 
To enable compatibility with CISCO's AnyConnect the client's policy must
set in a way that disables the downloader. An example policy file is shown below.
@example
<?xml version="1.0" encoding="UTF-8"?>
<AnyConnectPreferences>
<DefaultUser>my_user_name</DefaultUser>
<BypassDownloader>true</BypassDownloader>
<DefaultSecondUser></DefaultSecondUser>
<ClientCertificateThumbprint></ClientCertificateThumbprint>
<ServerCertificateThumbprint>2804076F5A73955FE7D92B656983EBA5BD48A276</ServerCertificateThumbprint>
<DefaultHost>my_server_name</DefaultHost>
<DefaultGroup></DefaultGroup>
<ProxyHost></ProxyHost>
<ProxyPort></ProxyPort>
<ControllablePreferences></ControllablePreferences>
</AnyConnectPreferences>
@end example
_EOT_;
};