Merge pull request #3773 from zowe/anax-v2.17-publishdocs-docs

Anax v2.17 publishdocs docs

docs/user-guide/api-mediation/authenticating-with-personal-access-token.md

@@ -82,7 +82,7 @@ The request requires the body in the following format:
 The user has the option of calling this API to validate the token, however, validation is also automatically performed by the API ML.
 :::
 
-When validation is successful, the response to the request is an empty body with a status code of `200`. When validation fails, the user receives a status code of `401`.
+When validation is successful, the response to the request is an empty body with a status code of `204`. When validation fails, the user receives a status code of `401`.
 
 ### Invalidate a specific token
 
@@ -103,7 +103,7 @@ The request requires the body in the following format:
 When the `/auth/access-token/revoke` endpoint is called, the provided hash of the PAT is stored in the cache by the Caching Service under the `invalidTokens` key. As such, the token is invalidated.
 Access to these entries is protected by the API ML client certificate.
 
-When invalidation is successful, the response to the request is an empty body with a status code of `200`. When invalidation fails, the user receives a status code of `401`.
+When invalidation is successful, the response to the request is an empty body with a status code of `204`. When invalidation fails, the user receives a status code of `401`.
 
 ### Invalidate all tokens
 
@@ -126,7 +126,7 @@ If the body is not provided, the timestamp value defaults to the current date.
 When the `/auth/access-token/revoke/tokens` endpoint is called, the provided user rule is stored in the cache by the Caching Service under the `invalidUsers` key. As such, all of the tokens of the user are invalidated.
 Access to these entries is protected by the client certificate of the API ML.
 
-When invalidation is successful, the response to the request is an empty body with a status code of `200`. When invalidation fails, the user receives a status code of `401`.
+When invalidation is successful, the response to the request is an empty body with a status code of `204`. When invalidation fails, the user receives a status code of `401`.
 
 ## Security Administrator APIs
 
@@ -174,7 +174,7 @@ used to specify that tokens created before the date specified in the timestamp a
 
 By calling this endpoint, the user rule is stored in the cache by the Caching Service under the `invalidUsers` key.
 
-When invalidation is successful, the response to the request is an empty body with a status code of `200`. When invalidation fails, the user receives a status code of `401`.
+When invalidation is successful, the response to the request is an empty body with a status code of `204`. When invalidation fails, the user receives a status code of `401`.
 
 ### Invalidate all tokens for a service
 
@@ -205,7 +205,7 @@ after that date are not affected by the service rule.
 
 Calling this endpoint stores the service rule in the cache by the Caching Service under the `invalidScopes` key.
 
-When invalidation is successful, the response to the request is an empty body with a status code of `200`. When invalidation fails, the user receives a status code of `401`.
+When invalidation is successful, the response to the request is an empty body with a status code of `204`. When invalidation fails, the user receives a status code of `401`.
 
 ### Evict non-relevant tokens and rules
 

docs/user-guide/api-mediation/configuration-authorization.md

@@ -6,4 +6,5 @@
 In Zowe's API Mediation Layer, system administrators can limit access to services and information in the API Catalog by hiding sensitive data like service instance URLs, configurable via the apiml.catalog.hide.serviceInfo property in zowe.yaml. Additionally, SAF resource checking for user authorization on specific endpoints is facilitated through various providers, such as Endpoint, Native, and Dummy. These configurations, modifiable in the zowe.yaml file, enhance security by controlling service exposure and ensuring proper authorization checks within the Zowe ecosystem.
 
 - [Limiting access to information or services in the API Catalog](./configuration-limiting-access-to-info-or-services-in-api-catalog.md)
-- [Configuring SAF resource checking](./configuration-saf-resource-checking.md)
+- [Configuring SAF resource checking](./configuration-saf-resource-checking.md)
+- [Configurint Health Endpoint Protection](./configuration-health-endpoint-protection.md)

docs/user-guide/api-mediation/configuration-connection-limits.md

@@ -5,19 +5,19 @@
 
 ## TCP/IP Connection Limits
 
-By default, the API Gateway accepts up to 100 concurrent connections per route, and 1000 total concurrent connections. Any further concurrent requests are queued until the completion of an existing request. The API Gateway is built on top of Apache HTTP components that require these two connection limits for concurrent requests. 
+By default, the API Gateway accepts up to 100 concurrent connections per route, and 1000 total concurrent connections. Any further concurrent requests are queued until the completion of an existing request. The API Gateway is built on top of Apache HTTP components that require these two connection limits for concurrent requests.
 
 Use the following procedure to change the number of concurrent connections:
 
 1. Open the file `zowe.yaml`.
-2. Find or add the property `zowe.components.gateway.server.maxConnectionsPerRoute` and set the value to an appropriate positive integer.
-3. Find or add the property `zowe.components.gateway.server.maxTotalConnections` and set the value to an appropriate positive integer.
+2. Find or add the property `zowe.components.gateway.server.maxConnectionsPerRoute` and set the value to an appropriate positive integer. Defaults to 100 max reusable connections per route.
+3. Find or add the property `zowe.components.gateway.server.maxTotalConnections` and set the value to an appropriate positive integer. Defaults to 1000 max total concurrent connections.
 
 ## Websocket Limits
 
 The API Mediation Layer supports Websocket connections. It is possible to configure the limits around timeouts. All the values are in milliseconds. Customizing this limit may be practical if you see problems such as with the usage of the TN3270 terminal in Virtual Desktop. 
 
-```
+```yaml
 zowe:
   components:
     gateway:
@@ -26,13 +26,15 @@ zowe:
           connectTimeout: 15000
           stopTimeout: 30000
           asyncWriteTimeout: 60000
-          maxIdleTimeout:3600000
+          maxIdleTimeout: 3600000
+          requestBufferSize: 8192
 ```
 
 Use the following procedure to change the limits:
 
 1. Open the file `zowe.yaml`.
-2. Find or add the property `zowe.components.gateway.server.websocket.connectTimeout`, and set the value to an appropriate positive integer. This timeout limits how long the API Gateway waits until it drops connection if it cannot reach the target server. The default is 15 seconds.
-3. Find or add the property `zowe.components.gateway.server.websocket.stopTimeout`, and set the value to an appropriate positive integer. This timeout handles how long the API Gateway waits before it fails on stop message for the Websocket connection. The default is 30 seconds.
-4. Find or add the property `zowe.components.gateway.server.websocket.asyncWriteTimeout`, and set the value to an appropriate positive integer. This timeout handles how long it takes before the server fails with unsuccessful response when trying to write message to the Websocket connection. The default is 60 seconds.
-5. Find or add the property `zowe.components.gateway.server.websocket.maxIdleTimeout`, and set the value to an appropriate positive integer. This timeout handles how long the Websocket connection remains open if there is no communication happening over the open connection. The default is one hour.
+2. Find or add the property `zowe.components.gateway.server.websocket.connectTimeout`, and set the value to an appropriate positive integer. This timeout limits how long the API Gateway waits until it drops connection if it cannot reach the target server. The default is 45 seconds (45000 milliseconds).
+3. Find or add the property `zowe.components.gateway.server.websocket.stopTimeout`, and set the value to an appropriate positive integer. This timeout handles how long the API Gateway will wait for the graceful stopping of the WebSocket connection. The default is 30 seconds (30000 milliseconds).
+4. Find or add the property `zowe.components.gateway.server.websocket.asyncWriteTimeout`, and set the value to an appropriate positive integer. This timeout handles how long it takes before the server fails with unsuccessful response when trying to write a message to the Websocket connection. The default is 60 seconds (60000 milliseconds).
+5. Find or add the property `zowe.components.gateway.server.websocket.maxIdleTimeout`, and set the value to an appropriate positive integer. This timeout handles how long the Websocket connection remains open if there is no communication happening over the open connection. The default is one hour (3600000 milliseconds).
+6. Find or add the property `zowe.components.gateway.server.websocket.requestBufferSize` and set the value to an appropriate positive integer. This property handles the max request size allowed in WebSocket handshake requests. The default is 8K.

docs/user-guide/api-mediation/configuration-gateway-timeouts.md

@@ -3,7 +3,7 @@
 :::info Role: system programmer
 :::
 
-Use the following procedure to change the global timeout value for the API Mediation Layer instance.
+Use the following procedure to change the global timeout value for an API Mediation Layer instance.
 
 1. Open the file `zowe.yaml`.
 2. Configure the following properties:
@@ -23,4 +23,22 @@ Use the following procedure to change the global timeout value for the API Media
   * **components.gateway.ribbon.connectionManagerTimeout**  
   The HttpClient employs a special entity to manage access to HTTP connections called by the HTTP connection manager. The purpose of an HTTP connection manager is to serve as a factory for new HTTP connections, to manage the life cycle of persistent connections, and to synchronize access to persistent connections. Internally, the connections that are managed serve as proxies for real connections. `ConnectionManagerTimeout` specifies a period during which managed connections with API ML should be established. The value is in milliseconds. If omitted, the default value specified in the API ML Gateway service configuration is used.
 
-3. Restart Zowe.
+  * **components.gateway.httpclient.requestConnectionTimeout**  
+  Specifies the HTTP Client Request Connection Timeout for southbound services from the API Gateway. This setting defines the period that the API Gateway waits for a response from the southbound server before issuing a connection refused response. The value is in milliseconds. An example value of a 30 second connection timeout would be 30000. 
+
+**Example:**
+
+```yaml
+components:
+    gateway:
+       ribbon:
+           connectTimeout: 30000
+           readTimeout: 60000
+           connectionManagerTimeout: 45000
+       httpclient:
+           requestConnectionTimeout: 60000
+```
+
+3. Restart Zowe.
+
+You completed customization of Gateway timeouts.

docs/user-guide/api-mediation/configuration-health-endpoint-protection.md

@@ -0,0 +1,43 @@
+# Configuring API Gateway Health Check Protection
+
+:::info Role: system programmer
+::: 
+
+As a system programmer, you can configure the security setting for the health check endpoint of the API Gateway. This setting determines whether the health check endpoint is accessible without authentication, or alternatively requires authentication. Enabling protection for the health check endpoint can enhance the security of the API Gateway by restricting access to sensitive status information about the Gateway.
+
+Use the following procedure to set the value of the health check endpoint of the API Gateway:  
+
+1. Open the file `zowe.yaml`.
+2. Configure the following property:
+
+* `components.gateway.apiml.gateway.health.protected`  
+This property defines whether the health check endpoint is accessible with or without authentication.
+
+:::note
+The default value of this parameter is `false`. We recommend setting this parameter to `true` for production environments.
+:::
+
+**Example:**
+```yaml
+zowe:
+  components:
+    gateway:
+      apiml:
+        gateway:
+            health:
+                protected: true
+```
+
+In this example, setting `protected` to `true` protects the health check endpoint by requiring authentication. Only authenticated users can access the health check endpoint. This ensures that sensitive information about the status of the Gateway is not exposed to unauthenticated users.
+
+To allow open access to the health check endpoint, set the parameter to `false`. Setting this parameter to `false` permits access to this endpoint without authentication. In this case, anyone can access the health check endpoint and obtain information about the status of the Gateway.
+
+## Environment Recommendations
+
+When setting this parameter, we recommend applying the following values according to your environment:
+
+* **In Production Environments**  
+It is recommended to set `apiml.gateway.health.protected` to `true` to enhance security and protect sensitive information about the API Gateway's health status.
+
+* **In Development/Testing Environments**  
+ setting `apiml.gateway.health.protected` to `false` can simplify the testing process, reduce development overhead, and assist with debugging.