DOCS-379 Application name correction

docs/concepts_appid.md

@@ -13,11 +13,13 @@ The SSR has three built-in techniques for affiliating named applications to serv
 2. Using the `application-identification` mode `tls`
 3. Using the `application-identification` mode `module`
 
+Additionally, [Web Filtering](config_domain-based_web_filter.md#overview) provides domain classification using third party data sources to generate a comprehensive, real time, and up-to-date worldwide database for categorizing domains and URLs.
+
 ### DNS-based Services
 
 Generally, when configuring a `service` on a SSR, administrators use the `address` field to identify the IP address(es)/CIDR block(s) that the SSR should use to match to inbound traffic. However, the `address` field will also accept hostnames, such as `www.128technology.com`. When a service uses a hostname in the `address` field, it is referred to as a *DNS-based service*.
 
-For every DNS-based service, the SSR will use its local DNS to resolve the hostnames; for every IP address that is returned the SSR will treat that as though it were configured in the `address` field, and install FIB entries accordingly. It will also refresh these FIB entries based on the time-to-live (TTL) returned by the DNS server. Here is a sample configuration for reference:
+For every DNS-based service, the SSR will use the host system's local DNS capabilities to resolve hostnames; for every IP address that is returned the SSR will treat that as though it were configured in the `address` field, and install FIB entries accordingly. It will also refresh these FIB entries based on the time-to-live (TTL) returned by the DNS server. Here is a sample configuration for reference:
 
 ```
 [email protected]# show config running authority service interchange
@@ -59,114 +61,44 @@ The names used in the `address` field must be DNS-resolvable names. You cannot u
 This technique relies on your SSR getting the same answers from DNS that your clients get. Take for example a massive SaaS provider such as `www.salesforce.com`. Their web site resolves to hundreds or thousands of IP addresses distributed across the globe. When the SSR resolves that hostname, it will get a handful of answers; if a client does the same DNS query and gets a different set of answers, then the traffic the client sends will not match the FIB entries that the SSR has created.
 
 :::tip Key to success
-Use DNS-based services when your destination uses a small set of nonvolatile IP addresses. This technique is perfect for small, hosted services. The effectiveness of using DNS-based services diminishes rapidly when referencing names that resolve to dozens of address or more.
+Use DNS-based services when your destination uses a small set of non-volatile IP addresses. This technique is perfect for small, hosted services. The effectiveness of using DNS-based services diminishes rapidly when referencing names that resolve to dozens of address or more.
 :::
 
 ### AppID based on TLS
 
-The SSR can also *learn about named destinations* by inspecting the traffic that traverses it. This is done by inspecting the X.509 certificate sent by a server during the TLS handshake process. Importantly: *this presupposes that the SSR can route packets to that destination for the purposes of retrieving the server's certificate*. Thus, when using AppID based on TLS, it is important to ensure that there is a `service` and `service-route` capable of reaching that server in addition to the one you'll configure for the named application.
-
-:::note
-Normally this is done by having a "catch-all" service for `0.0.0.0/0` to route traffic out to the internet, but it does not need to be.
-:::
-
-Within the `Server Hello` message sent by a server will include its X.509 certificate, which is decipherable by the client to include information about the server. One such example is here:
-
-```
-[ptimmons@labsystem1 ~]$ openssl x509 -in /tmp/512b-rsa-example-cert.pem -text -noout
-Certificate:
-    Data:
-        Version: 1 (0x0)
-        Serial Number: 3578 (0xdfa)
-    Signature Algorithm: sha1WithRSAEncryption
-        Issuer: C=JP, ST=Tokyo, L=Chuo-ku, O=Frank4DD, OU=WebCert Support, CN=Frank4DD Web CA/[email protected]
-        Validity
-            Not Before: Aug 22 05:26:54 2012 GMT
-            Not After : Aug 21 05:26:54 2017 GMT
-        Subject: C=JP, ST=Tokyo, O=Frank4DD, CN=www.example.com
-        Subject Public Key Info:
-            Public Key Algorithm: rsaEncryption
-                Public-Key: (512 bit)
-                Modulus:
-                    00:9b:fc:66:90:79:84:42:bb:ab:13:fd:2b:7b:f8:
-                    de:15:12:e5:f1:93:e3:06:8a:7b:b8:b1:e1:9e:26:
-                    bb:95:01:bf:e7:30:ed:64:85:02:dd:15:69:a8:34:
-                    b0:06:ec:3f:35:3c:1e:1b:2b:8f:fa:8f:00:1b:df:
-                    07:c6:ac:53:07
-                Exponent: 65537 (0x10001)
-    Signature Algorithm: sha1WithRSAEncryption
-         14:b6:4c:bb:81:79:33:e6:71:a4:da:51:6f:cb:08:1d:8d:60:
-         ec:bc:18:c7:73:47:59:b1:f2:20:48:bb:61:fa:fc:4d:ad:89:
-         8d:d1:21:eb:d5:d8:e5:ba:d6:a6:36:fd:74:50:83:b6:0f:c7:
-         1d:df:7d:e5:2e:81:7f:45:e0:9f:e2:3e:79:ee:d7:30:31:c7:
-         20:72:d9:58:2e:2a:fe:12:5a:34:45:a1:19:08:7c:89:47:5f:
-         4a:95:be:23:21:4a:53:72:da:2a:05:2f:2e:c9:70:f6:5b:fa:
-         fd:df:b4:31:b2:c1:4a:9c:06:25:43:a1:e6:b4:1e:7f:86:9b:
-         16:40
-```
+The SSR can also *learn about named destinations* by inspecting the traffic that traverses it. This is done by inspecting the client hello TLS message sent by a client during the TLS handshake process. Importantly: *this presupposes that the SSR can route packets to that destination for the  purposes of retrieving the clients's message*. Thus, when using AppID based on TLS, it is important to ensure that there is a `service` and `service-route` capable of reaching that server in addition to the one you'll configure for the named application.
 
 :::note
-This sample certificate was supplied by [FM4DD](http://www.fm4dd.com/openssl/certexamples.htm).
+Normally this is done by having a "catch-all" service for `0.0.0.0/0` to route traffic out to the internet, but it does not need to be. Please refer to [**Configuring Web Filtering using the PCLI**](config_domain-based_web_filter.md#configuring-web-filtering-using-the-pcli) for detailed configuration steps.
 :::
 
-About a third of the way through the output you can see that the *Common Name* (listed as `CN` in the `Subject` line) is `www.example.com`. This is what SSR will parse and subsequently retain as the "application name" for this destination. Assuming this matches a configured `application-name` within a `service`, a FIB entry is installed with this server's IP address and associated with the `service`.
-
-To enable application identification based on TLS, configure the `application-identification` element within the `router` context as seen here:
-
-```
-[email protected]# show config running authority router burlington application-identification
-
-config
-
-    authority
-
-        router  burlington
-            name                        burlington
-
-            application-identification
-                mode  tls
-            exit
-        exit
-    exit
-exit
-```
-
-For reference, here's a `service` that would leverage the X.509 certificate shown above:
-
-```
-[email protected]# show config running authority service example
-
-config
-
-    authority
-
-        service  example
-            name                  example
-            description           "www.example.com website"
-            application-name      www.example.com
-
-            access-policy         trusted
-                source      trusted
-                permission  allow
-            exit
-            service-policy        NO-LTE
-            share-service-routes  false
-        exit
-    exit
-exit
+The `Client Hello` message typically includes a `server_name` extension, which represents the domain-name being accessed by the client. For example:
+
+``` console {15-18}
+TLSv1.3 Record Layer: Handshake Protocol: Client Hello
+    Content Type: Handshake (22)
+    Version: TLS 1.0 (0x0301)
+    Length: 562
+    Handshake Protocol: Client Hello
+        Handshake Type: Client Hello (1)
+        Length: 558
+        Version: TLS 1.2 (0x0303)
+        Random: a625da0d64ec96bbf35a2422a5a10816812e978b7f90db592e50be120c0fa9a4
+        Cipher Suites Length: 32
+        Cipher Suites (16 suites)
+        Compression Methods Length: 1
+        Compression Methods (1 method)
+        Extensions Length: 453
+        Extension: server_name (len=20) name=www.example.com
+            Type: server_name (0)
+            Length: 20
+            Server Name Indication extension
+        Extension: compress_certificate (len=3)
+        Extension: application_settings (len=5)
+        Extension: psk_key_exchange_modes (len=2)
 ```
 
-Here we can see the `application-name` set to `www.example.com`, which matches the Common Name from the X.509 certificate in our example. Assuming we had a `service`/`service-route` capable of reaching `www.example.com` to begin with, the TLS handshake would see the server's X.509 certificate returned back to the client through the SSR. The SSR parses the certificate, recognizes `www.example.com` as belonging to the service named `example` and installs a FIB entry for it with the server's IP address.
-
-:::note
-The `example` service needs to have its own `service-route` in order for traffic to be forwarded.
-:::
-
-With the TLS-based application identification technique, the `application-name` can include a wildcard such as `*.example.com`, which is not possible with the DNS-based approach. This gives administrators a bit more flexibility in defining which traffic to match to services when parsing the X.509 certificates.
-
-#### Update for SSR version 5.0
-
-Starting with SSR version 5.0, a FIB entry is no longer installed as part of DPI. Instead, domain-names and IP addresses are learned from TLS and mapped to hierarchical services using the `domain-name` field.
+The `server_name` extension shown above with the value `www.example.com` represents the domain in this example. This is what SSR will parse and subsequently retain as the domain-name for this destination. Domain-names and IP addresses are learned from TLS and mapped to hierarchical services using the `domain-name` field.
 
 ```
 config
@@ -258,7 +190,7 @@ Scripts are placed on the router's filesystem at `/etc/128technology/application
 
 #### Systemd-Based Module Setup
 
-Beginning with the 5.2 release, `systemd` may be used to manage the execution of application identification modules. JSON output produced by the module is passed directly to the highway REST API instead of being written to disk.
+`systemd` may be used to manage the execution of application identification modules. JSON output produced by the module is passed directly to the highway REST API instead of being written to disk.
 
 Using this approach, modules are registered by creating a file at `/etc/128technology/application-modules/services/<module-name>`. This file lists the systemd units of the module and specifies if and how SSR should interact with them.
 - `reload-service`: When the highway process starts, reload the systemd unit. This is a signal to POST the JSON to highway again as module data is not saved through process restarts.
@@ -286,7 +218,7 @@ For more information about using timers with the systemd service, refer to [Arch
 
 #### Viewing Modules
 
-Beginning with the 5.2 release, module registration and detailed module status (including a full list of ip-prefix/ports/protocol) can be accessed via a REST API or from the CLI. Please refer to the API documentation available from the GUI, and the [`show application modules status`](cli_reference.md#show-application-modules-status) and [`show application modules registration`](cli_reference.md#show-application-modules-registration) for full details.
+Module registration and detailed module status (including a full list of ip-prefix/ports/protocol) can be accessed via a REST API or from the CLI. Please refer to the API documentation available from the GUI, and the [`show application modules status`](cli_reference.md#show-application-modules-status) and [`show application modules registration`](cli_reference.md#show-application-modules-registration) for full details.
 
 #### Referencing Modules in Configuration
 

docs/config_app_ident.md

@@ -1,6 +1,6 @@
 ---
-title: Application Identification
-sidebar_label: Application Identification
+title: Application Learning Mode
+sidebar_label: Application Learning Mode
 ---
 
 Application Identification can automatically learn, identify, and classify applications processed by the SSR and store them in the [web filtering cache](config_domain-based_web_filter.md#how-it-works). 

sidebars.js

@@ -62,7 +62,6 @@ module.exports = {
     ],
     "Concepts": [
       "concepts_application_discovery",
-      "concepts_appid",
       "concepts_EthOverSVR",
       "concepts_ha_theoryofoperation",
       "concepts_interface_types",
@@ -132,7 +131,6 @@ module.exports = {
           "config_dns_proxy",
           "config_forward_error_correction",
           "config_management_over_forwarding",
-          "config_app_ident",
           "config_domain-based_web_filter",
           "config_application_steering",
           "config_EthoSVR",
@@ -152,6 +150,15 @@ module.exports = {
           "config_transport_encryption",
         ],
       },
+      {
+        "type": "category",
+        "label": "Application Identification",
+        "items": [
+          "concepts_appid",
+          "config_app_ident",
+          "how_to_use_app_summary",
+        ],
+      },
       {
         "type": "category",
         "label": "Optimizing Routing Protocols",
@@ -228,7 +235,6 @@ module.exports = {
         "type": "category",
         "label": "How To",
         "items": [
-          "how_to_use_app_summary",
           "how_to_local_config_override",
           "howto_extend_gui_nav",
           "howto_lte",