ocserv/doc/ocserv.1

.TH ocserv 1 "16 Feb 2013" "0.0.1" "User Commands"
.\"
.\"  DO NOT EDIT THIS FILE   (ocserv-args.man)
.\"  
.\"  It has been AutoGen-ed  February 16, 2013 at 04:40:04 PM by AutoGen 5.16
.\"  From the definitions    ../src/ocserv-args.def.tmp
.\"  and the template file   agman-cmd.tpl
.\"
.SH NAME
ocserv \- OpenConnect server
.SH SYNOPSIS
.B ocserv
.\" Mixture of short (flag) options and long options
.RB [ \-\fIflag\fP " [\fIvalue\fP]]... [" \-\-\fIopt\-name\fP " [[=| ]\fIvalue\fP]]..."
.PP
All arguments must be options.
.PP
.SH "DESCRIPTION"
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 address.
Currently there is no tool to manipulate logged-in users. However,
they can be disconnected by killing their worker process. The pid of that
process can be seen with @var{who -u} if utmp logging is enabled.
.SH "OPTIONS"
.TP
.BR \-f ", " -\-foreground
Do not fork into background.
.sp
.TP
.BR \-\-tls\-debug
Enable verbose TLS debugging information.
.sp
.TP
.BR \-d ", " -\-debug
Enable verbose network debugging information.
.sp
.TP
.BR \-c " \fIfile\fP, " \-\-config "=" \fIfile\fP
Configuration file for the server.
.sp
.TP
.BR \-h , " \-\-help"
Display usage information and exit.
.TP
.BR \-! , " \-\-more-help"
Pass the extended usage information through a pager.
.TP
.BR \-v " [{\fIv|c|n\fP}]," " \-\-version" "[=\fI{v|c|n}\fP]"
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.
.SH AUTHENTICATION
.br
\fBPassword authentication\fP
.br
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.
.sp
.br
\fBCertificate authentication\fP
.br
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 \fBca\-cert, crl\fP).
.sp
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 \fBcert\-user\-oid\fP configuration option must be set.
.sp
The following examples demonstrate how to use certtool from GnuTLS to
generate such CA.
.sp
.br
\fBGenerating the CA\fP
.br
.br
.in +4
.nf
$ 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
.in -4
.fi
.sp
.br
\fBGenerating the client certificates\fP
.br
.br
.in +4
.nf
$ 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
.sp
.in -4
.fi
.sp
.br
\fBRevoking a client certificate\fP
.br
To revoke the previous client certificate use:
.br
.in +4
.nf
$ 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
.in -4
.fi
After that you may want to notify ocserv of the new CRL by using
the HUP signal.
.sp
.SH "IMPLEMENTATION NOTES"
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.
.SH FILES
.br
\fBocserv's configuration file format\fP
.br
By default, if no other file is specified, ocserv looks for its configuration file at \fI/etc/ocserv.conf\fP.
An example configuration file follows.
.sp
.br
.in +4
.nf
.sp
# User authentication method. Could be set multiple times and in that case
# all should succeed.
# Options: certificate, pam. 
#auth = "certificate"
auth = "pam"
.sp
# Use listen\-host to limit to specific IPs or to the IPs of a provided hostname.
#listen\-host = [IP|HOSTNAME]
.sp
# Limit the number of clients. Unset or set to zero for unlimited.
#max\-clients = 1024
max\-clients = 16
.sp
# Limit the number of identical clients (i.e., users connecting multiple times)
# Unset or set to zero for unlimited.
max\-same\-clients = 1
.sp
# TCP and UDP port number
tcp\-port = 3333
udp\-port = 3333
.sp
# Keepalive in seconds
keepalive = 32400
.sp
# Dead peer detection in seconds
dpd = 240
.sp
# The key and the certificates of the server
# The key may be a file, or any URL supported by GnuTLS (i.e., tpmkey or pkcs11)
server\-cert = /path/to/cert.pem
server\-key = /path/to/key.pem
.sp
# The Certificate Authority that will be used
# to verify clients if certificate authentication
# is set.
#ca\-cert = /path/to/ca.pem
.sp
# 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
.sp
# 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
.sp
# A revocation list of ca\-cert is set
#crl = /path/to/crl.pem
.sp
# GnuTLS priority string
tls\-priorities = "PERFORMANCE:%SERVER_PRECEDENCE"
.sp
# The default server directory
#chroot\-dir = /path/to/chroot
.sp
# The time (in seconds) that a client is allowed to stay connected prior
# to authentication
auth\-timeout = 40
.sp
# 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
.sp
# A cookie database. If not set cookies are stored in memory and
# server restarts won't preserve them.
#cookie\-db = /var/tmp/cookies.db
.sp
# 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 connect), IP_REMOTE (the VPN IP of the client).
#connect\-script = /usr/bin/myscript
#disconnect\-script = /usr/bin/myscript
.sp
# UTMP
use\-utmp = true
.sp
# PID file
pid\-file = /var/run/ocserv.pid
.sp
run\-as\-user = nobody
run\-as\-group = nogroup
.sp
# Network settings
.sp
device = vpns
.sp
ipv4\-network = 192.168.1.0
ipv4\-netmask = 255.255.255.0
# Use the keywork local to advertize the local P\-t\-P address as DNS server
# ipv4\-dns = 192.168.2.1
ipv4\-dns = local
.sp
#ipv6\-address = 
#ipv6\-mask = 
#ipv6\-dns = 
.sp
# Leave empty to assign the default MTU of the device
# mtu = 
.sp
route = 192.168.1.0/255.255.255.0
route = 192.168.5.0/255.255.255.0
.sp
.in -4
.fi
.sp
.SH "EXIT STATUS"
One of the following exit values will be returned:
.TP
.BR 0 " (EXIT_SUCCESS)"
Successful program execution.
.TP
.BR 1 " (EXIT_FAILURE)"
The operation failed or the command syntax was not valid.
.SH COMPATIBILITY
.br
\fBFeatures of the server\fP
.br
.in +4
.ti -4
\fB*\fP
Supports both TCP and UDP VPN tunnels using TLS and Datagram TLS.
.ti -4
\fB*\fP
Support for the server key being stored in TPM, hardware security modules (HSM), or even a smart card. They can be specified as files using the tpmkey or pkcs11 URLs.
.ti -4
\fB*\fP
Authentication using PAM or certificates.
.ti -4
\fB*\fP
Each client is isolated from the others on a separate process with a separate tun device. This allows routing using the system facilies, allows having separate settings per user or group (e.g. bandwidth limits).
.ti -4
\fB*\fP
Privilege separation between the main process which performs TUN allocation and authentication, with the worker processes which handles messages from the client.
.ti -4
\fB*\fP
Registers VPN leases to UTMP and WTMP files.
.ti -4
\fB*\fP
Persistent storage of cookies, to allow a seamless server restart.
.in -4
.SH "AUTHORS"
Nikos Mavrogiannopoulos
.SH "COPYRIGHT"
Copyright (C) 2013 Nikos Mavrogiannopoulos all rights reserved.
This program is released under the terms of the GNU General Public License, version 2.
.SH "BUGS"
Please send bug reports to: openconnect-devel@lists.infradead.org
.SH "NOTES"
This manual page was \fIAutoGen\fP-erated from the \fBocserv\fP
option definitions.