Document configuration file format

Let's avoid having users digging the code to actually understand that
format.

1 files changed, 71 insertions, 0 deletions

diff --git a/doc/config-format.txt b/doc/config-format.txt
new file mode 100644
index 00000000..ef530e60
--- /dev/null
+++ b/doc/config-format.txt
@@ -0,0 +1,71 @@
+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/.
+Those configuration files are text files with a simple format and we typically
+have one file per provisioned network.
+
+
+Global entry [global]
+=====================
+
+These files can have an optional global entry describing the actual file.
+The 2 allowed fields for that entry are:
+- Name: Name of the network.
+- Description: Description of the network.
+
+
+Service entry [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.
+
+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.
+- 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.
+- Identity: Identity string for EAP.
+- Phase2: Phase2 (inner authentication with TLS tunnel) parameters.
+
+
+Example
+=======
+
+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.
+
+[global]
+Name = Example
+Description = Example network configuration
+
+[service_tls]
+Type = wifi
+SSID = 746c735f73736964
+EAP = tls
+CACertFile = /home/user/.certs/ca.pem
+ClientCertFile = /home/user/devlp/.certs/client.pem
+PrivateKeyFile = /home/user/.certs/client.fsid.pem
+PrivateKeyPassphraseType = fsid
+Identity = user
+
+[service_peap]
+Type = wifi
+SSID = peap_ssid
+EAP = peap
+CACert = /home/user/.cert/ca.pem
+Phase2 = MSCHAPV2
+Identity = user