Merge pull request #78 from telekom-mms/feature/update-docs

Feature/update docs
telekom-mms · Apr 25, 2024 · dbbaaf2 · dbbaaf2
2 parents d47ebf2 + bbb66d2
commit dbbaaf2
Show file tree

Hide file tree

Showing 6 changed files with 135 additions and 99 deletions.
diff --git a/docs/development/api.md b/docs/development/api.md
@@ -1,8 +1,85 @@
 # Daemon API
 
-The daemon API is used by the oc-client and the oc-daemon-vpncscript to
+The Daemon API is used to communicate with the oc-daemon. It actually consists
+of two APIs: the D-Bus API for user interaction and the Unix Socket API for
+communication with the oc-daemon-vpncscript.
+
+## D-Bus API
+
+The D-Bus API is used by oc-client or other client implementations to
 communicate with the oc-daemon.
 
+```console
+$ gdbus introspect --system --dest com.telekom_mms.oc_daemon.Daemon --object-path /com/telekom_mms/oc_daemon/Daemon
+
+node /com/telekom_mms/oc_daemon/Daemon {
+  interface com.telekom_mms.oc_daemon.Daemon {
+    methods:
+      Connect(in  s server,
+              in  s cookie,
+              in  s host,
+              in  s connectURL,
+              in  s fingerprint,
+              in  s resolve);
+      Disconnect();
+    signals:
+    properties:
+      readonly u TrustedNetwork = 1;
+      readonly u OCRunning = 1;
+      readonly s VPNConfig = '';
+      readonly s IP = '';
+      readonly s Server = '';
+      readonly x ConnectedAt = 0;
+      readonly u ConnectionState = 1;
+      readonly s Device = '';
+      readonly as Servers = ['VPN Server 1', 'VPN Server 2'];
+  };
+};
+```
+
+### Methods
+
+`Connect()` is used to connect to a VPN server. The parameter `server` is the
+name of the VPN server. The remaining parameters are the login information
+returned by `openconnect -authenticate`: `Cookie` is an access token containing
+information for authentication and authorization on the VPN server. `Host` is
+the VPN server address. `ConnectURL` is the VPN server URL. `Fingerprint` is
+the fingerprint of the server's certificate. `Resolve` maps the server's host
+name to its IP address to bypass DNS resolution.
+
+`Disconnect()` is used to disconnect from the current VPN server.
+
+### Properties
+
+All properties emit `org.freedesktop.DBus.Properties.PropertiesChanged`
+signals.
+
+`TrustedNetwork` indicates whether a trusted network has been detected.
+
+`OCRunning` indicates whether the OpenConnect process is running.
+
+`VPNConfig` is the VPN network configuration. For the go-representation of the
+configuration see [VPN Network Configuration](vpn-network-config.md).
+
+`IP` is the local client's IP address in the VPN.
+
+`Server` is the name of the current VPN server.
+
+`ConnectedAt` is the time when the VPN connection was established.
+
+`ConnectionState` indicates whether the VPN connection was established using
+the OpenConnect process.
+
+`Device` is the name of the local client's VPN network device (default:
+`oc-daemon-tun0`).
+
+`Servers` is the list of names of available VPN servers.
+
+## Unix Socket API
+
+The Unix Socket API is used by the oc-daemon-vpncscript to communicate with the
+oc-daemon.
+
 ```
 Client    OC-Daemon
   |           |
@@ -26,91 +103,29 @@ Client    OC-Daemon
 
 ```
 +---------------+-----------------+---------------------+
-| Type (16 bit) | Length (16 bit) | Value (Length byte) |
+| Type (16 bit) | Length (32 bit) | Value (Length byte) |
 +---------------+-----------------+---------------------+
 ```
 
 Message format:
 
  * Type: 16 Bits
- * Length: 16 Bits
+ * Length: 32 Bits
  * Value: Length Bytes
 
 Message Types:
 
 * 1: OK (Server Response - OK)
 * 2: Error (Server Response - Error)
-* 3: VPN Connect (Client Request - Connect to VPN)
-* 4: VPN Disconnect (Client Request - Disconnect from VPN)
-* 5: VPN Query (Client Request - Query Status of Daemon/VPN)
-* 6: VPN Config Update (Client Request - Update VPN Network Configuration)
+* 3: VPN Config Update (Client Request - Update VPN Network Configuration)
 
 Value depends on message type:
 
 * JSON object,
 * empty, or
 * in case of Error: error message string
 
-## VPN Connect
-
-* Request
-  * Type: VPN Connect
-  * Value: JSON with login information
-* Response
-  * Type: OK
-  * Value: empty
-
-Go-representation of the login information:
-
-```go
-type LoginInfo struct {
-	Cookie      string
-	Host        string
-	Fingerprint string
-}
-```
-
-The login information represents the information returned by `openconnect
--authenticate`: `Cookie` is an access token containing information for
-authentication and authorization on the VPN server. `Host` is the VPN server.
-`Fingerprint` is the fingerprint of the server's certificate.
-
-## VPN Disconnect
-
-* Request
-  * Type: VPN Disconnect
-  * Value: empty
-* Response
-  * Type: OK
-  * Value: empty
-
-## VPN Query
-
-* Request
-  * Type: VPN Query
-  * Value: empty
-* Response
-  * Type: OK
-  * Value: JSON with VPN/daemon status
-
-Go-representation of the status:
-
-```go
-type Status struct {
-	TrustedNetwork bool
-	Running        bool
-	Connected      bool
-	Config         *Config
-}
-```
-
-`TrustedNetwork` indicates if a trusted network has been detected. `Running`
-indicates if the openconnect process is running. `Connected` indicates if the
-VPN connection was established using the openconnect process. `Config` is the
-VPN network configuration. For the go-representation of the configuration see
-[VPN Network Configuration](vpn-network-config.md).
-
-## VPN Config Update
+### VPN Config Update
 
 * Request
   * Type: VPN Config Update
@@ -125,16 +140,16 @@ Go-representation of the config update:
 type ConfigUpdate struct {
 	Reason string
 	Token  string
-	Config *Config
+	Config *vpnconfig.Config
 }
 ```
 
-`Reason` is the reason of the update: `connect` or `disconnect`. `Token` is
+`Reason` is the reason of the update: `connect` or `disconnect`. `Token` is a
 secret shared between the oc-daemon and the client. It is used to verify a
 legitimate request to change the VPN configuration. `Config` is the VPN network
 configuration. For the go-representation of the configuration see [VPN Network
 Configuration](vpn-network-config.md).
 
-Note: the token is passed from the oc-daemon to openconnect via an environment
-variable. This variable is also passed by openconnect to oc-daemon-vpncscript,
+Note: the token is passed from the oc-daemon to OpenConnect via an environment
+variable. This variable is also passed by OpenConnect to oc-daemon-vpncscript,
 that then uses it in its Config Update request.
diff --git a/docs/development/dns-config.md b/docs/development/dns-config.md
@@ -17,7 +17,7 @@ components inside the oc-daemon. It performs the following operations:
   * Check domain names in DNS queries using watch list
   * Report A records to oc-daemon
   * Report AAAA records to oc-daemon
-  * Store CNAMES in watch list (with a timeout)
+  * Store DNAME and CNAME records in watch list (with a timeout)
 
 ## Split-DNS
 

diff --git a/docs/development/overview.md b/docs/development/overview.md
@@ -67,6 +67,8 @@ User    OC-Client      OC-Daemon     OpenConnect        OC-Daemon-VPNCScript
  |          | <--------    |              |                      |
  |          | ---------------------> Authenticate                |
  |          | <---------------------      |                      |
+ |          | --------> Status            |                      |
+ |          | <--------    |              |                      |
  |          | --------> Connect -----> Connect ----------> Config Update
  |          |           Network <-------------------------       |
  |          |           Config            |                      |
@@ -80,9 +82,10 @@ User    OC-Client      OC-Daemon     OpenConnect        OC-Daemon-VPNCScript
       2. abort, if VPN is already running
    2. runs `openconnect -authenticate`
    3. parses login info from openconnect
-   4. sends "connect" message with login info to oc-daemon
+   4. retrieves and checks status again
+   5. passes login info to oc-daemon with "connect" request
 3. oc-daemon connects to VPN server
-   1. receives login info in oc-client "connect" message
+   1. receives login info in oc-client "connect" request
    2. runs `openconnect -script oc-daemon-vpncscript`
 4. openconnect starts running
    1. establishes tunnel
@@ -110,12 +113,12 @@ User    OC-Client      OC-Daemon     OpenConnect        OC-Daemon-VPNCScript
 ```
 
 1. user runs oc-client with "disconnect" command
-2. oc-client sends "disconnect" request
+2. oc-client requests "disconnect"
    1. oc client retrieves status from oc-daemon
       1. abort, if VPN is not running
-   2. sends "disconnect" message to oc-daemon
+   2. requests "disconnect" from oc-daemon
 3. oc-daemon disconnects VPN
-   1. receives "disconnect" message from oc-client
+   1. receives "disconnect" request from oc-client
    2. terminates running openconnect process
 4. openconect stops running
    1. disconnects tunnel

diff --git a/docs/development/traffic-policing.md b/docs/development/traffic-policing.md
@@ -16,6 +16,7 @@ On startup, Traffic Policing performs the following configuration steps:
   * Allow traffic of related and established connections
   * Allow traffic on allowed devices
   * Allow incoming and outgoing ICMPv4 and ICMPv6 traffic
+  * Allow incoming and outgoing DHCPv4 and DHCPv6 traffic
   * Allow outgoing DNS traffic (port 53)
   * Allow outgoing traffic to allowed IPv4/6 hosts
   * Block all other traffic
@@ -30,7 +31,7 @@ On startup, Traffic Policing performs the following configuration steps:
 * Start Captive Portal Detection (CPD)
   * If portal is detected:
     * Allow HTTP(S) traffic (ports 80 and 443)
-  * If no more portal is detected (after login):
+  * If portal is not detected anymore (after login):
     * Remove HTTP(S) traffic exception
     * Resolve/Update all IPs in sets of allowed IPv4/6 hosts
 
@@ -42,9 +43,7 @@ firewall exceptions in Traffic Policing, so we can log onto the network.
 Captive Portal Detection uses Ubuntu's portal detection scheme. It sends an
 HTTP request to `connectivity-check.ubuntu.com` and expects the response `204
 (No Content)`. If CPD receives a different response, it assumes, there is a
-portal. If the response is a `302 (Redirect)`, CPD reports the host name of the
-redirect location, so Traffic Policing can add the host name to the allowed
-IPv4/6 hosts.
+portal.
 
 In order to allow Ubuntu's and other portal detection schemes, the following
 CPD hosts are added to the allowed IPv4/6 hosts:

diff --git a/docs/user/debug.md b/docs/user/debug.md
@@ -10,8 +10,8 @@ OC-Client and OC-Daemon logs, and with other tools. Some Examples are:
 
 ### Connected Server
 
-You can see the server you are currently connected to in the OC-Client and
-OC-Daemon logs.
+You can see the server you are currently connected to in the `Current Server`
+line in `oc-client status`.
 
 ### Current Profile
 
@@ -20,36 +20,34 @@ the profile name.
 
 ### Connection State
 
-You can see the current connection state with `Connected` in `oc-client
-status`.
+You can see the current connection state in the `Connection State` line in
+`oc-client status`.
 
 ### Local IP
 
-There are two ways to see the current IP used inside the tunnel:
-
-- `IPv4` or `IPv6` in `Config` in `oc-client status`
-- `ip address show dev $DEV`, where `$DEV` is the VPN device name found in
-  `Device -> Name` in `Config` in `oc-client status`
+You can see the current IP used inside the tunnel in the `IP` line in
+`oc-client status`.
 
 ### Server IP
 
-The `Gateway` in `Config` in `oc-client status` is the IP address of the server
-you are currently connected to.
+The `Gateway` entry in the `VPN Config` line in `oc-client status -verbose` is
+the IP address of the server you are currently connected to.
 
 ### Sent/Received Bytes
 
 You can view statistics about sent and received bytes on the tunnel device with
-`ip -statistics a show dev $DEV`, where $DEV is the VPN device name.
+`ip -statistics a show dev $DEV`, where $DEV is the VPN device name (default:
+`oc-daemon-tun0`).
 
 ### Information about Encryption
 
-You can find Information about the used encryption, e.g., cipher suite, in the
+You can find information about the used encryption, e.g., cipher suite, in the
 OC-Client and OC-Daemon log output.
 
 ## Split Routing Details
 
-You can view details about split routing with `oc-client status` and then in
-`Config -> Split`.
+You can view details about split routing with `oc-client status -verbose` in
+the `VPN Config` line and then in the `Split` entry.
 
 `Split` contains the Split Routing configuration with IPv4 address ranges in
 `ExcludeIPv4`, IPv6 address ranges in `ExcludeIPv6` and  DNS-based Excludes in