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