Anax v2.14 synchingdocsstaging docs

.github/workflows/pull-request-checker.yml

@@ -69,10 +69,10 @@ jobs:
             If you have addressed this issue already, refresh this page in your browser to remove this comment.
       - name: File type checker
         id: file_type_checker
-        uses: JJ/github-pr-contains-action@releases/v10
-        with:
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-          bodyContains: '\.md|\.jpg|\.gif|\.png'
+        env:
+          PR_BODY_PATTERN: '\.md|\.jpg|\.gif|\.png|\.pdf'
+        run: |
+          [[ "${{ github.event.pull_request.body }}" =~ "$PR_BODY_PATTERN" ]] || exit 1
       - name: Missing File Name Comment PR
         if: failure() && steps.file_type_checker.outcome == 'failure'
         uses: marocchino/sticky-pull-request-comment@v2

docs/appendix/zowe-glossary.md

@@ -241,7 +241,7 @@ The standard z/OS Unix directory where Zowe server component and extension confi
 
 #### Zowe instance directory (V1 only)
 
-Also known as <INSTANCE_DIR>. Contains information that is specific to a launch of Zowe. It contains configuration settings that determine how an instance of the Zowe server is started, such as ports that are used or paths to dependent Java and Node.js runtimes.
+Also known as `<INSTANCE_DIR>`. Contains information that is specific to a launch of Zowe. It contains configuration settings that determine how an instance of the Zowe server is started, such as ports that are used or paths to dependent Java and Node.js runtimes.
 
 The instance directory also contains a log directory where different microservices write trace data for diagnosis, as well as a workspace and shell scripts to start and stop Zowe.
 

docs/contribute/contributing.md

@@ -247,7 +247,7 @@ For whatever list or steps we are introducing, the word "following" should prece
 
 Examples:
 - Before a procedure, use "Follow these steps:"
-- The <component_name> supports the following use cases:
+- The `<component_name>` supports the following use cases:
 - Before you install Zowe, review the following prerequisite installation tasks:
 
 Avoid ending the sentence with "following".

docs/extend/extend-api/ReactJSUI.md

@@ -85,7 +85,7 @@ In order to build and prepare your app:
 
 2.  Create a folder for your project and a new `web` folder inside it.
 
-    - EX: /Desktop/<Your_Project_Name> and Desktop/<Your_Project_Name>/web
+    - EX: `/Desktop/<Your_Project_Name>` and `Desktop/<Your_Project_Name>/web`
 
 3.  Copy built project into `Desktop/<Your_Project_Name>/web`
     - If using the sample, copy `app.min.js` , `index.html` , `icon.png` and `css` into to `/Desktop/<Your_Project_Name>/web/`

docs/extend/extend-apiml/api-mediation-components-of-URL.md

@@ -1,37 +1,44 @@
-# Components of URL
+# Components of a URL
 
-This page provides definitions and a diagram to make sure everyone is using the same terms. These terms are often overloaded. This page tries to follow the terms used in Swagger documentation.
+This page provides definitions and a diagram to make sure everyone is using the same terms. To maintain consistency of the structure of URLs, Zowe seeks to establish standards around URLs and the elements that make up a URL. This article presents the standard terminology used in Swagger documentation.
 
 ## Definitions
 
 REST APIs have a _baseUrl_ to which the endpoint paths are appended. The base URL is defined by _scheme_, _host_, _port_ and _basePath_
 
 where:
 
-- **`baseUrl`** is an absolute URL prefix that is different for each instance of the service, or when the service is accessed via the API Gateway.
+- **`baseUrl`**  
+Specifies an absolute URL prefix that is different for each instance of the service, or when the service is accessed via the API Gateway.
 
-  The endpoint paths are relative paths that follow the documentation of the REST API.
+The endpoint paths are relative paths that follow the documentation of the REST API.
 
-- **`scheme`** is the transfer protocols used by the API. APIML supports the `http`, `https`, and WebSocket schemes - `ws` and `wss`.
+- **`scheme`**  
+Specifies the transfer protocols used by the API. API ML supports the `http`, `https`, and WebSocket schemes - `ws` and `wss`.
 
-- **`host`** is the domain name or IP address (IPv4) of the host that serves the API. It may include the port number if it is different from the scheme's default port (80 for HTTP and 443 for HTTPS). Note that this must be the host only, without a scheme or sub-paths.
+- **`host`**  
+Specifies the domain name or IP address (IPv4) of the host that serves the API. It may include the port number if it is different from the scheme's default port (80 for HTTP and 443 for HTTPS). Note that this must be the host only, without a scheme or sub-paths.
 
-- **`basePath`** is the URL prefix for all API paths, relative to the host root. It must start with a leading slash `/`. If basePath is not specified then all endpoint paths start at the host root.
+- **`basePath`**  
+Specifies the URL prefix for all API paths, relative to the host root. It must start with a leading slash `/`. If basePath is not specified then all endpoint paths start at the host root.
 
 When a service is accessed without the API Gateway then the format the `basePath` depends on the service. It can be empty or have several parts (e.g. `/fileMasterPlus/api/v1`).
 
-When a service is accessed via the API Gateway then the format of the URL is standardized in one of the following formats:
+When a service is accessed via the API Gateway, the format of the URL is standardized in one of the following formats:
 
 - Using `serviceId`, service type (`t`) and major version (`v`)
 - Using `serviceId` and service type (`t`)
 
 where:
 
-- **`serviceId`** is a unique name of the service that is set during the installation of the service.
+- **`serviceId`**  
+Specifies a unique name of the service that is set during the installation of the service.
 
-- **`t`** is the type of the service. It can be `api`, `ui`, or `ws`
+- **`t`**  
+Specifies the type of the service. It can be `api`, `ui`, or `ws`
 
-- **`v`** is the major version the REST API.
+- **`v`**  
+Specifies the major version the REST API.
 
   **Example:** `v1`, `v2`. It is optional since some existing services can have versioning in the endpoint path.
 
@@ -90,4 +97,4 @@ scheme        host          basePath    endpointPath
 
 ### Resources
 
-- <https://swagger.io/docs/specification/2-0/api-host-and-base-path/>
+- For more information, see the documentation for [swagger specifications](https://swagger.io/docs/specification/2-0/api-host-and-base-path/) in the Swagger product documentation.

docs/extend/extend-apiml/api-mediation-infinispan.md

@@ -17,8 +17,8 @@ For more information on Infinispan, see the [official Infinispan documentation](
 
 ### Infinispan replica instances
 
-Infinispan can be used with both on standalone instance and High Availability mode. In case of multiple Caching Service instances, 
-you will have to specify all the cluster nodes (members). Each Infinispan node is bound to specific Caching Service instance and runs on a different port and host, which can be configured. See the [infinispan configuration](#infinispan-configuration) to know how to configure multiple Infinispan nodes.
+Infinispan can be used with both a standalone instance and high availability mode. When using multiple Caching Service instances, 
+it is necessary to specify all of the cluster nodes (members). Each Infinispan node is bound to a specific Caching Service instance and runs on a different port and host, which can be configured. For more information about configuring multiple Infinispan modes, see the [Infinispan configuration](#infinispan-configuration). 
 
 For more information on Infinispan replication and how to configure a replica instance, see the [Infinispan Cross-site Replication](https://infinispan.org/docs/stable/titles/xsite/xsite.html) documentation.
 
@@ -34,10 +34,8 @@ Configure Infinispan as a storage solution through the Caching service by settin
 * **`zowe.components.caching-service.storage.infinispan.persistence.dataLocation`**
 
   The path where the Soft-Index store keeps its data files for the Infinispan Soft-Index Cache Store. 
-  The default value is `data`. If you run the Caching Service in HA and the instances use the same filesystem,
+  The default value is `data`. If you run the Caching Service in HA and the instances use the same filesystem, you have to specify a different value of the `CACHING_STORAGE_INFINISPAN_PERSISTENCE_DATALOCATION` property for each instance. For more information, see the [Soft-Index File Store](https://infinispan.org/blog/2014/10/31/soft-index-file-store).
 
-  you have to specify a different value of the `zowe.components.caching-service.storage.infinispan.persistence.dataLocation` property for each
-  instance. For more information, see [Soft-Index File Store](https://infinispan.org/blog/2014/10/31/soft-index-file-store).
 
 * **`zowe.components.caching-service.storage.infinispan.jgroups.port`**
 

docs/extend/extend-apiml/authentication-for-apiml-services.md

@@ -98,99 +98,21 @@ The `auth/ticket` endpoint generates a PassTicket for the user associated with a
 ## Supported authentication methods
 
 The API Mediation Layer provides multiple methods which clients can use to authenticate. When the API ML is run as part
-of Zowe, all of the following methods are enabled and supported. All methods are supported at least to some extent
-with each authentication provider. 
+of Zowe, all of the following methods are enabled and supported. All methods are supported at least to some extent with each authentication provider.
 
-### Authenticate with Username/Password
-
-The client can authenticate via Username and password. There are multiple methods which can be used to deliver  
-credentials. For more details, see the ZAAS Client documentation. 
-
-### Authenticate with Client certificate
-
-You can perform authentication with client certificates.
-
-If the keyring or a truststore contains at least one valid certificate authority (CA) other than the CA of API ML, it is possible to use the client certificates issued by this CA to authenticate to API ML. This feature is not enabled by default and must be configured.
-
-:::note
-There is a limitation with respect to ACF2 systems. If you would like to offer feedback using client
-certificate authentication, please create an issue against the api-layer repository.
-:::
-
-When providing credentials with a client certificate on the same login request, the credentials take precedence and the client certificate is ignored.
-
-#### How the Gateway resolves authentication 
-
- When sending a request to a service with a client certificate, the Gateway performs the following process to resolve authentication:
-
-* The client calls the service endpoint through API ML Gateway with the client certificate.
-* The client certificate and private key are checked as a valid TLS client certificate against the trusted CAs of the Gateway.
-* The public part of the provided client certificate is checked against SAF. SAF subsequently returns a user ID that owns this certificate. ZSS provides this API for API ML.
-* The Gateway performs the login of the mapped user and provides valid authentication to the southbound service.
-
-When sending a request to the login endpoint with a client certificate, the Gateway performs the following process to exchange the client certificate for an authentication token.
-
-* The client calls the API ML Gateway login endpoint with the client certificate.
-* The client certificate and private key are checked as a valid TLS client certificate against the trusted CAs of the Gateway.
-* The public part of the provided client certificate is checked against SAF. SAF subsequently returns a user ID that owns this certificate. ZSS provides this API for API ML. 
-* The Gateway performs the login of the mapped user and returns a valid JWT token.
-
-![Zowe client certificate authentication diagram](../../images/api-mediation/zowe-client-cert-auth.png)
-
-#### Prerequisites
-
-Ensure to satisfy the following requirements before you set up client certificate authentication:
-
-1. Specify the Zowe runtime user and set your protection by password. The user is created with the `NOPASSWORD` parameter by the Zowe installer. It is necessary to change this password. 
+Zowe supports three authentication methods with single-sign-on. Use the following links to the documentation about using the following supported authentication methods:
 
-  For RACF, issue the following TSO command:  
+* [Authenticating with a JWT token](../../user-guide/authenticating-with-jwt-token).
 
-  `ALTUSER <ZOWE_RUNTIME_USER (ZWESVUSR by default)> PASSWORD(<NEWPASSWORD>)`  
+* [Authenticating with client certificates](../../user-guide/authenticating-with-client-certificates).
 
-  For other security systems, refer to the documentation for an equivalent command.
+* [Authenticating with personal access tokens](../../user-guide/api-mediation/authenticating-with-personal-access-token).
 
-2. Verify that the Zowe runtime user is allowed to log in to z/OSMF. (Check that the user is member of the default `IZUUSER` group.)
-
-  :::note
-  Ensure that you have an external Certificate Authority and signed client certificates. Alternatively, you can generate these certificates in SAF. The client certificate must have correct `Extended Key Usage` metadata so the metadate can be used for TLS client authentication. (`OID: 1.3.6.1.5.5.7.3.2`)
-  :::
-
-#### Configure your z/OS system to support client certificate authentication
-
-1. Import the client certificates to SAF, or add them to a user profile.  
-**Examples:** `RACDCERT ADD` or `RACDCERT GENCERT`.  
-For more information, see your security system documentation.
-2. Import the external CA to the truststore or keyring of the API Mediation Layer.
-3. Configure the Gateway for client certificate authentication. Follow the procedure described in [Enabling single sign on for clients via client certificate configuration](../../user-guide/api-mediation/configuration-client-certificates).
-
-:::note**Notes:**
-* PassTicket generation must be enabled for the Zowe runtime user. The user has to be able to generate a PassTicket for itself and for the APPLID of z/OSMF. For more information, see [Configure Passticket](#authentication-with-passtickets).
-* The Zowe runtime user must be enabled to perform identity mapping in SAF. For more information, see [Additional security rights that need to be granted](../../user-guide/configure-zos-system/#configure-main-Zowe-server-use-identity-mapping).
-* ZSS has to be configured to participate in Zowe SSO. For more information, see [Configure components zss](../../appendix/zowe-yaml-configuration/#configure-component-zss).
-:::
-
-#### Validate the client certificate functionality
-
-To validate that the client certificate functionality works properly, call the login endpoint with the certificate that was setup using the steps in _Configure your z/OS system to support client certificate authentication_. 
-
-Validate using CURL, a command line utility that runs on Linux based systems:
-
-**Example:**
-```
-curl --cert /path/to/cert.pem --key /path/to/key.pem https://api-mediation-layer:7554/gateway/api/v1/login
-```
-Your Zowe instance is configured to accept x.509 client certificates authentication.
-
-
-### Authenticate with JWT Token
-
-When the client authenticates with the API ML, the client receives the JWT token in exchange. This token can be used for further authentication. If z/OSMF is configured as the authentication provider and the client already received a JWT token produced by z/OSMF, it is possible to reuse this token within API ML for authentication.  
+### Authenticate with Username/Password
 
-### Authenticate with Personal Access Token
+The client can authenticate via Username and password. There are multiple methods which can be used to deliver  
+credentials. For more details, see the ZAAS Client documentation. 
 
-A Personal Access Token (PAT) is an alternative to using passwords for authentication.
-It is possible to generate a Personal Access Token that can be used for an instance of Version Control Systems on mainframe without having to store mainframe credentials
-or use a certificate. For more information about the PAT functionality, see the [Personal Access Token documentation](../../user-guide/api-mediation/api-mediation-personal-access-token.md).
 
 ## Authentication parameters
 
@@ -303,11 +225,7 @@ Use the following property of API Gateway to enable the `Dummy Authentication Pr
 apiml.security.auth.provider: dummy
 ```
 
-## Authorization
-
-Authorization is a method used to determine access rights of an entity.
 
-In the API ML, authorization is performed by the z/OS security manager ([ACF2](https://www.broadcom.com/products/mainframe/identity-access/acf2), [IBM RACF](https://www.ibm.com/support/knowledgecenter/zosbasics/com.ibm.zos.zsecurity/zsecc_042.htm), [Top Secret](https://www.broadcom.com/products/mainframe/identity-access/top-secret)). An authentication token is used as proof of valid authentication. The authorization checks, however, are always performed by the z/OS security manager.
 ## Discovery Service authentication
 
 There are several authentication mechanisms, depending on the desired endpoint, as described by the following matrix:

docs/extend/extend-apiml/implementing-routing-to-the-api-gateway.md

@@ -0,0 +1,51 @@
+# Implementing routing to the API Gateway
+
+Service instances provide information about routing to the API Gateway via Eureka metadata.
+
+**Example:**
+
+    routes:
+        - gatewayUrl: "ui/v1"
+          serviceUrl: "/helloworld"
+        - gatewayUrl: "api/v1"
+          serviceUrl: "/helloworld/v1"
+        - gatewayUrl: "api/v2"
+          serviceUrl: "/helloworld/v2"
+
+In this example, the service has a service ID of `helloworldservice` that exposes the following endpoints:
+
+* **UI** - `https://gateway/helloworldservice/ui/v1` routed to `https://hwServiceHost:port/helloworld/`
+* **API major version 1** - `https://gateway/helloworldservice/api/v1` routed to `https://hwServiceHost:port/helloworld/v1`
+* **API major version 2** - `https://gateway/helloworldservice/api/v2` routed to `https://hwServiceHost:port/helloworld/v2`
+
+where:
+
+* The gatewayUrl is matched against the prefix of the URL path used at the Gateway `https://gateway/urlPath`, where `urlPath` is `serviceId/prefix/resourcePath`.
+* The service ID is used to find the service host and port.
+* The `serviceUrl` is used to prefix the `resourcePath` at the service host.
+
+:::note
+The service ID is not included in the routing metadata, but the service ID is in the basic Eureka metadata.
+:::
+
+### Basic Routing using only the service ID
+
+This method of routing is similar to the previous method, but does not use the version part of the URL. This approach is useful for services that handle versioning themselves with different granularity.
+
+One example that only uses a service ID is z/OSMF.
+
+**Example:**
+
+z/OSMF URL through the Gateway has the following format:
+
+ `https://gateway:10010/ibmzosmf/api/restjobs/jobs/...`
+
+where:
+
+* **`ibmzosmf`**  
+Specifies the service ID.
+
+* **`/restjobs/1.0/...`**  
+Specifies the rest of the endpoint segment.
+
+Note that no version is specified in this URL.