Connman configuration file format for VPN
*****************************************

Connman VPN uses configuration files to provision existing providers.
vpnd will be looking for its configuration files at VPN_STORAGEDIR
which by default points to /var/lib/connman-vpn. Configuration file names
must not include other characters than letters or numbers and must have
a .config suffix. Those configuration files are text files with a simple
key-value pair format organized into sections. Values do not comprise leading
trailing whitespace. We typically have one file per provisioned network.

If the config file is removed, then vpnd tries to remove the
provisioned service. If an individual service entry inside a config is removed,
then the corresponding provisioned service is removed. If a service
section is changed, then the corresponding service is removed and immediately
re-provisioned.


Global section [global]
=======================

These files can have an optional global section describing the actual file.
The two allowed fields for this section are:
- Name: Name of the network.
- Description: Description of the network.


Provider section [provider_*]
=============================

Each provisioned provider must start with the [provider_*] tag.
Replace * with an identifier unique to the config file.

Allowed fields:
- Type: Provider type. Value of OpenConnect, OpenVPN, VPNC, L2TP, PPTP or
        WireGuard

VPN related parameters (M = mandatory, O = optional):
- Name: A user defined name for the VPN (M)
- Host: VPN server IP address (M)
- Domain: Domain name for the VPN service (O)
- Networks: The networks behind the VPN link can be defined here. This can
  be missing if all traffic should go via VPN tunnel. If there are more
  than one network, then separate them by comma. Format of the entry
  is network/netmask/gateway. The gateway can be left out. (O)
  Example: 192.168.100.0/24/10.1.0.1,192.168.200.0/255.255.255.0/10.1.0.2
  For IPv6 addresses only prefix length is accepted like this 2001:db8::1/64

OpenConnect VPN supports following options (see openconnect(8) for details):
 Option name            OpenConnect option Description
 OpenConnect.ServerCert --servercert       SHA1 certificate fingerprint of the
                                           final VPN server after possible web
                                           authentication login, selection and
                                           redirection (O)
 OpenConnect.CACert     --cafile           File containing other Certificate
                                           Authorities in addition to the ones
                                           in the system trust database (O)
 OpenConnect.ClientCert --certificate      Client certificate file, needed
                                           by web authentication when AuthType
                                           is set as "publickey" (O)
 VPN.MTU                --mtu              Request MTU from server as the MTU
                                           of the tunnel (O)
 OpenConnect.Cookie     --cookie-on-stdin  Cookie received as a result of the
                                           web authentication. As the cookie
                                           lifetime can be very limited, it
                                           does not usually make sense to add
                                           it into the configuration file (O)
 OpenConnect.VPNHost                       The final VPN server to use after
                                           completing the web authentication.
                                           Only usable for extremely simple VPN
                                           configurations and should normally
                                           be set only via the VPN Agent API.
 OpenConnect.AllowSelfSignedCert none      Additional option to define if self
                                           signed server certificates are
                                           allowed. Boolean string and defaults
                                           to false, value "true" enables the
                                           option. Affects to the OpenConnect
                                           internal function only: --servercert
                                           is not added to startup parameters
                                           and receiving self signed cert from
                                           server terminates the connection if
                                           set as false (or omitted) (O)
 OpenConnect.AuthType                      Type of authentication used with
                                           OpenConnect. Applicable values are
                                           "cookie", "cookie_with_userpass",
                                           "userpass", "publickey" and
                                           "pkcs". Value "cookie" is basic
                                           cookie based authentication. Value
                                           "cookie_with_userpass" means that
                                           credentials are used to retrieve the
                                           connection cookie, which hides the
                                           username from commandline. With
                                           value "userpass" username and
                                           password are used. Value "publickey"
                                           requires CACert and UserPrivateKey
                                           to be set. Value "pkcs" uses the
                                           PKCSClientCert and requests password
                                           input. Defaults to "cookie" (O)
    cookie              --cookie-on-stdin  Default cookie based authentication
    cookie_with_userpass                   Two phased connection, first
        authentication: --cookieonly       authenticate with credentials then
                        --passwd-on-stdin  use cookie for connection. Username
                        --user             is hidden from commandline during
        connection:     --cookie-on-stdin  connection.
    userpass            --passwd-on-stdin  Credential based authentication,
                        --user             username is visible on commandline.
    publickey           --clientcert       Non-encrypted client certificate and
                        --sslkey           private key file is used for auth.
    pkcs                --cliencert        Authenticate with PKCS#1/PKCS#8/
                                           PKCS#12 client certificate.
 OpenConnect.DisableIPv6 --disable-ipv6    Do not ask for IPv6 connectivity.
                                           Boolean string and defaults to
                                           false, value "true" enables the
                                           option (O)
 OpenConnect.NoDTLS      --no-dtls         Disable DTLS and ESP (O)
 OpenConnect.NoHTTPKeepalive --no-http-keepalive    Disable HTTP connection
                                           re-use to workaround issues with
                                           some servers. Boolean string and
                                           defaults to false, value "true"
                                           enables the option (O)
 OpenConnect.PKCSClientCert --certificate  Certificate and private key in
                                           a PKCS#1/PKCS#8/PKCS#12 structure.
                                           Needed when AuthType is "pkcs" (O)
 OpenConnect.Usergroup  --usergroup        Set login usergroup on remote server
                                           (O)
 OpenConnect.UserPrivateKey --sslkey       SSL private key file needed by web
                                           authentication when AuthType is set
                                           as "publickey" (O)

The VPN agent will be contacted to supply the information based on the
authentication type as follows:
 Authentication type    Information requested       Saved with name
 cookie                 OpenConnect.Cookie          OpenConnect.Cookie
 cookie_with_userpass   Username                    OpenConnect.Username
                        Password                    OpenConnect.Password
 userpass               Username                    OpenConnect.Username
                        Password                    OpenConnect.Password
 publickey              <none>
 pkcs                   OpenConnect.PKCSPassword    OpenConnect.PKCSPassword

OpenVPN VPN supports following options (see openvpn(8) for details):
 Option name            OpenVPN option   Description
 OpenVPN.CACert         --ca             Certificate authority file (M)
 OpenVPN.Cert           --cert           Local peer's signed certificate (M)
 OpenVPN.Key            --key            Local peer's private key (M)
 OpenVPN.MTU            --mtu            MTU of the tunnel (O)
 OpenVPN.NSCertType     --ns-cert-type   Peer certificate type, value of
                                         either server or client (O)
 OpenVPN.Proto          --proto          Use protocol (O)
 OpenVPN.Port           --port           TCP/UDP port number (O)
 OpenVPN.AuthUserPass   --auth-user-pass Authenticate with server using
                                         username/password (O)
 OpenVPN.AskPass        --askpass        Get certificate password from file (O)
 OpenVPN.AuthNoCache    --auth-nocache   Don't cache --askpass or
                                         --auth-user-pass value (O)
 OpenVPN.TLSRemote      --tls-remote     Accept connections only from a host
                                         with X509 name or common name equal
                                         to name parameter (O). Deprecated in
                                         OpenVPN 2.3+.
 OpenVPN.TLSAuth        sub-option of --tls-remote (O)
 OpenVPN.TLSAuthDir     sub-option of --tls-remote (O)
 OpenVPN.TLSCipher      --tls-cipher     Add an additional layer of HMAC
                                         authentication on top of the TLS
                                         control channel to mitigate DoS attacks
                                         and attacks on the TLS stack. Static
                                         key file given as parameter (0)
 OpenVPN.Cipher         --cipher         Encrypt packets with cipher algorithm
                                         given as parameter (O)
 OpenVPN.Auth           --auth           Authenticate  packets with HMAC using
                                         message digest algorithm alg (O)
 OpenVPN.CompLZO        --comp-lzo       Use  fast  LZO compression. Value can
                                         be "yes", "no", or "adaptive". Default
                                         is adaptive (O)
 OpenVPN.RemoteCertTls  --remote-cert-tls Require that peer certificate was
                                          signed based on RFC3280 TLS rules.
                                          Value is "client" or "server" (O)
 OpenVPN.ConfigFile     --config         OpenVPN config file that can contain
                                         extra options not supported by OpenVPN
                                         plugin (O)
 OpenVPN.DeviceType     --dev-type       Whether the VPN should use a tun (OSI
                                         layer 3) or tap (OSI layer 2) device.
                                         Value is "tun" (default) or "tap" (O)

VPNC VPN supports following options (see vpnc(8) for details):
 Option name         VPNC config value     Description
 VPNC.IPSec.ID       IPSec ID              your group username (M)
 VPNC.IPSec.Secret   IPSec secret          your group password (cleartext) (O)
 VPNC.Xauth.Username Xauth username        your username (O)
 VPNC.Xauth.Password Xauth password        your password (cleartext) (O)
 VPNC.IKE.Authmode   IKE Authmode          IKE Authentication mode (O)
 VPNC.IKE.DHGroup    IKE DH Group          name of the IKE DH Group (O)
 VPNC.PFS            Perfect Forward Secrecy    Diffie-Hellman group to use for
						PFS (O)
 VPNC.Domain         Domain                Domain name for authentication (O)
 VPNC.Vendor         Vendor                vendor of your IPSec gateway (O)
 VPNC.LocalPort      Local Port            local ISAKMP port number to use
 VPNC.CiscoPort      Cisco UDP Encapsulation Port    Local UDP port number to
						     use (O)
 VPNC.AppVersion     Application version   Application Version to report (O)
 VPNC.NATTMode       NAT Traversal Mode    Which NAT-Traversal Method to use (O)
 VPNC.DPDTimeout     DPD idle timeout (our side)    Send DPD packet after
						    timeout (O)
 VPNC.SingleDES      Enable Single DES     enables single DES encryption (O)
 VPNC.NoEncryption   Enable no encryption  enables using no encryption for data
					   traffic (O)
 VPNC.DeviceType     Interface mode        Whether the VPN should use a tun (OSI
                                           layer 3) or tap (OSI layer 2) device.
                                           Value is "tun" (default) or "tap" (O)

L2TP VPN supports following options (see xl2tpd.conf(5) and pppd(8) for details)
 Option name         xl2tpd config value    Description
 L2TP.User           -                      L2TP user name, asked from the user
                                            if not set here (O)
 L2TP.Password       -                      L2TP password, asked from the user
                                            if not set here (O)
 L2TP.BPS            bps                    Max bandwidth to use (O)
 L2TP.TXBPS          tx bps                 Max transmit bandwidth to use (O)
 L2TP.RXBPS          rx bps                 Max receive bandwidth to use (O)
 L2TP.LengthBit      length bit             Use length bit (O)
 L2TP.Challenge      challenge              Use challenge authentication (O)
 L2TP.DefaultRoute   defaultroute           Default route (O)
 L2TP.FlowBit        flow bit               Use seq numbers (O)
 L2TP.TunnelRWS      tunnel rws             Window size (O)
 L2TP.Exclusive      exclusive              Use only one control channel (O)
 L2TP.Redial         redial                 Redial if disconnected (O)
 L2TP.RedialTimeout  redial timeout         Redial timeout (O)
 L2TP.MaxRedials     max redials            How many times to try redial (O)
 L2TP.RequirePAP     require pap            Need pap (O)
 L2TP.RequireCHAP    require chap           Need chap (O)
 L2TP.ReqAuth        require authentication Need auth (O)
 L2TP.AccessControl  access control         Accept only these peers (O)
 L2TP.AuthFile       auth file              Authentication file location (O)
 L2TP.ListenAddr     listen-addr            Listen address (O)
 L2TP.IPsecSaref     ipsec saref            Use IPSec SA (O)
 L2TP.Port           port                   What UDP port is used (O)

 Option name         pppd config value      Description
 PPPD.EchoFailure    lcp-echo-failure       Dead peer check count (O)
 PPPD.EchoInterval   lcp-echo-interval      Dead peer check interval (O)
 PPPD.Debug          debug                  Debug level (O)
 PPPD.RefuseEAP      refuse-eap             Deny eap auth (O)
 PPPD.RefusePAP      refuse-pap             Deny pap auth (O)
 PPPD.RefuseCHAP     refuse-chap            Deny chap auth (O)
 PPPD.RefuseMSCHAP   refuse-mschap          Deny mschap auth (O)
 PPPD.RefuseMSCHAP2  refuse-mschapv2        Deny mschapv2 auth (O)
 PPPD.NoBSDComp      nobsdcomp              Disables BSD compression (O)
 PPPD.NoPcomp        nopcomp                Disable protocol compression (O)
 PPPD.UseAccomp      noaccomp               Disable address/control
					    compression (O)
 PPPD.NoDeflate      nodeflate              Disable deflate compression (O)
 PPPD.ReqMPPE        require-mppe           Require the use of MPPE (O)
 PPPD.ReqMPPE40      require-mppe-40        Require the use of MPPE 40 bit (O)
 PPPD.ReqMPPE128     require-mppe-128       Require the use of MPPE 128 bit (O)
 PPPD.ReqMPPEStateful mppe-stateful         Allow MPPE to use stateful mode (O)
 PPPD.NoVJ           novj                   No Van Jacobson compression (O)

PPTP VPN supports following options (see pptp(8) and pppd(8) for details)
 Option name         pptp config value    Description
 PPTP.User           -                    PPTP user name, asked from the user
                                          if not set here (O)
 PPTP.Password       -                    PPTP password, asked from the user
                                          if not set here (O)

 Option name         pppd config value    Description
 PPPD.EchoFailure    lcp-echo-failure     Dead peer check count (O)
 PPPD.EchoInterval   lcp-echo-interval    Dead peer check interval (O)
 PPPD.Debug          debug                Debug level (O)
 PPPD.RefuseEAP      refuse-eap           Deny eap auth (O)
 PPPD.RefusePAP      refuse-pap           Deny pap auth (O)
 PPPD.RefuseCHAP     refuse-chap          Deny chap auth (O)
 PPPD.RefuseMSCHAP   refuse-mschap        Deny mschap auth (O)
 PPPD.RefuseMSCHAP2  refuse-mschapv2      Deny mschapv2 auth (O)
 PPPD.NoBSDComp      nobsdcomp            Disables BSD compression (O)
 PPPD.NoDeflate      nodeflate            Disable deflate compression (O)
 PPPD.RequirMPPE     require-mppe         Require the use of MPPE (O)
 PPPD.RequirMPPE40   require-mppe-40      Require the use of MPPE 40 bit (O)
 PPPD.RequirMPPE128  require-mppe-128     Require the use of MPPE 128 bit (O)
 PPPD.RequirMPPEStateful mppe-stateful    Allow MPPE to use stateful mode (O)
 PPPD.NoVJ           novj                 No Van Jacobson compression (O)

WireGuard VPN supports following options
 Option name                              Description
 WireGuard.Address                        Internal IP address (local/netmask/peer)
 WireGuard.ListPort                       Local listen port (optional)
 WireGuard.DNS                            List of nameservers separated
                                          by comma (optional)
 WireGuard.PrivateKey                     Private key of interface
 WireGuard.PublicKey                      Public key of peer
 WireGuard.PresharedKey                   Preshared key of peer (optional)
 WireGuard.AllowedIPs                     See Cryptokey Routing
 WireGuard.EndpointPort                   Endpoint listen port (optional)
 WireGuard.PersistentKeepalive            Keep alive in seconds (optional)


Example
=======

This is a configuration file for a VPN providing L2TP, OpenVPN and
OpenConnect services.


example@example:[~]$ cat /var/lib/connman/vpn/example.config
[global]
Name = Example
Description = Example VPN configuration

[provider_l2tp]
Type = L2TP
Name = Connection to corporate network
Host = 1.2.3.4
Domain = corporate.com
Networks = 10.10.30.0/24
L2TP.User = username

[provider_openconnect]
Type = OpenConnect
AuthType = pkcs
Name = Connection to corporate network using Cisco VPN
Host = 7.6.5.4
Domain = corporate.com
Networks = 10.10.20.0/255.255.255.0/10.20.1.5,192.168.99.1/24,2001:db8::1/64
OpenConnect.ServerCert = 263AFAB4CB2E6621D12E90182008AEF44AEFA031
OpenConnect.CACert = /etc/certs/certificate.p12

[provider_openvpn]
Type = OpenVPN
Name = Connection to corporate network using OpenVPN
Host = 3.2.5.6
Domain = my.home.network
OpenVPN.CACert = /etc/certs/cacert.pem
OpenVPN.Cert = /etc/certs/cert.pem
OpenVPN.Key = /etc/certs/cert.key

[provider_wireguard]
Type = WireGuard
Name = Wireguard VPN Tunnel
Host = 3.2.5.6
Domain = my.home.network
WireGuard.Address = 10.2.0.2/24
WireGuard.ListenPort = 47824
WireGuard.DNS = 10.2.0.1
WireGuard.PrivateKey = qKIj010hDdWSjQQyVCnEgthLXusBgm3I6HWrJUaJymc=
WireGuard.PublicKey = zzqUfWGIil6QxrAGz77HE5BGUEdD2PgHYnCg3CDKagE=
WireGuard.AllowedIPs = 0.0.0.0/0, ::/0
WireGuard.EndpointPort = 51820
