Merge branch 'master' into apiml/pr21b138c6fa3e49bfe815dc3e6540585ee4…

…b810ca08216c5b9f11d7e9a8911154/changed_errors

.github/workflows/build-docs.yml

@@ -30,7 +30,11 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
         with:
-          fetch-depth: 0
+          # Fetches all commit history for a single branch. We need commit
+          # history for accurate "last updated" dates on each page, but fetch
+          # depth of 0 would fetch all branches which is slow.
+          # https://github.com/actions/checkout/issues/520#issuecomment-1320838255
+          fetch-depth: 2147483647
 
       - name: Use Node.js LTS
         uses: actions/setup-node@v3
@@ -43,7 +47,7 @@ jobs:
         env:
           TAR_OPTIONS: "--remove-files"
         with:
-          path: node_modules/.cache/webpack
+          path: node_modules/.cache/rspack
           key: cache-webpack-${{ github.base_ref || github.ref_name }}
 
       - name: Install Dependencies

docs/user-guide/authenticating-with-client-certificates.md

@@ -3,17 +3,18 @@
 :::info Required roles: system administrator, security administrator
 :::
 
-Authentication for integration with API Mediation Layer (API ML) can also be performed by the client when the service endpoint is called through 
+Authentication for integration with API Mediation Layer (API ML) can also be performed by the client when the service endpoint is called through
 the API ML Gateway with client certificates. This method of authentication requires client certification to be enabled and configured. For details about this configuration, see [Enabling single sign on for clients via client certificate configuration](./api-mediation/configuration-client-certificates.md).
 
 :::note Notes:
+
 * When calling the login endpoint with basic authentication credentials, as well as with client certificate, the basic 
-  authentication credentials take precedence and the client certificate is ignored. 
+  authentication credentials take precedence and the client certificate is ignored.
 
 * If you are calling a specific endpoint on one of the onboarded services, API Mediation Layer ignores Basic authentication. In this case, the Basic authentication is not part of the authenticated request.
 :::
 
-## How the Gateway resolves authentication 
+## 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:
 
@@ -30,36 +31,54 @@ When sending a request to the login endpoint with a client certificate, the Gate
 4. The Gateway then performs the login of the mapped user and returns a valid JWT token.
 
 :::note Notes:
+
 * As of Zowe release 3.0.0, the Internal API ML Mapper is the default API that provides this mapping between the public part of the client certificate and SAF user ID. Alternatively, you can use Z Secure Services (ZSS) to provide this API for API ML, with the noted exception when using ACF2, although we recommend using the internal API ML mapper.
 * For information about ZSS, see the section Zowe runtime in the [Zowe server-side installation overview](./install-zos.md).
 :::
 
-The following diagram shows how routing works with ZSS, in the case where the ZSS API is used for the identity mapping. 
+The following diagram shows how routing works with ZSS, in the case where the ZSS API is used for the identity mapping.
 
 ![Zowe client certificate authentication diagram](../images/api-mediation/zowe-client-cert-auth.png)
 
 :::tip
 For more information, see the Medium blog post [Zowe client certificate authentication](https://medium.com/zowe/zowe-client-certificate-authentication-5f1c7d4d579).
 :::
 
-## Configure your z/OS system to support client certificate authentication for a specific user
+## Configure your z/OS system to support client certificate authentication for specific users
+
+Register the client certificate with the user IDs in your ESM.
+
+The following commands show options for both the internal API ML mapper and ZSS.
+
+:::note
 
-Register the client certificate with the user ID in your ESM. The following commands apply to both the internal API ML mapper and ZSS.
+If using the internal API ML mapper (default from Zowe v3) and the MAP / CERTMAP option with distinguished name filters, use the `CHCKCERT` or equivalent command on the certificate to use the same order and format of the certificate's distinguished name as displayed.
+:::
 
-**RACF** 
+**RACF**
 <details>
-<summary>Click here for an example command in RACF. </summary> 
+<summary>Click here for an example command in RACF. </summary>
 
-  ``` 
-  RACDCERT ADD(<dataset>) ID(<userid>) WITHLABEL('<label>') TRUST
-  SETROPTS RACLIST(DIGTCERT, DIGTRING) REFRESH
+  Activate the `DIGTNMAP` class:
+
+  ```racf
+  SETROPTS CLASSACT(DIGTNMAP) RACLIST(DIGTNMAP)
   ```
-Alternatively, if you are using the internal API ML mapper, use the following command:
 
-  ```
+  Create the mapping for the user and a distinguished name filter:
+
+  ```racf
   RACDCERT ID(<userid>) MAP 
   SDNFILTER('<subject's-distinguished-name-filter>')
   WITHLABEL('<label>')
+  SETROPTS RACLIST(DIGTMAP) REFRESH
+  ```
+
+  Alternatively, if you disabled the internal API ML mapper, use the following command to add the certificate to an ACID:
+
+  ```racf
+  RACDCERT ADD(<dataset>) ID(<userid>) WITHLABEL('<label>') TRUST
+  SETROPTS RACLIST(DIGTCERT, DIGTRING) REFRESH
   ```
 
 </details>
@@ -69,59 +88,78 @@ Alternatively, if you are using the internal API ML mapper, use the following co
 <details>
 <summary>Click here for an example command in ACF2. </summary>  
 
-  `INSERT <userid>.<certname> DSNAME('<dataset>') LABEL(<label>) TRUST`
+  Create the mapping for the user and a distinguished name filter:
 
-Alternatively, if you are using the internal API ML mapper, use the following command:
-
-  ```
+  ```acf2
   CERTMAP.<recid>     
   SDNFILTR(<subject's-distinguished-name-filter>)
   LABEL(<label>)
   USERID(<userid>)
   TRUST
   ```
 
-</details>
-
+  Alternatively, if you disabled the internal API ML mapper, use the following command to add the certificate to an ACID
 
-**Top Secret** 
+  ```acf2
+  INSERT <userid>.<certname> DSNAME('<dataset>') LABEL(<label>) TRUST
+  ```
 
-<details>
-<summary>Click here for an example command in Top Secret. </summary> 
+</details>
 
-  `TSS ADDTO(<userid>) DIGICERT(<certname>) LABLCERT('<label>') DCDSN('<dataset>') TRUST`
+**Top Secret**
 
-Alternatively, if you are using the internal API ML mapper, use the following command:
+<details>
+<summary>Click here for an example command in Top Secret. </summary>
 
-  ```
+  Create the mapping for the user and a distinguished name filter:
+
+  ```tss
   TSS ADDT0(<userid>) CERTMAP(<recid>)
   SDNFILTR('<subject's-distinguished-name-filter>')
   USERID(<userid>)
   TRUST
   ```
-</details>
 
+  Alternatively, if you disabled the internal API ML mapper, use the following command to add the certificate to an ACID:
+
+  ```tss
+  TSS ADDTO(<userid>) DIGICERT(<certname>) LABLCERT('<label>') DCDSN('<dataset>') TRUST
+  ```
+
+</details>
 
 Additional details are likely described in your security system documentation.
 
 :::note Notes
+
 * The alternative ESM map commands allow mapping a certificate to a user without adding the X.509 certificate to the ESM database. While this approach is more convenient, it could be considered less secure than adding the certificate to the ACID, which offers better control and protection.
 * Ensure that you have the Issuer certificate imported in the truststore or in the SAF keyring. Alternatively, you can generate these certificates in SAF.
 * Ensure that the client certificate has the following `Extended Key Usage` metadata:  
 `OID: 1.3.6.1.5.5.7.3.2`  
 This metadata can be used for TLS client authentication.
 :::
 
-
 ## Validate the client certificate functionality
 
-To validate that the client certificate functionality works properly, call the login endpoint with the certificate that was set up using the steps in [Configure your z/OS system to support client certificate authentication for a specific user](#configure-your-zos-system-to-support-client-certificate-authentication-for-a-specific-user) described previously in this article. 
+To validate that the client certificate functionality works properly, call the login endpoint with the certificate that was set up using the steps in [Configure your z/OS system to support client certificate authentication for a specific user](#configure-your-zos-system-to-support-client-certificate-authentication-for-specific-users) described previously in this article.
 
 Validate using _CURL_, a command line utility that runs on Linux based systems:
 
 **Example:**
+
+```bash
+curl -X POST \
+--cert /path/to/cert.pem \
+--key /path/to/key.pem \
+https://api-mediation-layer:7554/gateway/api/v1/auth/login -v
 ```
-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.
 
+Where:
+
+* `cert`: Specifies the certificate location
+* `key`: Path to the private key
+* `7554`: Replace with the configured API Gateway port in the intance
+
+x.509 Client Certificate authentication is correctly configured if the result of the request is HTTP 200 with an `apimlAuthenticationToken` cookie generated.
+
+Your Zowe instance is configured to accept x.509 client certificates authentication.

docs/user-guide/cli-configuringcli-ev.md

@@ -74,3 +74,13 @@ Use the `--show-inputs-only` option in a Zowe CLI command to view the property v
 | Environment variable | Description | Values | Default |
 | ---------------------- | ----------- |------- | ------- |
 | `ZOWE_SHOW_SECURE_ARGS`        | Displays secure property values used by a Zowe CLI command            | `TRUE`, `FALSE` | `FALSE` |
+
+## Using Zowe CLI with a proxy
+
+If your network configuration requires communication with the mainframe to be performed through a proxy server, set environment variables to route Zowe CLI traffic through an HTTP/HTTPS proxy.
+
+| Environment Variable         | Description   |   Example Value |
+| - | - | - |
+| `HTTPS_PROXY`, `https_proxy` | Use an `https` proxy to route communication to the mainframe when your proxy server supports `https`.               | If authentication required: <br/> `https://[user]:[password]@[address]:[port]` <br/> If authentication not required:<br/> `https://[address]:[port]` |
+| `HTTP_PROXY`, `http_proxy`   | Use an `http` proxy to route communication to the mainframe when your proxy server does not support `https`.                                                        | If authentication required: <br/>`http://[user]:[password]@[address]:[port]` <br/> If authentication not required:<br/> `http://[address]:[port]`|
+| `NO_PROXY`                   | Set a list of host addresses (separated by commas) to connect to the specified hosts without going through a proxy.| `https://[address_1],https://[address_2]`, `http://[address_1],http://[address_2]`, `*.address_1,*.address_2` |

docs/user-guide/cli-db2plugin.md

@@ -4,6 +4,10 @@ The IBM® Db2® Database Plug-in for Zowe™ CLI lets you interact with Db2
 
 Zowe CLI Plug-in for IBM Db2 Database lets you execute SQL statements against a Db2 region, export a Db2 table, and call a stored procedure. The plug-in also exposes its API so that the plug-in can be used directly in other products.
 
+:::note
+Although Node.js is required to run Zowe CLI, Node.js V22.0 is not yet supported for this plug-in.
+:::
+
 ## Use cases
 
 As an application developer, you can use Zowe CLI Plug-in for IBM Db2 Database to perform the following tasks:

docs/user-guide/cli-swreqplugins.md

@@ -7,8 +7,8 @@ Before installing a Zowe™ CLI plug-in, meet the software requirements to r
 
 | Plug-in | Requirements |
 | --- | --- |
-| [IBM CICS Plug-in for Zowe CLI](cli-cicsplugin.md) | <ul><li>Ensure that [IBM CICS Transaction Server v5.2 or later](https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.2.0/com.ibm.cics.ts.home.doc/welcomePage/welcomePage.html) is installed and running in your mainframe environment</li><li>[IBM CICS Management Client Interface (CMCI)](https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.2.0/com.ibm.cics.ts.clientapi.doc/topics/clientapi_overview.html) is configured and running in your CICS region.</li></ul> |
-| [IBM Db2 Database Plug-in for Zowe CLI](cli-db2plugin.md) | <ul> <li>[Download and prepare the ODBC driver](../user-guide/cli-db2plugin.md#downloading-the-odbc-driver) (required for only package installations) and address the licensing requirements. _Perform this task before you install the plug-in_.</li><li>**(MacOS)** Download and Install [Xcode](https://developer.apple.com/xcode/resources/).</li> </ul>|  [z/OS FTP Plug-in for Zowe CLI](cli-ftpplugin.md) | <ul> <li>Ensure that z/OS FTP service is enabled and configured with `JESINTERFACELEVEL` = 2.</li> <li>FTP over SSL is recommended.</li>   </ul> |
+| [IBM CICS Plug-in for Zowe CLI](cli-cicsplugin.md) | <ul><li>Ensure that [IBM CICS Transaction Server v5.2 or later](https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.2.0/com.ibm.cics.ts.home.doc/welcomePage/welcomePage.html) is installed and running in your mainframe environment.</li><li>[IBM CICS Management Client Interface (CMCI)](https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.2.0/com.ibm.cics.ts.clientapi.doc/topics/clientapi_overview.html) is configured and running in your CICS region.</li></ul> |
+| [IBM Db2 Database Plug-in for Zowe CLI](cli-db2plugin.md) | <ul> <li>[Download and prepare the ODBC driver](../user-guide/cli-db2plugin.md#downloading-the-odbc-driver) (required for only package installations) and address the licensing requirements. _Perform this task before you install the plug-in_.</li><li>**(MacOS)** Download and Install [Xcode](https://developer.apple.com/xcode/resources/).</li><li>**Note**: Node.js V22.0 is not yet supported.</li> </ul>|  [z/OS FTP Plug-in for Zowe CLI](cli-ftpplugin.md) | <ul> <li>Ensure that z/OS FTP service is enabled and configured with `JESINTERFACELEVEL` = 2.</li> <li>FTP over SSL is recommended.</li>   </ul> |
 | [IBM z/OS FTP Plug-in for Zowe CLI](cli-ftpplugin.md) | <ul> <li>Ensure that z/OS FTP service is enabled and configured with `JESINTERFACELEVEL` = 2.</li> <li>FTP over SSL is recommended.</li> </ul> |
 | [IBM MQ Plug-in for Zowe CLI](cli-mqplugin.md) | <ul><li>Ensure that [IBM® MQ™ v9.1.0](https://www.ibm.com/support/knowledgecenter/en/SSFKSJ_9.1.0/com.ibm.mq.pro.doc/q121910_.htm) or later is installed and running in your mainframe environment. Please read this blog for more information: [Exposing the MQ REST API via the Zowe API Mediation Layer](https://developer.ibm.com/messaging/2019/05/17/exposing-the-mq-rest-api-via-the-zowe-api-mediation-layer/) </li></ul>|
 | [Visual Studio Code Extension for Zowe](../user-guide/ze-install.md) | <ul><li>Node.js V8.0 or later</li><li>Access to z/OSMF; at least one profile is configured</li><li>Configure TSO/E address space services, z/OS data set, file REST interface, and z/OS jobs REST interface. For more information, see [z/OS Requirements](../user-guide/systemrequirements-zosmf.md).</li></ul>|

docs/user-guide/cli-using-formatting-environment-variables.md

@@ -19,4 +19,3 @@ The following table provides examples of CLI options and the corresponding envir
 | `--user`                | `ZOWE_OPT_USER`                | Define your mainframe username to an environment variable to avoid specifying it on all commands or profiles.                           |
 | `--reject-unauthorized` | `ZOWE_OPT_REJECT_UNAUTHORIZED` | Define a value of `true` to the `--reject-unauthorized` flag when you always require the flag and do not want to specify it on all commands or profiles. |
 | `--editor`              | `ZOWE_OPT_EDITOR`              | Define an editor that Zowe CLI uses to open files. The value can be either the editor's executable file location or the name of a program (for example, *notepad* on Windows or *nano* on Linux).|
-

docs/user-guide/cli-using-using-environment-variables.md

@@ -53,4 +53,4 @@ pipeline {
 }
 ```
 
-For more information on Jenkins credential storage, see [Using credentials](https://www.jenkins.io/doc/book/using/using-credentials/) and Using a [Jenkinsfile](https://www.jenkins.io/doc/book/pipeline/jenkinsfile/#for-secret-text-usernames-and-passwords-and-secret-files).
+For more information on Jenkins credential storage, see [Using credentials](https://www.jenkins.io/doc/book/using/using-credentials/) and Using a [Jenkinsfile](https://www.jenkins.io/doc/book/pipeline/jenkinsfile/#for-secret-text-usernames-and-passwords-and-secret-files).

docs/whats-new/zowe-v3-migration.md

@@ -1,6 +1,6 @@
-# Migrating from Zowe V2 to Zowe V3
+# Migrating from Zowe Vx to Zowe V3
 
-Follow the procedure outlined in this article to migrate from Zowe v2 to Zowe v3. While the migration process is similar to a Zowe v2 minor release upgrade, there are several new and updated configuration parameters to consider. The workspace directory should be re-created only if you are using the app-server component.
+Follow the procedure outlined in this article to migrate from Zowe v2 to Zowe v3, or Zowe v1 to Zowe v3. While the migration process is similar to a Zowe v2 minor release upgrade, there are several new and updated configuration parameters to consider. The workspace directory should be re-created only if you are using the app-server component.
 Follow the steps described in this article to ensure a smooth migration.
 
 

docusaurus.config.js

@@ -3,8 +3,7 @@ const versionsArray = require("./versions.json");
 
 module.exports = {
   title: "Zowe Docs",
-  tagline:
-    "Combining the past and the present to build the future of Mainframe",
+  tagline: "Combining the past and the present to build the future of Mainframe",
   url: "https://docs.zowe.org/",
   baseUrl: "/",
   onBrokenLinks: "warn",
@@ -18,18 +17,12 @@ module.exports = {
       comments: true
     }
   },
-  webpack: {
-    jsLoader: (isServer) => ({
-      loader: require.resolve("esbuild-loader"),
-      options: {
-        loader: "tsx",
-        format: isServer ? "cjs" : undefined,
-        target: isServer ? "node12" : "es2017",
-      },
-    }),
+  future: {
+    // https://docusaurus.io/blog/releases/3.6#docusaurus-faster
+    experimental_faster: process.env.NODE_ENV === "production",
   },
   themeConfig: {
-        docs: {
+    docs: {
       sidebar: {
         hideable: true
       }