Diffstat (limited to 'doc/config-format.txt')
1 files changed, 30 insertions, 24 deletions
diff --git a/doc/config-format.txt b/doc/config-format.txt
index 24299276..d825070d 100644
@@ -5,27 +5,28 @@ 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 format and we typically
-have one file per provisioned network.
+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 service. If individual service entry inside config is removed,
-then the corresponding provisioned service is removed. If service
-entry is changed, then corresponding service is removed and then
+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
-Global entry [global]
+Global section [global]
-These files can have an optional global entry describing the actual file.
-The 2 allowed fields for that entry are:
+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 entry [service_*]
+Service sections [service_*]
Each provisioned service must start with the [service_*] tag. Replace * with
an identifier unique to the config file.
@@ -34,20 +35,25 @@ 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 field can also contain the string "off" or "dhcp".
+ 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.
- 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 field can also contain the string "off" or "auto".
+ 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.
- IPv6.Privacy: IPv6 privacy option. Value can be either "disabled",
- "enabled" or "prefered". See use_tempaddr variable description in Linux
- kernel Documentation/networking/ip-sysctl.txt file.
+ "enabled" or "preferred" (or the misspelled "prefered"). See use_tempaddr
+ variable description in Linux kernel Documentation/networking/ip-sysctl.txt
- 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,
@@ -64,8 +70,9 @@ 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. If the SSID field is
- omitted, the Name field is used instead.
+- 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).
@@ -84,18 +91,17 @@ The following options are valid if Type is "wifi"
then AP is not hidden.
This is a configuration file for a network providing EAP-TLS, EAP-TTLS and
-The respective SSIDs are tls_ssid, ttls_ssid and peap_ssid and the file name
+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
Name = Example