| Connman configuration file format |
| ********************************* |
| |
| Connman uses configuration files to provision existing services. Connman will |
| be looking for its configuration files at STORAGEDIR which by default points |
| to /var/lib/connman/. 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 or trailing whitespace. |
| We typically have one file per provisioned network. |
| |
| If the config file is removed, then Connman tries to remove the |
| provisioned services. If an individual service 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. |
| |
| |
| Service sections [service_*] |
| ============================ |
| |
| Each provisioned service must start with the [service_*] tag. Replace * with |
| an identifier unique to the config file. |
| |
| Allowed fields: |
| - Type: Service type. We currently only support wifi and ethernet. |
| - IPv4: The IPv4 address, netmask and gateway. Format of the entry |
| is network/netmask/gateway. The mask length can be used instead |
| of netmask. The gateway can be omitted if necessary. |
| The IPv4 field can also contain the string "off" or "dhcp". |
| If the setting is "off", then no IPv4 address is set to the interface. |
| If the setting is "dhcp", then DHCPv4 address resolution is activated. |
| Example: 192.168.1.2/24/192.168.1.1 |
| 192.168.200.100/255.255.255.0/192.168.200.1 |
| 10.0.0.2/24 |
| - IPv6: The IPv6 address, prefix length and gateway. Format of the entry |
| is network/prefixlen/gateway. For IPv6 addresses only prefix length is |
| accepted. The gateway can be omitted if necessary. |
| The IPv6 field can also contain the string "off" or "auto". |
| If the setting is "off", then no IPv6 address is set to the interface. |
| If the setting is "auto", then SLAAC or DHCPv6 is used. |
| Example: 2001:db8::2/64/2001:db8::1 |
| 2001:db8::1:2:3:4/64 |
| - IPv6.Privacy: IPv6 privacy option. Value can be either "disabled", |
| "enabled" or "preferred" (or the misspelled "prefered"). See use_tempaddr |
| variable description in Linux kernel Documentation/networking/ip-sysctl.txt |
| file. |
| - MAC: MAC address of the interface where this setting should be applied. |
| The MAC address is optional and if it is missing, then the first found |
| interface is used. The byte values must have prefix 0 added, |
| the bytes must be separated by ":" char and its length must be |
| exactly 2 + 1 + 2 + 1 + 2 + 1 + 2 + 1 + 2 + 1 + 2 = 17 characters. |
| - Nameservers: Comma separated list of nameservers |
| - SearchDomains: Comma separated list of DNS search domains |
| - Timeservers: Comma separated list of timeservers |
| - Domain: Domain name to be used |
| |
| If IPv4 address is missing then DHCP is used. If IPv6 address is missing, |
| then SLAAC or DHCPv6 is used. |
| |
| The following options are valid if Type is "wifi" |
| - Name: A string representation of an 802.11 SSID. If the SSID field is |
| present, the Name field is ignored. |
| - SSID: A hexadecimal representation of an 802.11 SSID. Use this format to |
| encode special characters including starting or ending spaces. If the SSID |
| field is omitted, the Name field is used instead. |
| - EAP: EAP type. We currently only support tls, ttls or peap. |
| - CACertFile: File path to CA certificate file (PEM/DER). |
| - ClientCertFile: File path to client certificate file (PEM/DER). |
| - PrivateKeyFile: File path to client private key file (PEM/DER/PFX). |
| - PrivateKeyPassphrase: Password/passphrase for private key file. |
| - PrivateKeyPassphraseType: We only support the fsid passphrase type for now. |
| This is for private keys generated by using their own filesystem UUID as the |
| passphrase. The PrivateKeyPassphrase field is ignored when this field is set |
| to fsid. |
| - Identity: Identity string for EAP. |
| - Phase2: Phase2 (inner authentication with TLS tunnel) authentication method. |
| Prefix the value with "EAP-" to indicate the usage of an EAP-based inner |
| authentication method (should only be used with EAP = TTLS). |
| - Passphrase: RSN/WPA/WPA2 Passphrase |
| - Security: The security type of the network. Possible values are 'psk' |
| (WPA/WPA2 PSK), 'ieee8021x' (WPA EAP), 'none' and 'wep'. When not set, the |
| default value is 'ieee8021x' if an EAP type is configured, 'psk' if a |
| passphrase is present and 'none' otherwise. |
| - Hidden: If set to true, then this AP is hidden. If missing or set to false, |
| then AP is not hidden. |
| |
| |
| Examples |
| ======== |
| |
| This is a configuration file for a network providing EAP-TLS, EAP-TTLS and |
| EAP-PEAP services. The respective SSIDs are tls_ssid, ttls_ssid and peap_ssid |
| and the file name is example.config. |
| |
| Please note that the SSID entry is for hexadecimal encoded SSID (e.g. "SSID = |
| 746c735f73736964"). If your SSID does not contain any exotic character then |
| you should use the Name entry instead (e.g. "Name = tls_ssid"). |
| |
| example@example:[~]$ cat /var/lib/connman/example.config |
| [global] |
| Name = Example |
| Description = Example network configuration |
| |
| [service_tls] |
| Type = wifi |
| SSID = 746c735f73736964 |
| EAP = tls |
| CACertFile = /home/user/.certs/ca.pem |
| ClientCertFile = /home/user/devlp/.certs/client.pem |
| PrivateKeyFile = /home/user/.certs/client.fsid.pem |
| PrivateKeyPassphraseType = fsid |
| Identity = user |
| |
| [service_ttls] |
| Type = wifi |
| Name = ttls_ssid |
| EAP = ttls |
| CACertFile = /home/user/.cert/ca.pem |
| Phase2 = MSCHAPV2 |
| Identity = user |
| |
| [service_peap] |
| Type = wifi |
| Name = peap_ssid |
| EAP = peap |
| CACertFile = /home/user/.cert/ca.pem |
| Phase2 = MSCHAPV2 |
| Identity = user |
| |
| [service_home_ethernet] |
| Type = ethernet |
| IPv4 = 192.168.1.42/255.255.255.0/192.168.1.1 |
| IPv6 = 2001:db8::42/64/2001:db8::1 |
| MAC = 01:02:03:04:05:06 |
| Nameservers = 10.2.3.4,192.168.1.99 |
| SearchDomains = my.home,isp.net |
| Timeservers = 10.172.2.1,ntp.my.isp.net |
| Domain = my.home |
| |
| [service_home_wifi] |
| Type = wifi |
| Name = my_home_wifi |
| Passphrase = secret |
| IPv4 = 192.168.2.2/255.255.255.0/192.168.2.1 |
| MAC = 06:05:04:03:02:01 |
