Merge "wireguard: Add routes for allowedIPs" into tizen

[platform/upstream/connman.git] / doc / config-format.txt

diff --git a/doc/config-format.txt b/doc/config-format.txt
old mode 100644 (file)
new mode 100755 (executable)
index 48b6453..cdde9cb
--- a/doc/config-format.txt
+++ b/doc/config-format.txt
@@ -3,53 +3,125 @@ 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
 
 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 should follow the *.config
-pattern.
-Those configuration files are text files with a simple format and we typically
-have one file per provisioned network.
+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 entry [global]
-=====================

 
 

-These files can have an optional global entry describing the actual file.
-The 2 allowed fields for that entry are:
+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.
 
 
 - 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
 
 Each provisioned service must start with the [service_*] tag. Replace * with

-your service identifier.
-The service identifier can be anything and will be used internally by connman
-to store the different services into an hash table.
+an identifier unique to the config file.

 
 Allowed fields:
 
 Allowed fields:

-- Type: Service type. We currently only support wifi.
-- SSID: An hexadecimal or a string representation of a 802.11 SSID.
-- EAP: EAP type. We currently only support tls or peap.
+- 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.
+- DeviceName: The interface name where this setting should be applied, e.g.
+  eth0. The MAC address will take preference over DeviceName in matching.
+- 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
+- mDNS: Boolean value (true or false). True means that mDNS is enabled.
+  mDNS domains can be resolved and hostname is registered. False means
+  that all mDNS functionality for this service is disabled. Note that
+  not all DNS backends support mDNS: currently systemd-resolved is
+  the only DNS backend with mDNS.
+
+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.
 - 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.
+  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.
 - Identity: Identity string for EAP.

-- Phase2: Phase2 (inner authentication with TLS tunnel) parameters.
+- AnonymousIdentity: Anonymous Identity string for EAP.
+- SubjectMatch: Substring to be matched against the subject of the
+  authentication server certificate for EAP.
+- AltSubjectMatch: Semicolon separated string of entries to be matched against
+  the alternative subject name of the authentication server certificate for EAP.
+- DomainSuffixMatch: Constraint for server domain name. If set, this FQDN is
+  used as a suffix match requirement for the authentication server certificate
+  for EAP.
+- DomainMatch: This FQDN is used as a full match requirement for the
+  authentication server certificate 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
 - 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.

 
 
 
 

-Example
-=======
+Examples
+========

 
 

-This is a configuration file for a network providing both EAP-TLS and
-EAP-PEAP services.
-The respective SSIDs are tls_ssid and peap_ssid and the file name is
-example.config.
+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]
 
 example@example:[~]$ cat /var/lib/connman/example.config
 [global]


@@ -66,10 +138,35 @@ PrivateKeyFile = /home/user/.certs/client.fsid.pem
 PrivateKeyPassphraseType = fsid
 Identity = user
 
 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
 [service_peap]
 Type = wifi

-SSID = peap_ssid
+Name = peap_ssid

 EAP = peap
 EAP = peap

-CACert = /home/user/.cert/ca.pem
+CACertFile = /home/user/.cert/ca.pem

 Phase2 = MSCHAPV2
 Identity = user
 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