doc/config-format.txt

   1 Connman configuration file format
   2 *********************************
   3
   4 Connman uses configuration files to provision existing services. Connman will
   5 be looking for its configuration files at STORAGEDIR which by default points
   6 to /var/lib/connman/. Configuration file names must not include other
   7 characters than letters or numbers and must have a .config suffix.
   8 Those configuration files are text files with a simple key-value pair format,
   9 organized into sections. Values do not comprise leading or trailing whitespace.
  10 We typically have one file per provisioned network.
  11
  12 If the config file is removed, then Connman tries to remove the
  13 provisioned services. If an individual service inside a config is removed,
  14 then the corresponding provisioned service is removed. If a service section
  15 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 Service sections [service_*]
  29 ============================
  30
  31 Each provisioned service must start with the [service_*] tag. Replace * with
  32 an identifier unique to the config file.
  33
  34 Allowed fields:
  35 - Type: Service type. We currently only support wifi and ethernet.
  36 - IPv4: The IPv4 address, netmask and gateway. Format of the entry
  37   is network/netmask/gateway. The mask length can be used instead
  38   of netmask. The gateway can be omitted if necessary.
  39   The IPv4 field can also contain the string "off" or "dhcp".
  40   If the setting is "off", then no IPv4 address is set to the interface.
  41   If the setting is "dhcp", then DHCPv4 address resolution is activated.
  42   Example: 192.168.1.2/24/192.168.1.1
  43            192.168.200.100/255.255.255.0/192.168.200.1
  44            10.0.0.2/24
  45 - IPv6: The IPv6 address, prefix length and gateway. Format of the entry
  46   is network/prefixlen/gateway. For IPv6 addresses only prefix length is
  47   accepted. The gateway can be omitted if necessary.
  48   The IPv6 field can also contain the string "off" or "auto".
  49   If the setting is "off", then no IPv6 address is set to the interface.
  50   If the setting is "auto", then SLAAC or DHCPv6 is used.
  51   Example: 2001:db8::2/64/2001:db8::1
  52            2001:db8::1:2:3:4/64
  53 - IPv6.Privacy: IPv6 privacy option. Value can be either "disabled",
  54   "enabled" or "preferred" (or the misspelled "prefered"). See use_tempaddr
  55   variable description in Linux kernel Documentation/networking/ip-sysctl.txt
  56   file.
  57 - MAC: MAC address of the interface where this setting should be applied.
  58   The MAC address is optional and if it is missing, then the first found
  59   interface is used. The byte values must have prefix 0 added,
  60   the bytes must be separated by ":" char and its length must be
  61   exactly 2 + 1 + 2 + 1 + 2 + 1 + 2 + 1 + 2 + 1 + 2 = 17 characters.
  62 - DeviceName: The interface name where this setting should be applied, e.g.
  63   eth0. The MAC address will take preference over DeviceName in matching.
  64 - Nameservers: Comma separated list of nameservers
  65 - SearchDomains: Comma separated list of DNS search domains
  66 - Timeservers: Comma separated list of timeservers
  67 - Domain: Domain name to be used
  68 - mDNS: Boolean value (true or false). True means that mDNS is enabled.
  69   mDNS domains can be resolved and hostname is registered. False means
  70   that all mDNS functionality for this service is disabled. Note that
  71   not all DNS backends support mDNS: currently systemd-resolved is
  72   the only DNS backend with mDNS.
  73
  74 If IPv4 address is missing then DHCP is used. If IPv6 address is missing,
  75 then SLAAC or DHCPv6 is used.
  76
  77 The following options are valid if Type is "wifi"
  78 - Name: A string representation of an 802.11 SSID. If the SSID field is
  79   present, the Name field is ignored.
  80 - SSID: A hexadecimal representation of an 802.11 SSID. Use this format to
  81   encode special characters including starting or ending spaces. If the SSID
  82   field is omitted, the Name field is used instead.
  83 - EAP: EAP type. We currently only support tls, ttls or peap.
  84 - CACertFile: File path to CA certificate file (PEM/DER).
  85 - ClientCertFile: File path to client certificate file (PEM/DER).
  86 - PrivateKeyFile: File path to client private key file (PEM/DER/PFX).
  87 - PrivateKeyPassphrase: Password/passphrase for private key file.
  88 - PrivateKeyPassphraseType: We only support the fsid passphrase type for now.
  89   This is for private keys generated by using their own filesystem UUID as the
  90   passphrase. The PrivateKeyPassphrase field is ignored when this field is set
  91   to fsid.
  92 - Identity: Identity string for EAP.
  93 - AnonymousIdentity: Anonymous Identity string for EAP.
  94 - SubjectMatch: Substring to be matched against the subject of the
  95   authentication server certificate for EAP.
  96 - AltSubjectMatch: Semicolon separated string of entries to be matched against
  97   the alternative subject name of the authentication server certificate for EAP.
  98 - DomainSuffixMatch: Constraint for server domain name. If set, this FQDN is
  99   used as a suffix match requirement for the authentication server certificate
 100   for EAP.
 101 - DomainMatch: This FQDN is used as a full match requirement for the
 102   authentication server certificate for EAP.
 103 - Phase2: Phase2 (inner authentication with TLS tunnel) authentication method.
 104   Prefix the value with "EAP-" to indicate the usage of an EAP-based inner
 105   authentication method (should only be used with EAP = TTLS).
 106 - Passphrase: RSN/WPA/WPA2 Passphrase
 107 - Security: The security type of the network. Possible values are 'psk'
 108   (WPA/WPA2 PSK), 'ieee8021x' (WPA EAP), 'none' and 'wep'. When not set, the
 109   default value is 'ieee8021x' if an EAP type is configured, 'psk' if a
 110   passphrase is present and 'none' otherwise.
 111 - Hidden: If set to true, then this AP is hidden. If missing or set to false,
 112   then AP is not hidden.
 113
 114
 115 Examples
 116 ========
 117
 118 This is a configuration file for a network providing EAP-TLS, EAP-TTLS and
 119 EAP-PEAP services. The respective SSIDs are tls_ssid, ttls_ssid and peap_ssid
 120 and the file name is example.config.
 121
 122 Please note that the SSID entry is for hexadecimal encoded SSID (e.g. "SSID =
 123 746c735f73736964"). If your SSID does not contain any exotic character then
 124 you should use the Name entry instead (e.g. "Name = tls_ssid").
 125
 126 example@example:[~]$ cat /var/lib/connman/example.config
 127 [global]
 128 Name = Example
 129 Description = Example network configuration
 130
 131 [service_tls]
 132 Type = wifi
 133 SSID = 746c735f73736964
 134 EAP = tls
 135 CACertFile = /home/user/.certs/ca.pem
 136 ClientCertFile = /home/user/devlp/.certs/client.pem
 137 PrivateKeyFile = /home/user/.certs/client.fsid.pem
 138 PrivateKeyPassphraseType = fsid
 139 Identity = user
 140
 141 [service_ttls]
 142 Type = wifi
 143 Name = ttls_ssid
 144 EAP = ttls
 145 CACertFile = /home/user/.cert/ca.pem
 146 Phase2 = MSCHAPV2
 147 Identity = user
 148
 149 [service_peap]
 150 Type = wifi
 151 Name = peap_ssid
 152 EAP = peap
 153 CACertFile = /home/user/.cert/ca.pem
 154 Phase2 = MSCHAPV2
 155 Identity = user
 156
 157 [service_home_ethernet]
 158 Type = ethernet
 159 IPv4 = 192.168.1.42/255.255.255.0/192.168.1.1
 160 IPv6 = 2001:db8::42/64/2001:db8::1
 161 MAC = 01:02:03:04:05:06
 162 Nameservers = 10.2.3.4,192.168.1.99
 163 SearchDomains = my.home,isp.net
 164 Timeservers = 10.172.2.1,ntp.my.isp.net
 165 Domain = my.home
 166
 167 [service_home_wifi]
 168 Type = wifi
 169 Name = my_home_wifi
 170 Passphrase = secret
 171 IPv4 = 192.168.2.2/255.255.255.0/192.168.2.1
 172 MAC = 06:05:04:03:02:01