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.def

detail  = "This program is openconnect VPN server (ocserv), a server compatible with the
openconnect VPN client. It is believed to be compatible with the protocol
used by CISCO's AnyConnect SSL VPN.

Multiple authentication methods are available including PAM and certificate
authentication.
Authenticated users are assigned an unprivileged worker process and obtain 
a networking (tun) device and IP from a configurable pool of addresses.";



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      = 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   = "";
};

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

# 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)
server-cert = /path/to/cert.pem
server-key = /path/to/key.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"

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

# A cookie database. If not set cookies are stored in memory and
# server restarts won't preserve them.
#cookie-db = /var/tmp/cookies.db

# Script to call when a client connects and obtains an IP
# Parameters are passed on the environment.
# 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).
#connect-script = /usr/bin/myscript
#disconnect-script = /usr/bin/myscript

# UTMP
use-utmp = true

# PID file
pid-file = /var/run/ocserv.pid

# The user the worker processes will be run as.
run-as-user = nobody
run-as-group = nogroup

#
# Network settings
#

# The name of the tun device
device = vpns

# 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 = 192.168.2.1
ipv4-dns = local

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

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

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

# 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

#
# The following options are for (experimental) AnyConnect client 
# compatibility. They are only available if the server is built 
# with --enable-anyconnect
#

# 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

# 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 = '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.
It 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
certificates for the clients. That authority should also provide a CRL to
allow the server to reject the revoked clients (see @var{ca-cert, crl}).

Each client will then hold 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
email = "user@example.com"
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 for password
authentication, this does not apply for TLS and client certificate authentication.
This has the advantage of spreading TLS calculations to multiple workers (i.e. cores)
if available, but at the cost of each worker having a copy of the server's 
private key.
_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.
_EOT_;
};