Merge pull request #107954 from sharad4u/master

Adding documentation for various missing fields in the API, updating limits and adding clarity for the operational behavior of Front Door in the docs

Author: PMEds28

articles/frontdoor/front-door-backend-pool.md

@@ -62,14 +62,18 @@ A backend pool defines how the different backends should be evaluated via health
 ### Health probes
 Front Door sends periodic HTTP/HTTPS probe requests to each of your configured backends. Probe requests determine the proximity and health of each backend to load balance your end-user requests. Health probe settings for a backend pool define how we poll the health status of app backends. The following settings are available for load-balancing configuration:
 
-- **Path**. The URL used for probe requests for all the backends in the backend pool. For example, if one of your backends is contoso-westus.azurewebsites.net and the path is set to /probe/test.aspx, then Front Door environments, assuming the protocol is set to HTTP, will send health probe requests to http\://contoso-westus.azurewebsites.net/probe/test.aspx.
+- **Path**: The URL used for probe requests for all the backends in the backend pool. For example, if one of your backends is contoso-westus.azurewebsites.net and the path is set to /probe/test.aspx, then Front Door environments, assuming the protocol is set to HTTP, will send health probe requests to http\://contoso-westus.azurewebsites.net/probe/test.aspx.
 
-- **Protocol**. Defines whether to send the health probe requests from Front Door to your backends with HTTP or HTTPS protocol.
+- **Protocol**: Defines whether to send the health probe requests from Front Door to your backends with HTTP or HTTPS protocol.
 
-- **Interval (seconds)**. Defines the frequency of health probes to your backends, or the intervals in which each of the Front Door environments sends a probe.
+- **Method**:The HTTP method to be used for sending health probes. Options include GET or HEAD (default).
+    > [!NOTE]
+    > For lower load and cost on your backends, Front Door recommends using HEAD requests for health probes.
+
+- **Interval (seconds)**: Defines the frequency of health probes to your backends, or the intervals in which each of the Front Door environments sends a probe.
 
     >[!NOTE]
-    >For faster failovers, set the interval to a lower value. The lower the value, the higher the health probe volume your backends receive. For example, if the interval is set to 30 seconds with 90 Front Door environments or POPs globally, each backend will receive about 3-5 probe requests per second.
+    >For faster failovers, set the interval to a lower value. The lower the value, the higher the health probe volume your backends receive. For example, if the interval is set to 30 seconds with say, 100 Front Door POPs globally, each backend will receive about 200 probe requests per minute.
 
 For more information, see [Health probes](front-door-health-probes.md).
 

articles/frontdoor/front-door-caching.md

@@ -14,7 +14,7 @@ ms.author: sharadag
 ---
 
 # Caching with Azure Front Door
-The following document specifies behavior for Front Door with routing rules that have enabled caching.
+The following document specifies behavior for Front Door with routing rules that have enabled caching. Front Door is a modern Content Delivery Network (CDN) and so along with dynamic site acceleration and load balancing, it also supports caching behaviors just like any other CDN.
 
 ## Delivery of large files
 Azure Front Door delivers large files without a cap on file size. Front Door uses a technique called object chunking. When a large file is requested, Front Door retrieves smaller pieces of the file from the backend. After receiving a full or byte-range file request, a Front Door environment requests the file from the backend in chunks of 8 MB.
@@ -99,7 +99,7 @@ The following order of headers is used in order to determine how long an item wi
 2. Cache-Control: max-age=\<seconds>
 3. Expires: \<http-date>
 
-Cache-Control response headers that indicate that the response won’t be cached such as Cache-Control: private, Cache-Control: no-cache, and Cache-Control: no-store are honored. However, if there are multiple requests in-flight at a POP for the same URL, they may share the response. If no Cache-Control is present the default behavior is that AFD will cache the resource for X amount of time where X is randomly picked between 1 to 3 days.
+Cache-Control response headers that indicate that the response won't be cached such as Cache-Control: private, Cache-Control: no-cache, and Cache-Control: no-store are honored. However, if there are multiple requests in-flight at a POP for the same URL, they may share the response. If no Cache-Control is present the default behavior is that AFD will cache the resource for X amount of time where X is randomly picked between 1 to 3 days.
 
 ## Request headers
 

articles/frontdoor/front-door-custom-domain-https.md

@@ -80,8 +80,8 @@ You can use your own certificate to enable the HTTPS feature. This process is do
 
 2. Azure Key Vault certificates: If you already have a certificate, you can upload it directly to your Azure Key Vault account or you can create a new certificate directly through Azure Key Vault from one of the partner CAs that Azure Key Vault integrates with. Upload your certificate as a **certificate** object, rather than a **secret**.
 
-> [!IMPORTANT]
-> You must upload the certificate in PFX format **without** password protection.
+> [!NOTE]
+> For your own SSL certificate, Front Door doesn't support certificates with EC cryptography algorithms.
 
 #### Register Azure Front Door
 
@@ -256,8 +256,8 @@ The following table shows the operation progress that occurs when you disable HT
     If you have a CNAME entry for your custom domain that points directly to your endpoint hostname (and you are not using the afdverify subdomain name), you won't receive a domain verification email. Validation occurs automatically. Otherwise, if you don't have a CNAME entry and you haven't received an email within 24 hours, contact Microsoft support.
 
 4. *Is using a SAN certificate less secure than a dedicated certificate?*
-	
-	A SAN certificate follows the same encryption and security standards as a dedicated certificate. All issued SSL certificates use SHA-256 for enhanced server security.
+    
+    A SAN certificate follows the same encryption and security standards as a dedicated certificate. All issued SSL certificates use SHA-256 for enhanced server security.
 
 5. *Do I need a Certificate Authority Authorization record with my DNS provider?*
 

articles/frontdoor/front-door-custom-domain.md

@@ -28,6 +28,9 @@ In this tutorial, you learn how to:
 
 [!INCLUDE [quickstarts-free-trial-note](../../includes/quickstarts-free-trial-note.md)]
 
+> [!NOTE]
+> Front Door does **not** support custom domains with [punycode](https://en.wikipedia.org/wiki/Punycode) characters. 
+
 ## Prerequisites
 
 Before you can complete the steps in this tutorial, you must first create a Front Door. For more information, see [Quickstart: Create a Front Door](quickstart-create-front-door.md).

articles/frontdoor/front-door-diagnostics.md

@@ -71,12 +71,14 @@ Front Door currently provides diagnostic logs (batched hourly). Diagnostic logs
 | Property  | Description |
 | ------------- | ------------- |
 | BackendHostname | If request was being forwarded to a backend, this field represents the hostname of the backend. This field will be blank if the request was redirected or forwarded to a regional cache (when caching is enabled for the routing rule). |
+| CacheStatus | For caching scenarios, this field defines the cache hit/miss at the POP |
 | ClientIp | The IP address of the client that made the request. If there was an X-Forwarded-For header in the request, then the Client IP is picked from the same. |
 | ClientPort | The IP port of the client that made the request. |
 | HttpMethod | HTTP method used by the request. |
 | HttpStatusCode | The HTTP status code returned from the proxy. |
 | HttpStatusDetails | Resulting status on the request. Meaning of this string value can be found at a Status reference table. |
 | HttpVersion | Type of the request or connection. |
+| POP | Short name of the edge where the request landed. |
 | RequestBytes | The size of the HTTP request message in bytes, including the request headers and the request body. |
 | RequestUri | URI of the received request. |
 | ResponseBytes | Bytes sent by the backend server as the response.  |
@@ -87,6 +89,16 @@ Front Door currently provides diagnostic logs (batched hourly). Diagnostic logs
 | TrackingReference | The unique reference string that identifies a request served by Front Door, also sent as X-Azure-Ref header to the client. Required for searching details in the access logs for a specific request. |
 | UserAgent | The browser type that the client used. |
 
+**Note:** For various routing configurations and traffic behaviors, some of the fields like backendHostname, cacheStatus, sentToOriginShield, and POP field may respond with different values. The below table explains the different values, these fields will have for various scenarios:
+
+| Scenarios | Count of log entries | POP | BackendHostname | SentToOriginShield | CacheStatus |
+| ------------- | ------------- | ------------- | ------------- | ------------- | ------------- |
+| Routing rule without caching enabled | 1 | Edge POP code | Backend where request was forwarded | False | CONFIG_NOCACHE |
+| Routing rule with caching enabled. Cache hit at the edge POP | 1 | Edge POP code | Empty | False | HIT |
+| Routing rule with caching enabled. Cache miss at edge POP but cache hit at parent cache POP | 2 | 1. Edge POP code</br>2. Parent cache POP code | 1. Parent cache POP hostname</br>2. Empty | 1. True</br>2. False | 1. MISS</br>2. PARTIAL_HIT |
+| Routing rule with caching enabled. Cache miss at both edge and parent cache POP | 2 | 1. Edge POP code</br>2. Parent cache POP code | 1. Parent cache POP hostname</br>2. Backend that helps populate cache | 1. True</br>2. False | 1. MISS</br>2. MISS |
+
+
 ## Next steps
 
 - [Create a Front Door profile](quickstart-create-front-door.md)

articles/frontdoor/front-door-faq.md

@@ -82,22 +82,18 @@ Routes for your Front Door are not ordered and a specific route is selected base
 
 ### How do I lock down the access to my backend to only Azure Front Door?
 
-To lock down your application to accept traffic only from your specific Front Door, you will need to set up IP ACLs for your backend and then restrict the set of accepted values for the header 'X-Forwarded-Host' sent by Azure Front Door. These steps are detailed out as below:
+To lock down your application to accept traffic only from your specific Front Door, you will need to set up IP ACLs for your backend and then restrict the traffic on your backend to the specific value of the header 'X-Azure-FDID' sent by Front Door. These steps are detailed out as below:
 
-- Configure IP ACLing for your backends to accept traffic from Azure Front Door's backend IP address space and Azure's infrastructure services only. We are working towards integrating with [Azure IP Ranges and Service Tags](https://www.microsoft.com/download/details.aspx?id=56519) but for now you can refer the IP ranges as below:
+- Configure IP ACLing for your backends to accept traffic from Azure Front Door's backend IP address space and Azure's infrastructure services only. Refer the IP details below for ACLing your backend:
 
-    - Front Door's **IPv4** backend IP space: `147.243.0.0/16`
-    - Front Door's **IPv6** backend IP space: `2a01:111:2050::/44`
+    - Refer *AzureFrontDoor.Backend* section in [Azure IP Ranges and Service Tags](https://www.microsoft.com/download/details.aspx?id=56519) for Front Door's IPv4 backend IP address range or you can also use the service tag *AzureFrontDoor.Backend* in your [network security groups](https://docs.microsoft.com/azure/virtual-network/security-overview#security-rules) or with [Azure Firewall](https://docs.microsoft.com/azure/firewall/service-tags).
+    - Front Door's **IPv6** backend IP space while covered in the service tag, is not listed in the Azure IP ranges JSON file. If you are looking for explicit IPv6 address range, it is currently limited to `2a01:111:2050::/44`
     - Azure's [basic infrastructure services](https://docs.microsoft.com/azure/virtual-network/security-overview#azure-platform-considerations) through virtualized host IP addresses: `168.63.129.16` and `169.254.169.254`
 
     > [!WARNING]
     > Front Door's backend IP space may change later, however, we will ensure that before that happens, that we would have integrated with [Azure IP Ranges and Service Tags](https://www.microsoft.com/download/details.aspx?id=56519). We recommend that you subscribe to [Azure IP Ranges and Service Tags](https://www.microsoft.com/download/details.aspx?id=56519) for any changes or updates.
 
--	Filter on the values for the incoming header '**X-Forwarded-Host**' sent by Front Door. The only allowed values for the header should be all of the frontend hosts as defined in your Front Door config. In fact even more specifically, only the host names for which you want to accept traffic from, on this particular backend of yours.
-    - Example – let’s say your Front Door config has the following frontend hosts _`contoso.azurefd.net`_ (A), _`www.contoso.com`_ (B), _`api.contoso.com`_ (C), and _`notifications.contoso.com`_ (D). Let’s assume that you have two backends X and Y. 
-    - Backend X should only take traffic from host names A and B. Backend Y can take traffic from A, C, and D.
-    - So, on Backend X you should only accept traffic that has the header '**X-Forwarded-Host**' set to either _`contoso.azurefd.net`_ or _`www.contoso.com`_. For everything else, backend X should reject the traffic.
-    - Similarly, on Backend Y you should only accept traffic that has the header '**X-Forwarded-Host**' set to either _`contoso.azurefd.net`_, _`api.contoso.com`_ or _`notifications.contoso.com`_. For everything else, backend Y should reject the traffic.
+-    Perform a GET operation on your Front Door with the API version `2020-01-01` or higher. The same operation can also be done by referring your Front Door profile in Azure portal. In the 'Overview' section in Azure portal, you will see a field named *Front Door ID" and in the API call this field is called `frontdoorID`. Filter on the incoming header '**X-Azure-FDID**' sent by Front Door to your backend with the value as that of the field `frontdoorID`. 
 
 ### Can the anycast IP change over the lifetime of my Front Door?
 
@@ -178,17 +174,36 @@ The following are the current cipher suites supported by Azure Front Door:
 - TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
 - TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
 
+### Can I configure SSL policy to control SSL Protocol versions?
+
+You can configure a minimum TLS version in Azure Front Door in the custom domain HTTPS settings via Azure portal or the [Azure REST API](https://docs.microsoft.com/rest/api/frontdoorservice/frontdoor/frontdoors/createorupdate#minimumtlsversion). Currently, you can choose between 1.0 and 1.2.
+
+### Can I configure Front Door to only support specific cipher suites?
+
+No, configuring Front Door for specific cipher suites is not supported. However, you can get your own custom SSL certificate from your Certificate Authority (say Verisign, Entrust, or Digicert) and have specific cipher suites marked on the certificate when you have it generated. 
+
+### Does Front Door support OCSP stapling?
+
+Yes, OCSP stapling is supported by default by Front Door and no configuration is required.
+
 ### Does Azure Front Door also support re-encryption of traffic to the backend?
 
 Yes, Azure Front Door supports SSL offload, and end to end SSL, which re-encrypts the traffic to the backend. In fact, since the connections to the backend happen over it's public IP, it is recommended that you configure your Front Door to use HTTPS as the forwarding protocol.
 
-### Can I configure SSL policy to control SSL Protocol versions?
+### Does Front Door support self-signed certificates on the backend for HTTPS connection?
 
-You can configure a minimum TLS version in Azure Front Door via the [Azure REST API](https://docs.microsoft.com/rest/api/frontdoorservice/frontdoor/frontdoors/createorupdate#minimumtlsversion). Currently, you can choose between 1.0 and 1.2.
+No, self-signed certificates are not supported on Front Door and the restriction applies to both:
 
-### Can I configure Front Door to only support specific cipher suites?
+1. **Backends**: You cannot use self-signed certificates when you are forwarding the traffic as HTTPS or HTTPS health probes or filling the cache for from origin for routing rules with caching enabled.
+2. **Frontend**: You cannot use self-signed certificates when using your own custom SSL certificate for enabling HTTPS on your custom domain.
+
+### Why is HTTPS traffic to my backend failing?
+
+For having successful HTTPS connections to your backend whether for health probes or for forwarding requests, there could be two reasons why HTTPS traffic might fail:
 
-No, configuring Front Door for specific cipher suites is not supported. 
+1. **Certificate subject name mismatch**: For HTTPS connections, Front Door expects that your backend presents certificate from a valid CA with subject name(s) matching the backend hostname. As an example, if your backend hostname is set to `myapp-centralus.contosonews.net` and the certificate that your backend presents during the SSL handshake neither has `myapp-centralus.contosonews.net` nor `*myapp-centralus*.contosonews.net` in the subject name, the Front Door will refuse the connection and result in an error. 
+    1. **Solution**: While it is not recommended from a compliance standpoint, you can workaround this error by disabling certificate subject name check for your Front Door. This is present under Settings in Azure portal and under BackendPoolsSettings in the API.
+2. **Backend hosting certificate from invalid CA**: Only certificates from [valid CAs]() can be used at the backend with Front Door. Certificates from internal CAs or self-signed certificates are not allowed.
 
 ## Diagnostics and logging
 

articles/frontdoor/front-door-health-probes.md

@@ -17,8 +17,8 @@ ms.author: sharadag
 
 In order to determine the health and proximity of each backend from a given Front Door environment, each Front Door environment periodically sends a synthetic HTTP/HTTPS request to each of your configured backends. Front Door then uses responses from these probes to determine the "best" backends to which it should route real client requests. 
 
-> [!NOTE]
-> Since Front Door has many edge environments globally, health probe requests volume to your backends can be quite high - ranging from 18 requests every minute to as high as 960 requests per minute, depending on the health probe frequency configured.
+> [!WARNING]
+> Since Front Door has many edge environments globally, health probe requests volume to your backends can be quite high - ranging from 25 requests every minute to as high as 1200 requests per minute, depending on the health probe frequency configured. With the default probe frequency of 30 seconds, the probe volume on your backend should be about 200 requests per minute.
 
 ## Supported protocols
 
@@ -63,6 +63,10 @@ If health probes fail for every backend in a backend pool, then Front Door consi
 
 Once any backend returns to a healthy state, then Front Door will resume the normal load-balancing algorithm.
 
+## Disabling health probes
+
+If you have a single backend in your backend pool, you can choose to disable the health probes reducing the load on your application backend. Even if you have multiple backends in the backend pool but only one of them is in enabled state, you can disable health probes.
+
 ## Next steps
 
 - Learn how to [create a Front Door](quickstart-create-front-door.md).