doc/connman-service.config.5.in

   1 .\" connman-service.config(5) manual page
   2 .\"
   3 .\" Copyright (C) 2015 Intel Corporation
   4 .\"
   5 .TH "service-name.config" "5" "2015-10-15" ""
   6 .SH NAME
   7 service-name.config \- ConnMan service provisioning file
   8 .SH SYNOPSIS
   9 .B @storagedir@/\fIservice-name\fB.config
  10 .SH DESCRIPTION
  11 .P
  12 \fIConnMan\fP's services are configured with so called
  13 "\fBprovisioning files\fP" which reside under \fI@storagedir@/\fP.
  14 The files can be named anything, as long as they end in \fB.config\fP.
  15 The provisioning files can be used to configure for example secured
  16 wireless access points which need complex authentication, for example
  17 eduroam, or for static IPs and so on. Each provisioning file can be
  18 used for multiple services at once.
  19 .SH "FILE FORMAT"
  20 .P
  21 The configuration file consists of sections (groups) of key-value pairs.
  22 Lines beginning with a '#' and blank lines are considered comments.
  23 Sections are started by a header line containing the section enclosed
  24 in '[' and ']', and ended implicitly by the start of the next section
  25 or the end of the file. Each key-value pair must be contained in a section.
  26 .P
  27 Description of sections and available keys follows:
  28 .SS [global]
  29 This section is optional, and can be used to describe the actual file. The
  30 two allowed fields for this section are:
  31 .TP
  32 .BI Name= name
  33 Name of the network.
  34 .TP
  35 .BI Description= description
  36 Description of the network.
  37 .SS [service_*]
  38 Each provisioned service must start with a [service_*] tag, with * replaced
  39 by an unique name within the file.
  40 The allowed fields are:
  41 .TP
  42 .B Type=ethernet \fR|\fB wifi
  43 Mandatory. Other types than ethernet or wifi are not supported.
  44 .TP
  45 .BI IPv4=off \ \fR|\  dhcp\ \fR|\  network / netmask / gateway
  46 IPv4 settings for the service. If set to \fBoff\fP, IPv4 won't be used.
  47 If set to \fBdhcp\fP, dhcp will be used to obtain the network settings.
  48 \fInetmask\fP can be specified as length of the mask rather than the
  49 mask itself. The gateway can be omitted when using a static IP.
  50 .TP
  51 .BI IPv6=off \ \fR|\  auto\ \fR|\  network / prefixlength / gateway
  52 IPv6 settings for the service. If set to \fBoff\fP, IPv6 won't be used.
  53 If set to \fBauto\fP, settings will be obtained from the network.
  54 .TP
  55 .B IPv6.Privacy=disabled \fR|\fB enabled \fR|\fB preferred
  56 IPv6 privacy settings as per RFC3041.
  57 .TP
  58 .BI MAC= address
  59 MAC address of the interface to be used. If not specified, the first
  60 found interface is used. Must be in format ab:cd:ef:01:23:45.
  61 .TP
  62 .BI DeviceName= ifname
  63 Device name the interface to be used, e.g. eth0. MAC takes preference
  64 over DeviceName.
  65 .TP
  66 .BI Nameservers= servers
  67 Comma separated list of nameservers.
  68 .TP
  69 .BI SearchDomains= domains
  70 Comma separated list of DNS search domains.
  71 .TP
  72 .BI Timeservers= servers
  73 Comma separated list of timeservers.
  74 .TP
  75 .BI Domain= domain
  76 Domain name to be used.
  77 .TP
  78 The following keys can only be used for wireless networks:
  79 .TP
  80 .BI Name= name
  81 A string representation of an network SSID. If the SSID field is
  82 present, the Name field is ignored. If the SSID field is not present,
  83 this field is mandatory.
  84 .TP
  85 .BI SSID= ssid
  86 SSID: A hexadecimal representation of an 802.11 SSID. Use this format to
  87 encode special characters including starting or ending spaces.
  88 .TP
  89 .BI Passphrase= passphrase
  90 RSN/WPA/WPA2 Passphrase.
  91 .TP
  92 .BI Security= type
  93 The security type of the network. Possible values are \fBpsk\fP
  94 (WPA/WPA2 PSK), \fBieee8021x\fP (WPA EAP), \fBnone\fP and \fBwep\fP.
  95 When not set, the default value is \fBieee8021x\fP if an EAP type is
  96 configured, \fBpsk\fP if a passphrase is present and \fBnone\fP otherwise.
  97 .TP
  98 .B Hidden=true \fR|\fB false
  99 If set to \fBtrue\fP, then this AP is hidden. If missing or set to
 100 \fBfalse\fP, then AP is not hidden.
 101 .TP
 102 The following keys are used for WPA EAP (when \fBSecurity=ieee8021x\fP):
 103 .TP
 104 .B EAP=tls \fR|\fB ttls \fR|\fB peap
 105 EAP type to use. Only \fBtls\fP, \fBttls\fP and \fBpeap\fP are supported.
 106 .TP
 107 .BI CACertFile= file
 108 Path to the CA certificate file. Only PEM and DER formats are supported.
 109 .TP
 110 .BI PrivateKeyFile= file
 111 Path to the private key file. Only PEM, DER and PFX formats are supported.
 112 .TP
 113 .BI PrivateKeyPassphrase= passphrase
 114 Passphrase of the private key.
 115 .TP
 116 .B PrivateKeyPassphraseType=fsid
 117 If specified, use the private key's fsid as the passphrase, and ignore the
 118 PrivateKeyPassphrase field.
 119 .TP
 120 .BI Identity= identity
 121 Identity string for EAP.
 122 .TP
 123 .BI AnonymousIdentity= identity
 124 Anonymous identity string for EAP.
 125 .TP
 126 .BI SubjectMatch= substring
 127 Substring to be matched against the subject of the
 128 authentication server certificate for EAP.
 129 .TP
 130 .BI AltSubjectMatch= substring
 131 Semicolon separated string of entries to be matched against the alternative
 132 subject name of the authentication server certificate for EAP.
 133 .TP
 134 .BI DomainSuffixMatch= domain
 135 Constraint for server domain name. If set, this FQDN is used as a suffix match
 136 requirement for the authentication server certificate for EAP.
 137 .TP
 138 .BI DomainMatch= domain
 139 This FQDN is used as a full match requirement for the
 140 authentication server certificate for EAP.
 141 .TP
 142 .BI Phase2= type
 143 Inner authentication type with for \fBEAP=tls\fP or \fBEAP=ttls\fP. Prefix
 144 the value with \fBEAP-\fP to indicate usage of EAP-based authentication
 145 method (should only be used with \fBEAP=ttls\fP).
 146 .SH "EXAMPLE"
 147 .SS Eduroam
 148 This is a configuration file for eduroam networks. This file could for
 149 example be @storagedir@/eduroam.config. Your university's exact
 150 settings might be different.
 151 .PP
 152 .nf
 153 [service_eduroam]
 154 Type = wifi
 155 Name = eduroam
 156 EAP = peap
 157 Phase2 = MSCHAPV2
 158 CACertFile = /etc/ssl/certs/UNIV_CA.crt
 159 .fi
 160 .SS Complex networking
 161 This is a configuration file for a network providing EAP-TLS, EAP-TTLS and
 162 EAP-PEAP services. The respective SSIDs are tls_ssid, ttls_ssid and peap_ssid
 163 and the file name could be @storagedir@/complex.config.
 164 .PP
 165 Please note that the SSID entry is for hexadecimal encoded SSID (e.g. "SSID =
 166 746c735f73736964"). If your SSID does not contain any exotic character then
 167 you should use the Name entry instead (e.g. "Name = tls_ssid").
 168 .PP
 169 .nf
 170 [global]
 171 Name = Example
 172 Description = Example network configuration
 173
 174 [service_tls]
 175 Type = wifi
 176 SSID = 746c735f73736964
 177 EAP = tls
 178 CACertFile = /home/user/.certs/ca.pem
 179 ClientCertFile = /home/user/devlp/.certs/client.pem
 180 PrivateKeyFile = /home/user/.certs/client.fsid.pem
 181 PrivateKeyPassphraseType = fsid
 182 Identity = user
 183
 184 [service_ttls]
 185 Type = wifi
 186 Name = ttls_ssid
 187 EAP = ttls
 188 CACertFile = /home/user/.cert/ca.pem
 189 Phase2 = MSCHAPV2
 190 Identity = user
 191
 192 [service_peap]
 193 Type = wifi
 194 Name = peap_ssid
 195 EAP = peap
 196 CACertFile = /home/user/.cert/ca.pem
 197 Phase2 = MSCHAPV2
 198 Identity = user
 199
 200 [service_home_ethernet]
 201 Type = ethernet
 202 IPv4 = 192.168.1.42/255.255.255.0/192.168.1.1
 203 IPv6 = 2001:db8::42/64/2001:db8::1
 204 MAC = 01:02:03:04:05:06
 205 Nameservers = 10.2.3.4,192.168.1.99
 206 SearchDomains = my.home,isp.net
 207 Timeservers = 10.172.2.1,ntp.my.isp.net
 208 Domain = my.home
 209
 210 [service_home_wifi]
 211 Type = wifi
 212 Name = my_home_wifi
 213 Passphrase = password
 214 IPv4 = 192.168.2.2/255.255.255.0/192.168.2.1
 215 MAC = 06:05:04:03:02:01
 216
 217 [service_vlan]
 218 Type = ethernet
 219 DeviceName = enp4s0.1
 220 IPv4 = 192.168.1.42/255.255.255.0/192.168.1.1
 221 .fi
 222 .SH "SEE ALSO"
 223 .BR connman (8)