doc/vpn-config-format.txt

   1 Connman configuration file format for VPN
   2 *****************************************
   3
   4 Connman VPN uses configuration files to provision existing providers.
   5 vpnd will be looking for its configuration files at VPN_STORAGEDIR
   6 which by default points to /var/lib/connman-vpn. Configuration file names
   7 must not include other characters than letters or numbers and must have
   8 a .config suffix. Those configuration files are text files with a simple
   9 key-value pair format organized into sections. Values do not comprise leading
  10 trailing whitespace. We typically have one file per provisioned network.
  11
  12 If the config file is removed, then vpnd tries to remove the
  13 provisioned service. If an individual service entry inside a config is removed,
  14 then the corresponding provisioned service is removed. If a service
  15 section is changed, then the corresponding service is removed and immediately
  16 re-provisioned.
  17
  18
  19 Global section [global]
  20 =======================
  21
  22 These files can have an optional global section describing the actual file.
  23 The two allowed fields for this section are:
  24 - Name: Name of the network.
  25 - Description: Description of the network.
  26
  27
  28 Provider section [provider_*]
  29 =============================
  30
  31 Each provisioned provider must start with the [provider_*] tag.
  32 Replace * with an identifier unique to the config file.
  33
  34 Allowed fields:
  35 - Type: Provider type. Value of OpenConnect, OpenVPN, VPNC, L2TP, PPTP or
  36         WireGuard
  37
  38 VPN related parameters (M = mandatory, O = optional):
  39 - Name: A user defined name for the VPN (M)
  40 - Host: VPN server IP address (M)
  41 - Domain: Domain name for the VPN service (M)
  42 - Networks: The networks behind the VPN link can be defined here. This can
  43   be missing if all traffic should go via VPN tunnel. If there are more
  44   than one network, then separate them by comma. Format of the entry
  45   is network/netmask/gateway. The gateway can be left out. (O)
  46   Example: 192.168.100.0/24/10.1.0.1,192.168.200.0/255.255.255.0/10.1.0.2
  47   For IPv6 addresses only prefix length is accepted like this 2001:db8::1/64
  48
  49 OpenConnect VPN supports following options (see openconnect(8) for details):
  50  Option name            OpenConnect option Description
  51  OpenConnect.ServerCert --servercert       SHA1 certificate fingerprint of the
  52                                            final VPN server after possible web
  53                                            authentication login, selection and
  54                                            redirection (O)
  55  OpenConnect.CACert     --cafile           File containing other Certificate
  56                                            Authorities in addition to the ones
  57                                            in the system trust database (O)
  58  OpenConnect.ClientCert --certificate      Client certificate file, needed
  59                                            by web authentication when AuthType
  60                                            is set as "publickey" (O)
  61  VPN.MTU                --mtu              Request MTU from server as the MTU
  62                                            of the tunnel (O)
  63  OpenConnect.Cookie     --cookie-on-stdin  Cookie received as a result of the
  64                                            web authentication. As the cookie
  65                                            lifetime can be very limited, it
  66                                            does not usually make sense to add
  67                                            it into the configuration file (O)
  68  OpenConnect.VPNHost                       The final VPN server to use after
  69                                            completing the web authentication.
  70                                            Only usable for extremely simple VPN
  71                                            configurations and should normally
  72                                            be set only via the VPN Agent API.
  73  OpenConnect.AllowSelfSignedCert none      Additional option to define if self
  74                                            signed server certificates are
  75                                            allowed. Boolean string and defaults
  76                                            to false, value "true" enables the
  77                                            option. Affects to the OpenConnect
  78                                            internal function only: --servercert
  79                                            is not added to startup parameters
  80                                            and receiving self signed cert from
  81                                            server terminates the connection if
  82                                            set as false (or omitted) (O)
  83  OpenConnect.AuthType                      Type of authentication used with
  84                                            OpenConnect. Applicable values are
  85                                            "cookie", "cookie_with_userpass",
  86                                            "userpass", "publickey" and
  87                                            "pkcs". Value "cookie" is basic
  88                                            cookie based authentication. Value
  89                                            "cookie_with_userpass" means that
  90                                            credentials are used to retrieve the
  91                                            connection cookie, which hides the
  92                                            username from commandline. With
  93                                            value "userpass" username and
  94                                            password are used. Value "publickey"
  95                                            requires CACert and UserPrivateKey
  96                                            to be set. Value "pkcs" uses the
  97                                            PKCSClientCert and requests password
  98                                            input. Defaults to "cookie" (O)
  99     cookie              --cookie-on-stdin  Default cookie based authentication
 100     cookie_with_userpass                   Two phased connection, first
 101         authentication: --cookieonly       authenticate with credentials then
 102                         --passwd-on-stdin  use cookie for connection. Username
 103                         --user             is hidden from commandline during
 104         connection:     --cookie-on-stdin  connection.
 105     userpass            --passwd-on-stdin  Credential based authentication,
 106                         --user             username is visible on commandline.
 107     publickey           --clientcert       Non-encrypted client certificate and
 108                         --sslkey           private key file is used for auth.
 109     pkcs                --cliencert        Authenticate with PKCS#1/PKCS#8/
 110                                            PKCS#12 client certificate.
 111  OpenConnect.DisableIPv6 --disable-ipv6    Do not ask for IPv6 connectivity.
 112                                            Boolean string and defaults to
 113                                            false, value "true" enables the
 114                                            option (O)
 115  OpenConnect.NoDTLS      --no-dtls         Disable DTLS and ESP (O)
 116  OpenConnect.NoHTTPKeepalive --no-http-keepalive    Disable HTTP connection
 117                                            re-use to workaround issues with
 118                                            some servers. Boolean string and
 119                                            defaults to false, value "true"
 120                                            enables the option (O)
 121  OpenConnect.PKCSClientCert --certificate  Certificate and private key in
 122                                            a PKCS#1/PKCS#8/PKCS#12 structure.
 123                                            Needed when AuthType is "pkcs" (O)
 124  OpenConnect.Usergroup  --usergroup        Set login usergroup on remote server
 125                                            (O)
 126  OpenConnect.UserPrivateKey --sslkey       SSL private key file needed by web
 127                                            authentication when AuthType is set
 128                                            as "publickey" (O)
 129
 130 The VPN agent will be contacted to supply the information based on the
 131 authentication type as follows:
 132  Authentication type    Information requested       Saved with name
 133  cookie                 OpenConnect.Cookie          OpenConnect.Cookie
 134  cookie_with_userpass   Username                    OpenConnect.Username
 135                         Password                    OpenConnect.Password
 136  userpass               Username                    OpenConnect.Username
 137                         Password                    OpenConnect.Password
 138  publickey              <none>
 139  pkcs                   OpenConnect.PKCSPassword    OpenConnect.PKCSPassword
 140
 141 OpenVPN VPN supports following options (see openvpn(8) for details):
 142  Option name            OpenVPN option   Description
 143  OpenVPN.CACert         --ca             Certificate authority file (M)
 144  OpenVPN.Cert           --cert           Local peer's signed certificate (M)
 145  OpenVPN.Key            --key            Local peer's private key (M)
 146  OpenVPN.MTU            --mtu            MTU of the tunnel (O)
 147  OpenVPN.NSCertType     --ns-cert-type   Peer certificate type, value of
 148                                          either server or client (O)
 149  OpenVPN.Proto          --proto          Use protocol (O)
 150  OpenVPN.Port           --port           TCP/UDP port number (O)
 151  OpenVPN.AuthUserPass   --auth-user-pass Authenticate with server using
 152                                          username/password (O)
 153  OpenVPN.AskPass        --askpass        Get certificate password from file (O)
 154  OpenVPN.AuthNoCache    --auth-nocache   Don't cache --askpass or
 155                                          --auth-user-pass value (O)
 156  OpenVPN.TLSRemote      --tls-remote     Accept connections only from a host
 157                                          with X509 name or common name equal
 158                                          to name parameter (O). Deprecated in
 159                                          OpenVPN 2.3+.
 160  OpenVPN.TLSAuth        sub-option of --tls-remote (O)
 161  OpenVPN.TLSAuthDir     sub-option of --tls-remote (O)
 162  OpenVPN.TLSCipher      --tls-cipher     Add an additional layer of HMAC
 163                                          authentication on top of the TLS
 164                                          control channel to mitigate DoS attacks
 165                                          and attacks on the TLS stack. Static
 166                                          key file given as parameter (0)
 167  OpenVPN.Cipher         --cipher         Encrypt packets with cipher algorithm
 168                                          given as parameter (O)
 169  OpenVPN.Auth           --auth           Authenticate  packets with HMAC using
 170                                          message digest algorithm alg (O)
 171  OpenVPN.CompLZO        --comp-lzo       Use  fast  LZO compression. Value can
 172                                          be "yes", "no", or "adaptive". Default
 173                                          is adaptive (O)
 174  OpenVPN.RemoteCertTls  --remote-cert-tls Require that peer certificate was
 175                                           signed based on RFC3280 TLS rules.
 176                                           Value is "client" or "server" (O)
 177  OpenVPN.ConfigFile     --config         OpenVPN config file that can contain
 178                                          extra options not supported by OpenVPN
 179                                          plugin (O)
 180  OpenVPN.DeviceType     --dev-type       Whether the VPN should use a tun (OSI
 181                                          layer 3) or tap (OSI layer 2) device.
 182                                          Value is "tun" (default) or "tap" (O)
 183
 184 VPNC VPN supports following options (see vpnc(8) for details):
 185  Option name         VPNC config value     Description
 186  VPNC.IPSec.ID       IPSec ID              your group username (M)
 187  VPNC.IPSec.Secret   IPSec secret          your group password (cleartext) (O)
 188  VPNC.Xauth.Username Xauth username        your username (O)
 189  VPNC.Xauth.Password Xauth password        your password (cleartext) (O)
 190  VPNC.IKE.Authmode   IKE Authmode          IKE Authentication mode (O)
 191  VPNC.IKE.DHGroup    IKE DH Group          name of the IKE DH Group (O)
 192  VPNC.PFS            Perfect Forward Secrecy    Diffie-Hellman group to use for
 193                                                 PFS (O)
 194  VPNC.Domain         Domain                Domain name for authentication (O)
 195  VPNC.Vendor         Vendor                vendor of your IPSec gateway (O)
 196  VPNC.LocalPort      Local Port            local ISAKMP port number to use
 197  VPNC.CiscoPort      Cisco UDP Encapsulation Port    Local UDP port number to
 198                                                      use (O)
 199  VPNC.AppVersion     Application version   Application Version to report (O)
 200  VPNC.NATTMode       NAT Traversal Mode    Which NAT-Traversal Method to use (O)
 201  VPNC.DPDTimeout     DPD idle timeout (our side)    Send DPD packet after
 202                                                     timeout (O)
 203  VPNC.SingleDES      Enable Single DES     enables single DES encryption (O)
 204  VPNC.NoEncryption   Enable no encryption  enables using no encryption for data
 205                                            traffic (O)
 206  VPNC.DeviceType     Interface mode        Whether the VPN should use a tun (OSI
 207                                            layer 3) or tap (OSI layer 2) device.
 208                                            Value is "tun" (default) or "tap" (O)
 209
 210 L2TP VPN supports following options (see xl2tpd.conf(5) and pppd(8) for details)
 211  Option name         xl2tpd config value    Description
 212  L2TP.User           -                      L2TP user name, asked from the user
 213                                             if not set here (O)
 214  L2TP.Password       -                      L2TP password, asked from the user
 215                                             if not set here (O)
 216  L2TP.BPS            bps                    Max bandwidth to use (O)
 217  L2TP.TXBPS          tx bps                 Max transmit bandwidth to use (O)
 218  L2TP.RXBPS          rx bps                 Max receive bandwidth to use (O)
 219  L2TP.LengthBit      length bit             Use length bit (O)
 220  L2TP.Challenge      challenge              Use challenge authentication (O)
 221  L2TP.DefaultRoute   defaultroute           Default route (O)
 222  L2TP.FlowBit        flow bit               Use seq numbers (O)
 223  L2TP.TunnelRWS      tunnel rws             Window size (O)
 224  L2TP.Exclusive      exclusive              Use only one control channel (O)
 225  L2TP.Redial         redial                 Redial if disconnected (O)
 226  L2TP.RedialTimeout  redial timeout         Redial timeout (O)
 227  L2TP.MaxRedials     max redials            How many times to try redial (O)
 228  L2TP.RequirePAP     require pap            Need pap (O)
 229  L2TP.RequireCHAP    require chap           Need chap (O)
 230  L2TP.ReqAuth        require authentication Need auth (O)
 231  L2TP.AccessControl  access control         Accept only these peers (O)
 232  L2TP.AuthFile       auth file              Authentication file location (O)
 233  L2TP.ListenAddr     listen-addr            Listen address (O)
 234  L2TP.IPsecSaref     ipsec saref            Use IPSec SA (O)
 235  L2TP.Port           port                   What UDP port is used (O)
 236
 237  Option name         pppd config value      Description
 238  PPPD.EchoFailure    lcp-echo-failure       Dead peer check count (O)
 239  PPPD.EchoInterval   lcp-echo-interval      Dead peer check interval (O)
 240  PPPD.Debug          debug                  Debug level (O)
 241  PPPD.RefuseEAP      refuse-eap             Deny eap auth (O)
 242  PPPD.RefusePAP      refuse-pap             Deny pap auth (O)
 243  PPPD.RefuseCHAP     refuse-chap            Deny chap auth (O)
 244  PPPD.RefuseMSCHAP   refuse-mschap          Deny mschap auth (O)
 245  PPPD.RefuseMSCHAP2  refuse-mschapv2        Deny mschapv2 auth (O)
 246  PPPD.NoBSDComp      nobsdcomp              Disables BSD compression (O)
 247  PPPD.NoPcomp        nopcomp                Disable protocol compression (O)
 248  PPPD.UseAccomp      noaccomp               Disable address/control
 249                                             compression (O)
 250  PPPD.NoDeflate      nodeflate              Disable deflate compression (O)
 251  PPPD.ReqMPPE        require-mppe           Require the use of MPPE (O)
 252  PPPD.ReqMPPE40      require-mppe-40        Require the use of MPPE 40 bit (O)
 253  PPPD.ReqMPPE128     require-mppe-128       Require the use of MPPE 128 bit (O)
 254  PPPD.ReqMPPEStateful mppe-stateful         Allow MPPE to use stateful mode (O)
 255  PPPD.NoVJ           novj                   No Van Jacobson compression (O)
 256
 257 PPTP VPN supports following options (see pptp(8) and pppd(8) for details)
 258  Option name         pptp config value    Description
 259  PPTP.User           -                    PPTP user name, asked from the user
 260                                           if not set here (O)
 261  PPTP.Password       -                    PPTP password, asked from the user
 262                                           if not set here (O)
 263
 264  Option name         pppd config value    Description
 265  PPPD.EchoFailure    lcp-echo-failure     Dead peer check count (O)
 266  PPPD.EchoInterval   lcp-echo-interval    Dead peer check interval (O)
 267  PPPD.Debug          debug                Debug level (O)
 268  PPPD.RefuseEAP      refuse-eap           Deny eap auth (O)
 269  PPPD.RefusePAP      refuse-pap           Deny pap auth (O)
 270  PPPD.RefuseCHAP     refuse-chap          Deny chap auth (O)
 271  PPPD.RefuseMSCHAP   refuse-mschap        Deny mschap auth (O)
 272  PPPD.RefuseMSCHAP2  refuse-mschapv2      Deny mschapv2 auth (O)
 273  PPPD.NoBSDComp      nobsdcomp            Disables BSD compression (O)
 274  PPPD.NoDeflate      nodeflate            Disable deflate compression (O)
 275  PPPD.RequirMPPE     require-mppe         Require the use of MPPE (O)
 276  PPPD.RequirMPPE40   require-mppe-40      Require the use of MPPE 40 bit (O)
 277  PPPD.RequirMPPE128  require-mppe-128     Require the use of MPPE 128 bit (O)
 278  PPPD.RequirMPPEStateful mppe-stateful    Allow MPPE to use stateful mode (O)
 279  PPPD.NoVJ           novj                 No Van Jacobson compression (O)
 280
 281 WireGuard VPN supports following options
 282  Option name                              Description
 283  WireGuard.Address                        Internal IP address (local/netmask/peer)
 284  WireGuard.ListPort                       Local listen port (optional)
 285  WireGuard.DNS                            List of nameservers separated
 286                                           by comma (optional)
 287  WireGuard.PrivateKey                     Private key of interface
 288  WireGuard.PublicKey                      Public key of peer
 289  WireGuard.PresharedKey                   Preshared key of peer (optional)
 290  WireGuard.AllowedIPs                     See Cryptokey Routing
 291  WireGuard.EndpointPort                   Endpoint listen port (optional)
 292  WireGuard.PersistentKeepalive            Keep alive in seconds (optional)
 293
 294
 295 Example
 296 =======
 297
 298 This is a configuration file for a VPN providing L2TP, OpenVPN and
 299 OpenConnect services.
 300
 301
 302 example@example:[~]$ cat /var/lib/connman/vpn/example.config
 303 [global]
 304 Name = Example
 305 Description = Example VPN configuration
 306
 307 [provider_l2tp]
 308 Type = L2TP
 309 Name = Connection to corporate network
 310 Host = 1.2.3.4
 311 Domain = corporate.com
 312 Networks = 10.10.30.0/24
 313 L2TP.User = username
 314
 315 [provider_openconnect]
 316 Type = OpenConnect
 317 AuthType = pkcs
 318 Name = Connection to corporate network using Cisco VPN
 319 Host = 7.6.5.4
 320 Domain = corporate.com
 321 Networks = 10.10.20.0/255.255.255.0/10.20.1.5,192.168.99.1/24,2001:db8::1/64
 322 OpenConnect.ServerCert = 263AFAB4CB2E6621D12E90182008AEF44AEFA031
 323 OpenConnect.CACert = /etc/certs/certificate.p12
 324
 325 [provider_openvpn]
 326 Type = OpenVPN
 327 Name = Connection to corporate network using OpenVPN
 328 Host = 3.2.5.6
 329 Domain = my.home.network
 330 OpenVPN.CACert = /etc/certs/cacert.pem
 331 OpenVPN.Cert = /etc/certs/cert.pem
 332 OpenVPN.Key = /etc/certs/cert.key
 333
 334 [provider_wireguard]
 335 Type = WireGuard
 336 Name = Wireguard VPN Tunnel
 337 Host = 3.2.5.6
 338 Domain = my.home.network
 339 WireGuard.Address = 10.2.0.2/24
 340 WireGuard.ListenPort = 47824
 341 WireGuard.DNS = 10.2.0.1
 342 WireGuard.PrivateKey = qKIj010hDdWSjQQyVCnEgthLXusBgm3I6HWrJUaJymc=
 343 WireGuard.PublicKey = zzqUfWGIil6QxrAGz77HE5BGUEdD2PgHYnCg3CDKagE=
 344 WireGuard.AllowedIPs = 0.0.0.0/0, ::/0
 345 WireGuard.EndpointPort = 51820