1OCSERV(8)                                                            OCSERV(8)
2
3
4

NAME

6       ocserv - OpenConnect VPN server
7

SYNOPSIS

9       ocserv options -c [config]
10
11       Openconnect  VPN  server  (ocserv)  is a VPN server compatible with the
12       openconnect VPN client. It follows the AnyConnect VPN protocol which is
13       used by several CISCO routers.
14

DESCRIPTION

16       This a standalone server that reads a configuration file (see below for
17       more details), and waits for client connections. Log messages are redi‐
18       rected to daemon facility.
19
20       The server maintains two connections/channels with the client. The main
21       VPN channel is established over TCP, HTTP and TLS. This is the  control
22       channel  as  well as the backup data channel. After its establishment a
23       UDP channel using DTLS is initiated which serves as the main data chan‐
24       nel.  If  the UDP channel fails to establish or is temporarily unavail‐
25       able the backup channel over TCP/TLS is being used.
26
27       This server supports multiple authentication methods, including PAM and
28       certificate authentication. Authenticated users are assigned an unpriv‐
29       ileged worker process and obtain a networking (tun) device  and  an  IP
30       from a configurable pool of addresses.
31
32       Once  authenticated,  the server provides the client with an IP address
33       and a list of routes that it may access. In order to  allow  high-speed
34       transfers the server does not process or filter packets. It is expected
35       that the server has or will set up  any  required  routes  or  firewall
36       rules.
37
38       It  is possible to separate users into groups, which are either present
39       on their certificate, or presented on login for  the  user  to  choose.
40       That  way  a user may take advantage of the different settings that may
41       apply per group. See the comments on the configuration  file  for  more
42       information.
43
44       It  is  also possible to run hostname-based virtual servers which could
45       support different authentication methods. When multiple virtual servers
46       are  present  clients  are  distinguished by the advertised server name
47       over TLS (SNI). Clients which do not support or sent SNI, are  directed
48       to the default server.
49

OPTIONS

51       -f, --foreground:
52              Do not fork server into background.
53
54       -d, --debug=num:
55              Enable  verbose  network  debugging  information.  num  must  be
56              between zero and 9999.
57
58       -c, --config=FILE:
59              Specify the configuration file for the server.
60
61       -t, --test-config:
62              Test the provided configuration file and exit. A successful exit
63              error code indicates a valid configuration.
64
65       -p, --pid-file=FILE:
66              Specify a PID file for the server.
67
68       -h, --help:
69              Display usage information and exit.
70
71       -v, --version:
72              Output version of program and exit.
73

AUTHENTICATION

75       Users can be authenticated in multiple ways, which are explained in the
76       following paragraphs. Connected users can be managed  using  the  occtl
77       tool.
78
79   Password authentication
80       If  your  system  supports Pluggable Authentication Modules (PAM), then
81       ocserv will take advantage of it to password  authenticate  its  users.
82       Otherwise  a  plain  password file similar to the UNIX password file is
83       also supported. In that case the ´ocpasswd´ tool can be  used  for  its
84       management.  Note  that password authentication can be used in conjunc‐
85       tion with certificate authentication.
86
87   GSSAPI authentication
88       ocserv  will  take  advantage  of  the  MIT  Kerberos  project   GSSAPI
89       libraries,  and  allow authentication using any method GSSAPI supports.
90       That is, mainly, Kerberos authentication. That is often more useful  to
91       be combined with PAM or other password authentication methods so that a
92       fallback mechanism can be used when GSSAPI fails (e.g., when  the  user
93       doesn´t  already  have a Kerberos ticket). The GSSAPI authentication is
94       implemented using SPNEGO over HTTP (RFC4559).
95
96   Public key (certificate) authentication
97       Public key authentication allows the user to be  authenticated  by  the
98       possession of the private key that corresponds to a known to the server
99       public key. That allows the  usage  of  common  smart  cards  for  user
100       authentication.
101
102       In ocserv, a certificate authority (CA) is used to sign the client cer‐
103       tificates. That certificate authority can be local, used  only  by  the
104       server  to  sign  its  user´s known public keys which are then given to
105       users in a form of certificates. That authority need also provide a CRL
106       to allow the server to reject the revoked clients (see ca-cert, crl).
107
108       In  certificate  authentication  each client presents a certificate and
109       signs data provided by the server, as part of  TLS  authentication,  to
110       prove  his possession of the corresponding private key. The certificate
111       need also contain user identifying information, for example,  the  user
112       ID  of  the  client must be embedded in the certificate´s Distinguished
113       Name (DN), i.e., in the Common Name, or UID fields. For the  server  to
114       read the name, the cert-user-oid configuration option must be set.
115
116       The  following  examples demonstrate how to use certtool from GnuTLS to
117       generate such CA.
118
119   Generating the CA
120       $ certtool --generate-privkey --outfile ca-key.pem
121       $ cat << _EOF_ >ca.tmpl
122       cn = "VPN CA"
123       organization = "Big Corp"
124       serial = 1
125       expiration_days = -1
126       ca
127       signing_key
128       cert_signing_key
129       crl_signing_key
130       _EOF_
131
132       $ certtool --generate-self-signed --load-privkey ca-key.pem \
133                  --template ca.tmpl --outfile ca-cert.pem
134
135   Generating a local server certificate
136       The following example generates the server key  and  certificate  pair.
137       The  key  generated  is  an RSA one, but different types can be used by
138       specifying the ´ecdsa´ or ´dsa´ options to certtool.
139
140
141
142           $ certtool --generate-privkey --outfile server-key.pem
143           $ cat << _EOF_ >server.tmpl
144           cn = "VPN server"
145           dns_name = "www.example.com"
146           dns_name = "vpn1.example.com"
147           #ip_address = "1.2.3.4"
148           organization = "MyCompany"
149           expiration_days = -1
150           signing_key
151           encryption_key #only if the generated key is an RSA one
152           tls_www_server
153           _EOF_
154
155           $ certtool --generate-certificate --load-privkey server-key.pem \
156                      --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem \
157                      --template server.tmpl --outfile server-cert.pem
158
159
160
161       From this point the clients need ca-cert.pem to  be  able  to  securely
162       connect to the server.
163
164       Note  that  it  is  a better practice to use two separate RSA keys, one
165       with the signing_key option and another with the encryption_key.
166
167   Generating an external CA-signed server certificate
168       $ certtool --generate-privkey --outfile server-key.pem
169       $ cat << _EOF_ >server.tmpl
170       cn = "My server"
171       dns_name = "www.example.com"
172       organization = "MyCompany"
173       expiration_days = -1
174       signing_key
175       encryption_key #only if the generated key is an RSA one
176       tls_www_server
177       _EOF_
178       $ certtool --generate-request --load-privkey server-key.pem \
179                  --template server.tmpl --outfile server-cert.csr
180
181       At this point you need to provide the server-cert.csr to your  CA,  and
182       they will send you the server certificate.
183
184   Generating the client certificates
185       Note  that it is recommended to leave detailed personal information out
186       of the certificate as it is sent in clear  during  TLS  authentication.
187       The  following  process generates a certificate and converts it to PKCS
188       #12 that is protected by a PIN and most clients are able to import (the
189       3DES  cipher is used in the example because it is supported by far more
190       devices than AES).
191
192
193
194           $ certtool --generate-privkey --outfile user-key.pem
195           $ cat << _EOF_ >user.tmpl
196           cn = "user"
197           unit = "admins"
198           expiration_days = 365
199           signing_key
200           tls_www_client
201           _EOF_
202           $ certtool --generate-certificate --load-privkey user-key.pem \
203                      --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem \
204                      --template user.tmpl --outfile user-cert.pem
205
206           $ certtool --to-p12 --load-privkey user-key.pem \
207                      --pkcs-cipher 3des-pkcs12 \
208                      --load-certificate user-cert.pem \
209                      --outfile user.p12 --outder
210
211
212
213   Revoking a client certificate
214       To revoke the previous client certificate, i.e.,  preventing  the  user
215       from  accessing  the VPN resources prior to its certificate expiration,
216       use:
217
218
219
220           $ cat << _EOF_ >crl.tmpl
221           crl_next_update = 365
222           crl_number = 1
223           _EOF_
224           $ cat user-cert.pem >>revoked.pem
225           $ certtool --generate-crl --load-ca-privkey ca-key.pem \
226                      --load-ca-certificate ca-cert.pem --load-certificate revoked.pem \
227                      --template crl.tmpl --outfile crl.pem
228
229
230
231       After that you may want to notify ocserv of the new CRL  by  using  the
232       HUP signal, or wait for it to reload it.
233
234       When  there are no revoked certificates an empty revocation list should
235       be generated as follows.
236
237
238
239           $ certtool --generate-crl --load-ca-privkey ca-key.pem \
240                      --load-ca-certificate ca-cert.pem \
241                      --template crl.tmpl --outfile crl.pem
242
243
244

IMPLEMENTATION NOTES

246       Note that while this  server  utilizes  privilege  separation  and  all
247       authentication  occurs  on the security module, this does not apply for
248       TLS client certificate authentication. That is due to TLS protocol lim‐
249       itation.
250

NETWORKING CONSIDERATIONS

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

FILES

258   ocserv´s configuration file format
259       By default, if no other file is specified, ocserv looks for its config‐
260       uration  file at /etc/ocserv/ocserv.conf. An example configuration file
261       follows.
262
263
264
265           ### The following directives do not change with server reload.
266
267           # User authentication method. To require multiple methods to be
268           # used for the user to login, add multiple auth directives. The values
269           # in the ´auth´ directive are AND composed (if multiple all must
270           # succeed).
271           # Available options: certificate, plain, pam, radius, gssapi.
272           # Note that authentication methods utilizing passwords cannot be
273           # combined (e.g., the plain, pam or radius methods).
274
275           # certificate:
276           #  This indicates that all connecting users must present a certificate.
277           #  The username and user group will be then extracted from it (see
278           #  cert-user-oid and cert-group-oid). The certificate to be accepted
279           #  it must be signed by the CA certificate as specified in ´ca-cert´ and
280           #  it must not be listed in the CRL, as specified by the ´crl´ option.
281           #
282           # pam[gid-min=1000]:
283           #  This enabled PAM authentication of the user. The gid-min option is used
284           # by auto-select-group option, in order to select the minimum valid group ID.
285           #
286           # plain[passwd=/etc/ocserv/ocpasswd,otp=/etc/ocserv/users.otp]
287           #  The plain option requires specifying a password file which contains
288           # entries of the following format.
289           # "username:groupname1,groupname2:encoded-password"
290           # One entry must be listed per line, and ´ocpasswd´ should be used
291           # to generate password entries. The ´otp´ suboption allows one to specify
292           # an oath password file to be used for one time passwords; the format of
293           # the file is described in https://github.com/archiecobbs/mod-authn-otp/wiki/UsersFile
294           #
295           # radius[config=/etc/radiusclient/radiusclient.conf,groupconfig=true,nas-identifier=name]:
296           #  The radius option requires specifying freeradius-client configuration
297           # file. If the groupconfig option is set, then config-per-user/group will be overridden,
298           # and all configuration will be read from radius. That also includes the
299           # Acct-Interim-Interval, and Session-Timeout values.
300           #
301           # See doc/README-radius.md for the supported radius configuration atributes.
302           #
303           # gssapi[keytab=/etc/key.tab,require-local-user-map=true,tgt-freshness-time=900]
304           #  The gssapi option allows one to use authentication methods supported by GSSAPI,
305           # such as Kerberos tickets with ocserv. It should be best used as an alternative
306           # to PAM (i.e., have pam in auth and gssapi in enable-auth), to allow users with
307           # tickets and without tickets to login. The default value for require-local-user-map
308           # is true. The ´tgt-freshness-time´ if set, it would require the TGT tickets presented
309           # to have been issued within the provided number of seconds. That option is used to
310           # restrict logins even if the KDC provides long time TGT tickets.
311
312           #auth = "pam"
313           #auth = "pam[gid-min=1000]"
314           #auth = "plain[passwd=./sample.passwd,otp=./sample.otp]"
315           auth = "plain[passwd=./sample.passwd]"
316           #auth = "certificate"
317           #auth = "radius[config=/etc/radiusclient/radiusclient.conf,groupconfig=true]"
318
319           # Specify alternative authentication methods that are sufficient
320           # for authentication. That is, if set, any of the methods enabled
321           # will be sufficient to login, irrespective of the main ´auth´ entries.
322           # When multiple options are present, they are OR composed (any of them
323           # succeeding allows login).
324           #enable-auth = "certificate"
325           #enable-auth = "gssapi"
326           #enable-auth = "gssapi[keytab=/etc/key.tab,require-local-user-map=true,tgt-freshness-time=900]"
327
328           # Accounting methods available:
329           # radius: can be combined with any authentication method, it provides
330           #      radius accounting to available users (see also stats-report-time).
331           #
332           # pam: can be combined with any authentication method, it provides
333           #      a validation of the connecting user´s name using PAM. It is
334           #      superfluous to use this method when authentication is already
335           #      PAM.
336           #
337           # Only one accounting method can be specified.
338           #acct = "radius[config=/etc/radiusclient/radiusclient.conf]"
339
340           # Use listen-host to limit to specific IPs or to the IPs of a provided
341           # hostname.
342           #listen-host = [IP|HOSTNAME]
343
344           # When the server has a dynamic DNS address (that may change),
345           # should set that to true to ask the client to resolve again on
346           # reconnects.
347           #listen-host-is-dyndns = true
348
349           # TCP and UDP port number
350           tcp-port = 443
351           udp-port = 443
352
353           # Accept connections using a socket file. It accepts HTTP
354           # connections (i.e., without SSL/TLS unlike its TCP counterpart),
355           # and uses it as the primary channel. That option is experimental
356           # and it has many known issues.
357           #  * It can only be combined with certificate authentication, when receiving
358           #    channel information through proxy protocol (see listen-proxy-proto)
359           #  * It cannot derive any keys needed for the DTLS session (hence no support for dtls-psk)
360           #  * It cannot enforce the framing of the SSL/TLS packets, and that
361           #    breaks assumptions held by several openconnect clients.
362           # This option is not recommended for use, and may be removed
363           # in the future.
364           #
365           #listen-clear-file = /var/run/ocserv-conn.socket
366
367           # The user the worker processes will be run as. It should be
368           # unique (no other services run as this user).
369           run-as-user = nobody
370           run-as-group = daemon
371
372           # socket file used for IPC with occtl. You only need to set that,
373           # if you use more than a single servers.
374           #occtl-socket-file = /var/run/occtl.socket
375
376           # socket file used for server IPC (worker-main), will be appended with .PID
377           # It must be accessible within the chroot environment (if any), so it is best
378           # specified relatively to the chroot directory.
379           socket-file = /var/run/ocserv-socket
380
381           # The default server directory. Does not require any devices present.
382           #chroot-dir = /var/lib/ocserv
383
384           # The key and the certificates of the server
385           # The key may be a file, or any URL supported by GnuTLS (e.g.,
386           # tpmkey:uuid=xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx;storage=user
387           # or pkcs11:object=my-vpn-key;object-type=private)
388           #
389           # The server-cert file may contain a single certificate, or
390           # a sorted certificate chain.
391           # There may be multiple server-cert and server-key directives,
392           # but each key should correspond to the preceding certificate.
393           # The certificate files will be reloaded when changed allowing for in-place
394           # certificate renewal (they are checked and reloaded periodically;
395           # a SIGHUP signal to main server will force reload).
396
397           #server-cert = /etc/ocserv/server-cert.pem
398           #server-key = /etc/ocserv/server-key.pem
399           server-cert = ../tests/certs/server-cert.pem
400           server-key = ../tests/certs/server-key.pem
401
402           # Diffie-Hellman parameters. Only needed if for old (pre 3.6.0
403           # versions of GnuTLS for supporting DHE ciphersuites.
404           # Can be generated using:
405           # certtool --generate-dh-params --outfile /etc/ocserv/dh.pem
406           #dh-params = /etc/ocserv/dh.pem
407
408           # In case PKCS #11, TPM or encrypted keys are used the PINs should be available
409           # in files. The srk-pin-file is applicable to TPM keys only, and is the
410           # storage root key.
411           #pin-file = /etc/ocserv/pin.txt
412           #srk-pin-file = /etc/ocserv/srkpin.txt
413
414           # The password or PIN needed to unlock the key in server-key file.
415           # Only needed if the file is encrypted or a PKCS #11 object. This
416           # is an alternative method to pin-file.
417           #key-pin = 1234
418
419           # The SRK PIN for TPM.
420           # This is an alternative method to srk-pin-file.
421           #srk-pin = 1234
422
423           # The Certificate Authority that will be used to verify
424           # client certificates (public keys) if certificate authentication
425           # is set.
426           #ca-cert = /etc/ocserv/ca.pem
427           ca-cert = ../tests/certs/ca.pem
428
429
430           ### All configuration options below this line are reloaded on a SIGHUP.
431           ### The options above, will remain unchanged. Note however, that the
432           ### server-cert, server-key, dh-params and ca-cert options will be reloaded
433           ### if the provided file changes, on server reload. That allows certificate
434           ### rotation, but requires the server key to remain the same for seamless
435           ### operation. If the server key changes on reload, there may be connection
436           ### failures during the reloading time.
437
438
439           # Whether to enable seccomp/Linux namespaces worker isolation. That restricts the number of
440           # system calls allowed to a worker process, in order to reduce damage from a
441           # bug in the worker process. It is available on Linux systems at a performance cost.
442           # The performance cost is roughly 2% overhead at transfer time (tested on a Linux 3.17.8).
443           # Note however, that process isolation is restricted to the specific libc versions
444           # the isolation was tested at. If you get random failures on worker processes, try
445           # disabling that option and report the failures you, along with system and debugging
446           # information at: https://gitlab.com/ocserv/ocserv/issues
447           isolate-workers = true
448
449           # A banner to be displayed on clients
450           #banner = "Welcome"
451
452           # Limit the number of clients. Unset or set to zero for unlimited.
453           #max-clients = 1024
454           max-clients = 16
455
456           # Limit the number of identical clients (i.e., users connecting
457           # multiple times). Unset or set to zero for unlimited.
458           max-same-clients = 2
459
460           # When the server receives connections from a proxy, like haproxy
461           # which supports the proxy protocol, set this to obtain the correct
462           # client addresses. The proxy protocol would then be expected in
463           # the TCP or UNIX socket (not the UDP one). Although both v1
464           # and v2 versions of proxy protocol are supported, the v2 version
465           # is recommended as it is more efficient in parsing.
466           #listen-proxy-proto = true
467
468           # Limit the number of client connections to one every X milliseconds
469           # (X is the provided value). Set to zero for no limit.
470           #rate-limit-ms = 100
471
472           # Stats report time. The number of seconds after which each
473           # worker process will report its usage statistics (number of
474           # bytes transferred etc). This is useful when accounting like
475           # radius is in use.
476           #stats-report-time = 360
477
478           # Stats reset time. The period of time statistics kept by main/sec-mod
479           # processes will be reset. These are the statistics shown by cmd
480           # ´occtl show stats´. For daily: 86400, weekly: 604800
481           # This is unrelated to stats-report-time.
482           server-stats-reset-time = 604800
483
484           # Keepalive in seconds
485           keepalive = 32400
486
487           # Dead peer detection in seconds.
488           # Note that when the client is behind a NAT this value
489           # needs to be short enough to prevent the NAT disassociating
490           # his UDP session from the port number. Otherwise the client
491           # could have his UDP connection stalled, for several minutes.
492           dpd = 90
493
494           # Dead peer detection for mobile clients. That needs to
495           # be higher to prevent such clients being awaken too
496           # often by the DPD messages, and save battery.
497           # The mobile clients are distinguished from the header
498           # ´X-AnyConnect-Identifier-Platform´.
499           mobile-dpd = 1800
500
501           # If using DTLS, and no UDP traffic is received for this
502           # many seconds, attempt to send future traffic over the TCP
503           # connection instead, in an attempt to wake up the client
504           # in the case that there is a NAT and the UDP translation
505           # was deleted. If this is unset, do not attempt to use this
506           # recovery mechanism.
507           switch-to-tcp-timeout = 25
508
509           # MTU discovery (DPD must be enabled)
510           try-mtu-discovery = false
511
512           # If you have a certificate from a CA that provides an OCSP
513           # service you may provide a fresh OCSP status response within
514           # the TLS handshake. That will prevent the client from connecting
515           # independently on the OCSP server.
516           # You can update this response periodically using:
517           # ocsptool --ask --load-cert=your_cert --load-issuer=your_ca --outfile response
518           # Make sure that you replace the following file in an atomic way.
519           #ocsp-response = /etc/ocserv/ocsp.der
520
521           # The object identifier that will be used to read the user ID in the client
522           # certificate. The object identifier should be part of the certificate´s DN
523           # Useful OIDs are:
524           #  CN = 2.5.4.3, UID = 0.9.2342.19200300.100.1.1, SAN(rfc822name)
525           cert-user-oid = 0.9.2342.19200300.100.1.1
526
527           # The object identifier that will be used to read the user group in the
528           # client certificate. The object identifier should be part of the certificate´s
529           # DN. If the user may belong to multiple groups, then use multiple such fields
530           # in the certificate´s DN. Useful OIDs are:
531           #  OU (organizational unit) = 2.5.4.11
532           #cert-group-oid = 2.5.4.11
533
534           # The revocation list of the certificates issued by the ´ca-cert´ above.
535           # See the manual to generate an empty CRL initially. The CRL will be reloaded
536           # periodically when ocserv detects a change in the file. To force a reload use
537           # SIGHUP.
538           #crl = /etc/ocserv/crl.pem
539
540           # Uncomment this to enable compression negotiation (LZS, LZ4).
541           #compression = true
542
543           # Set the minimum size under which a packet will not be compressed.
544           # That is to allow low-latency for VoIP packets. The default size
545           # is 256 bytes. Modify it if the clients typically use compression
546           # as well of VoIP with codecs that exceed the default value.
547           #no-compress-limit = 256
548
549           # GnuTLS priority string; note that SSL 3.0 is disabled by default
550           # as there are no openconnect (and possibly anyconnect clients) using
551           # that protocol. The string below does not enforce perfect forward
552           # secrecy, in order to be compatible with legacy clients.
553           #
554           # Note that the most performant ciphersuites are the moment are the ones
555           # involving AES-GCM. These are very fast in x86 and x86-64 hardware, and
556           # in addition require no padding, thus taking full advantage of the MTU.
557           # For that to be taken advantage of, the openconnect client must be
558           # used, and the server must be compiled against GnuTLS 3.2.7 or later.
559           # Use "gnutls-cli --benchmark-tls-ciphers", to see the performance
560           # difference with AES_128_CBC_SHA1 (the default for anyconnect clients)
561           # in your system.
562
563           tls-priorities = "NORMAL:%SERVER_PRECEDENCE:%COMPAT:-VERS-SSL3.0"
564
565           # More combinations in priority strings are available, check
566           # http://gnutls.org/manual/html_node/Priority-Strings.html
567           # E.g., the string below enforces perfect forward secrecy (PFS)
568           # on the main channel.
569           #tls-priorities = "NORMAL:%SERVER_PRECEDENCE:%COMPAT:-RSA:-VERS-SSL3.0:-ARCFOUR-128"
570
571           # That option requires the established DTLS channel to use the same
572           # cipher as the primary TLS channel. This cannot be combined with
573           # listen-clear-file since the ciphersuite information is not available
574           # in that configuration. Note also, that this option implies that
575           # dtls-legacy option is false; this option cannot be enforced
576           # in the legacy/compat protocol.
577           #match-tls-dtls-ciphers = true
578
579           # The time (in seconds) that a client is allowed to stay connected prior
580           # to authentication
581           auth-timeout = 240
582
583           # The time (in seconds) that a client is allowed to stay idle (no traffic)
584           # before being disconnected. Unset to disable.
585           #idle-timeout = 1200
586
587           # The time (in seconds) that a client is allowed to stay connected
588           # Unset to disable. When set a client will be disconnected after being
589           # continuously connected for this amount of time, and its cookies will
590           # be invalidated (i.e., re-authentication will be required).
591           #session-timeout = 86400
592
593           # The time (in seconds) that a mobile client is allowed to stay idle (no
594           # traffic) before being disconnected. Unset to disable.
595           #mobile-idle-timeout = 2400
596
597           # The time (in seconds) that a client is not allowed to reconnect after
598           # a failed authentication attempt.
599           min-reauth-time = 300
600
601           # Banning clients in ocserv works with a point system. IP addresses
602           # that get a score over that configured number are banned for
603           # min-reauth-time seconds. By default a wrong password attempt is 10 points,
604           # a KKDCP POST is 1 point, and a connection is 1 point. Note that
605           # due to difference processes being involved the count of points
606           # will not be real-time precise.
607           #
608           # Score banning cannot be reliably used when receiving proxied connections
609           # locally from an HTTP server (i.e., when listen-clear-file is used).
610           #
611           # Set to zero to disable.
612           max-ban-score = 80
613
614           # The time (in seconds) that all score kept for a client is reset.
615           ban-reset-time = 1200
616
617           # In case you´d like to change the default points.
618           #ban-points-wrong-password = 10
619           #ban-points-connection = 1
620           #ban-points-kkdcp = 1
621
622           # Cookie timeout (in seconds)
623           # Once a client is authenticated he´s provided a cookie with
624           # which he can reconnect. That cookie will be invalidated if not
625           # used within this timeout value. This cookie remains valid, during
626           # the user´s connected time, and after user disconnection it
627           # remains active for this amount of time. That setting should allow a
628           # reasonable amount of time for roaming between different networks.
629           cookie-timeout = 300
630
631           # If this is enabled (not recommended) the cookies will stay
632           # valid even after a user manually disconnects, and until they
633           # expire. This may improve roaming with some broken clients.
634           #persistent-cookies = true
635
636           # Whether roaming is allowed, i.e., if true a cookie is
637           # restricted to a single IP address and cannot be re-used
638           # from a different IP.
639           deny-roaming = false
640
641           # ReKey time (in seconds)
642           # ocserv will ask the client to refresh keys periodically once
643           # this amount of seconds is elapsed. Set to zero to disable (note
644           # that, some clients fail if rekey is disabled).
645           rekey-time = 172800
646
647           # ReKey method
648           # Valid options: ssl, new-tunnel
649           #  ssl: Will perform an efficient rehandshake on the channel allowing
650           #       a seamless connection during rekey.
651           #  new-tunnel: Will instruct the client to discard and re-establish the channel.
652           #       Use this option only if the connecting clients have issues with the ssl
653           #       option.
654           rekey-method = ssl
655
656           # Script to call when a client connects and obtains an IP.
657           # The following parameters are passed on the environment.
658           # REASON, VHOST, USERNAME, GROUPNAME, DEVICE, IP_REAL (the real IP of the client),
659           # IP_REAL_LOCAL (the local interface IP the client connected), IP_LOCAL
660           # (the local IP in the P-t-P connection), IP_REMOTE (the VPN IP of the client),
661           # IPV6_LOCAL (the IPv6 local address if there are both IPv4 and IPv6
662           # assigned), IPV6_REMOTE (the IPv6 remote address), IPV6_PREFIX, and
663           # ID (a unique numeric ID); REASON may be "connect" or "disconnect".
664           # In addition the following variables OCSERV_ROUTES (the applied routes for this
665           # client), OCSERV_NO_ROUTES, OCSERV_DNS (the DNS servers for this client),
666           # will contain a space separated list of routes or DNS servers. A version
667           # of these variables with the 4 or 6 suffix will contain only the IPv4 or
668           # IPv6 values.
669
670           # The disconnect script will receive the additional values: STATS_BYTES_IN,
671           # STATS_BYTES_OUT, STATS_DURATION that contain a 64-bit counter of the bytes
672           # output from the tun device, and the duration of the session in seconds.
673
674           #connect-script = /usr/bin/myscript
675           #disconnect-script = /usr/bin/myscript
676
677           # UTMP
678           # Register the connected clients to utmp. This will allow viewing
679           # the connected clients using the command ´who´.
680           #use-utmp = true
681
682           # Whether to enable support for the occtl tool (i.e., either through D-BUS,
683           # or via a unix socket).
684           use-occtl = true
685
686           # PID file. It can be overridden in the command line.
687           pid-file = /var/run/ocserv.pid
688
689           # Set the protocol-defined priority (SO_PRIORITY) for packets to
690           # be sent. That is a number from 0 to 6 with 0 being the lowest
691           # priority. Alternatively this can be used to set the IP Type-
692           # Of-Service, by setting it to a hexadecimal number (e.g., 0x20).
693           # This can be set per user/group or globally.
694           #net-priority = 3
695
696           # Set the VPN worker process into a specific cgroup. This is Linux
697           # specific and can be set per user/group or globally.
698           #cgroup = "cpuset,cpu:test"
699
700           #
701           # Network settings
702           #
703
704           # The name to use for the tun device
705           device = vpns
706
707           # Whether the generated IPs will be predictable, i.e., IP stays the
708           # same for the same user when possible.
709           predictable-ips = true
710
711           # The default domain to be advertised
712           default-domain = example.com
713
714           # The pool of addresses that leases will be given from. If the leases
715           # are given via Radius, or via the explicit-ip? per-user config option then
716           # these network values should contain a network with at least a single
717           # address that will remain under the full control of ocserv (that is
718           # to be able to assign the local part of the tun device address).
719           # Note that, you could use addresses from a subnet of your LAN network if you
720           # enable [proxy arp in the LAN interface](http://ocserv.gitlab.io/www/recipes-ocserv-pseudo-bridge.html);
721           # in that case it is recommended to set ping-leases to true.
722           ipv4-network = 192.168.1.0
723           ipv4-netmask = 255.255.255.0
724
725           # An alternative way of specifying the network:
726           #ipv4-network = 192.168.1.0/24
727
728           # The IPv6 subnet that leases will be given from.
729           #ipv6-network = fda9:4efe:7e3b:03ea::/48
730
731           # Specify the size of the network to provide to clients. It is
732           # generally recommended to provide clients with a /64 network in
733           # IPv6, but any subnet may be specified. To provide clients only
734           # with a single IP use the prefix 128.
735           #ipv6-subnet-prefix = 128
736           #ipv6-subnet-prefix = 64
737
738           # Whether to tunnel all DNS queries via the VPN. This is the default
739           # when a default route is set.
740           #tunnel-all-dns = true
741
742           # The advertized DNS server. Use multiple lines for
743           # multiple servers.
744           # dns = fc00::4be0
745           dns = 192.168.1.2
746
747           # The NBNS server (if any)
748           #nbns = 192.168.1.3
749
750           # The domains over which the provided DNS should be used. Use
751           # multiple lines for multiple domains.
752           #split-dns = example.com
753
754           # Prior to leasing any IP from the pool ping it to verify that
755           # it is not in use by another (unrelated to this server) host.
756           # Only set to true, if there can be occupied addresses in the
757           # IP range for leases.
758           ping-leases = false
759
760           # Use this option to set a link MTU value to the incoming
761           # connections. Unset to use the default MTU of the TUN device.
762           # Note that the MTU is negotiated using the value set and the
763           # value sent by the peer.
764           #mtu = 1420
765
766           # Unset to enable bandwidth restrictions (in bytes/sec). The
767           # setting here is global, but can also be set per user or per group.
768           #rx-data-per-sec = 40000
769           #tx-data-per-sec = 40000
770
771           # The number of packets (of MTU size) that are available in
772           # the output buffer. The default is low to improve latency.
773           # Setting it higher will improve throughput.
774           #output-buffer = 10
775
776           # Routes to be forwarded to the client. If you need the
777           # client to forward routes to the server, you may use the
778           # config-per-user/group or even connect and disconnect scripts.
779           #
780           # To set the server as the default gateway for the client just
781           # comment out all routes from the server, or use the special keyword
782           # ´default´.
783
784           route = 10.10.10.0/255.255.255.0
785           route = 192.168.0.0/255.255.0.0
786           #route = fef4:db8:1000:1001::/64
787           #route = default
788
789           # Subsets of the routes above that will not be routed by
790           # the server.
791
792           no-route = 192.168.5.0/255.255.255.0
793
794           # Note the that following two firewalling options currently are available
795           # in Linux systems with iptables software.
796
797           # If set, the script /usr/bin/ocserv-fw will be called to restrict
798           # the user to its allowed routes and prevent him from accessing
799           # any other routes. In case of defaultroute, the no-routes are restricted.
800           # All the routes applied by ocserv can be reverted using /usr/bin/ocserv-fw
801           # --removeall. This option can be set globally or in the per-user configuration.
802           #restrict-user-to-routes = true
803
804           # This option implies restrict-user-to-routes set to true. If set, the
805           # script /usr/bin/ocserv-fw will be called to restrict the user to
806           # access specific ports in the network. This option can be set globally
807           # or in the per-user configuration.
808           #restrict-user-to-ports = "tcp(443), tcp(80), udp(443), sctp(99), tcp(583), icmp(), icmpv6()"
809
810           # You could also use negation, i.e., block the user from accessing these ports only.
811           #restrict-user-to-ports = "!(tcp(443), tcp(80))"
812
813           # When set to true, all client´s iroutes are made visible to all
814           # connecting clients except for the ones offering them. This option
815           # only makes sense if config-per-user is set.
816           #expose-iroutes = true
817
818           # Groups that a client is allowed to select from.
819           # A client may belong in multiple groups, and in certain use-cases
820           # it is needed to switch between them. For these cases the client can
821           # select prior to authentication. Add multiple entries for multiple groups.
822           # The group may be followed by a user-friendly name in brackets.
823           #select-group = group1
824           #select-group = group2[My special group]
825
826           # The name of the (virtual) group that if selected it would assign the user
827           # to its default group.
828           #default-select-group = DEFAULT
829
830           # Instead of specifying manually all the allowed groups, you may instruct
831           # ocserv to scan all available groups and include the full list.
832           #auto-select-group = true
833
834           # Configuration files that will be applied per user connection or
835           # per group. Each file name on these directories must match the username
836           # or the groupname.
837           # The options allowed in the configuration files are dns, nbns,
838           #  ipv?-network, ipv4-netmask, rx/tx-per-sec, iroute, route, no-route,
839           #  explicit-ipv4, explicit-ipv6, net-priority, deny-roaming, no-udp,
840           #  keepalive, dpd, mobile-dpd, max-same-clients, tunnel-all-dns,
841           #  restrict-user-to-routes, user-profile, cgroup, stats-report-time,
842           #  mtu, idle-timeout, mobile-idle-timeout, restrict-user-to-ports,
843           #  and session-timeout.
844           #
845           # Note that the ´iroute´ option allows one to add routes on the server
846           # based on a user or group. The syntax depends on the input accepted
847           # by the commands route-add-cmd and route-del-cmd (see below). The no-udp
848           # is a boolean option (e.g., no-udp = true), and will prevent a UDP session
849           # for that specific user or group. The hostname option will set a
850           # hostname to override any proposed by the user. Note also, that, any
851           # routes, no-routes, DNS or NBNS servers present will overwrite the global ones.
852
853           #config-per-user = /etc/ocserv/config-per-user/
854           #config-per-group = /etc/ocserv/config-per-group/
855
856           # When config-per-xxx is specified and there is no group or user that
857           # matches, then utilize the following configuration.
858           #default-user-config = /etc/ocserv/defaults/user.conf
859           #default-group-config = /etc/ocserv/defaults/group.conf
860
861           # The system command to use to setup a route. %{R} will be replaced with the
862           # route/mask, %{RI} with the route in CIDR format, and %{D} with the (tun) device.
863           #
864           # The following example is from linux systems. %{R} should be something
865           # like 192.168.2.0/255.255.255.0 and %{RI} 192.168.2.0/24 (the argument of iroute).
866
867           #route-add-cmd = "ip route add %{R} dev %{D}"
868           #route-del-cmd = "ip route delete %{R} dev %{D}"
869
870           # This option allows one to forward a proxy. The special keywords ´%{U}´
871           # and ´%{G}´, if present will be replaced by the username and group name.
872           #proxy-url = http://example.com/
873           #proxy-url = http://example.com/%{U}/
874
875           # This option allows you to specify a URL location where a client can
876           # post using MS-KKDCP, and the message will be forwarded to the provided
877           # KDC server. That is a translation URL between HTTP and Kerberos.
878           # In MIT kerberos you´ll need to add in realms:
879           #   EXAMPLE.COM = {
880           #     kdc = https://ocserv.example.com/KdcProxy
881           #     http_anchors = FILE:/etc/ocserv-ca.pem
882           #   }
883           # In some distributions the krb5-k5tls plugin of kinit is required.
884           #
885           # The following option is available in ocserv, when compiled with GSSAPI support.
886
887           #kkdcp = "SERVER-PATH KERBEROS-REALM PROTOCOL@SERVER:PORT"
888           #kkdcp = "/KdcProxy KERBEROS.REALM udp@127.0.0.1:88"
889           #kkdcp = "/KdcProxy KERBEROS.REALM tcp@127.0.0.1:88"
890           #kkdcp = "/KdcProxy KERBEROS.REALM tcp@[::1]:88"
891
892           # Client profile xml. This can be used to advertise alternative servers
893           # to the client. A minimal file can be:
894           # <?xml version="1.0" encoding="UTF-8"?>
895           # <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">
896           #   <ServerList>
897           #       <HostEntry>
898           #               <HostName>VPN Server name</HostName>
899           #               <HostAddress>localhost</HostAddress>
900           #       </HostEntry>
901           #   </ServerList>
902           # </AnyConnectProfile>
903           #
904           # Other fields may be used by some of the CISCO clients.
905           # This file must be accessible from inside the worker´s chroot.
906           # Note that enabling this option is not recommended as it will allow
907           # the worker processes to open arbitrary files (when isolate-workers is
908           # set to true).
909           #user-profile = profile.xml
910
911           #
912           # The following options are for (experimental) AnyConnect client
913           # compatibility.
914
915           # This option will enable the pre-draft-DTLS version of DTLS, and
916           # will not require clients to present their certificate on every TLS
917           # connection. It must be set to true to support legacy CISCO clients
918           # and openconnect clients < 7.08. When set to true, it implies dtls-legacy = true.
919           cisco-client-compat = true
920
921           # This option allows one to disable the DTLS-PSK negotiation (enabled by default).
922           # The DTLS-PSK negotiation was introduced in ocserv 0.11.5 to deprecate
923           # the pre-draft-DTLS negotiation inherited from AnyConnect. It allows the
924           # DTLS channel to negotiate its ciphers and the DTLS protocol version.
925           #dtls-psk = false
926
927           # This option allows one to disable the legacy DTLS negotiation (enabled by default,
928           # but that may change in the future).
929           # The legacy DTLS uses a pre-draft version of the DTLS protocol and was
930           # from AnyConnect protocol. It has several limitations, that are addressed
931           # by the dtls-psk protocol supported by openconnect 7.08+.
932           dtls-legacy = true
933
934           #Advanced options
935
936           # Option to allow sending arbitrary custom headers to the client after
937           # authentication and prior to VPN tunnel establishment. You shouldn´t
938           # need to use this option normally; if you do and you think that
939           # this may help others, please send your settings and reason to
940           # the openconnect mailing list. The special keywords ´%{U}´
941           # and ´%{G}´, if present will be replaced by the username and group name.
942           #custom-header = "X-My-Header: hi there"
943
944
945
946           # An example virtual host with different authentication methods serviced
947           # by this server.
948
949           [vhost:www.example.com]
950           auth = "certificate"
951
952           ca-cert = ../tests/certs/ca.pem
953
954           # The certificate set here must include a ´dns_name´ corresponding to
955           # the virtual host name.
956
957           server-cert = ../tests/certs/server-cert-secp521r1.pem
958           server-key = ../tests/certs/server-key-secp521r1.pem
959
960           ipv4-network = 192.168.2.0
961           ipv4-netmask = 255.255.255.0
962
963           cert-user-oid = 0.9.2342.19200300.100.1.1
964
965
966

SEE ALSO

968       occtl(8), ocpasswd(8), openconnect(8)
969
971       Copyright (C) 2013-2018 Nikos Mavrogiannopoulos and others, all  rights
972       reserved.  This  program is released under the terms of the GNU General
973       Public License, version 2.
974

AUTHORS

976       Written by Nikos Mavrogiannopoulos. Many people have contributed to it.
977
978
979
980                                  March 2019                         OCSERV(8)
Impressum