X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=doc%2Fconfig-format.txt;h=cdde9cbcf67648f35b9bb9d36f7b2da3d2702b2f;hb=fca568ced12e61747d4f28cd0e88f44c30cabcfa;hp=48b6453de4fb512f161a61d3bb96809ea86d7a04;hpb=f1e6754c96248260ae5013bbc03444140417b856;p=platform%2Fupstream%2Fconnman.git diff --git a/doc/config-format.txt b/doc/config-format.txt old mode 100644 new mode 100755 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 -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. -Service entry [service_*] -========================= +Service sections [service_*] +============================ 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: -- 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. -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. -- 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 +- 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] @@ -66,10 +138,35 @@ 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 -SSID = peap_ssid +Name = peap_ssid EAP = peap -CACert = /home/user/.cert/ca.pem +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