Merge branch 'master' into LP3157

docs/extend/extend-cli/cli-devTutorials.md

@@ -5,16 +5,30 @@ You can extend Zowe™ CLI by developing plug-ins and contributing code to t
 ## How to contribute
 You can contribute to Zowe CLI in the following ways:
 - Add new commands, options, or other improvements to the base CLI.
-- Develop a plug-in that users can install to Zowe CLI.
+- Develop a Zowe CLI plug-in.
 
 You might want to contribute to Zowe CLI to accomplish the following objectives:
-* Provide new scriptable functionality for yourself, your organization, or to a broader community.
-* Make use of Zowe CLI infrastructure (profiles and programmatic APIs).
-* Participate in the Zowe CLI community space.
+- Provide new scriptable functionality for yourself, your organization, or to a broader community.
+- Make use of Zowe CLI infrastructure (profiles and programmatic APIs).
+- Participate in the Zowe CLI community space.
 
 ## Getting started
 If you want to start working with the code immediately, review the Readme file in the [Zowe CLI core repository](https://github.com/zowe/zowe-cli#zowe-cli--) and the Zowe [contribution guidelines](https://github.com/zowe/zowe-cli/blob/master/CONTRIBUTING.md#contribution-guidelines). The [zowe-cli-sample-plugin GitHub repository](https://github.com/zowe/zowe-cli-sample-plugin#zowe-cli-sample-plug-in) is a sample plug-in that adheres to the guidelines for contributing to Zowe CLI projects.
 
+### Contribution guidelines
+The Zowe CLI contribution guidelines contain standards and conventions for developing Zowe CLI plug-ins.
+
+The guidelines contain critical information about working with the code, running/writing/maintaining automated tests, developing consistent syntax in your plug-in, and ensuring that your plug-in integrates with Zowe CLI properly:
+
+| For more information about ... | See: |
+| ------------------------------ | ----- |
+| General guidelines that apply to contributing to Zowe CLI and Plug-ins | [Contribution Guidelines](https://github.com/zowe/zowe-cli/blob/master/CONTRIBUTING.md) |
+| Conventions and best practices for creating packages and plug-ins for Zowe CLI | [Package and Plug-in Guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/PackagesAndPluginGuidelines.md)|
+| Guidelines for running tests on Zowe CLI | [Testing Guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/TESTING.md) |
+| Guidelines for running tests on the plug-ins that you build| [Plug-in Testing Guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/PluginTESTINGGuidelines.md) |
+Versioning conventions for Zowe CLI and Plug-ins| [Versioning Guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/MaintainerVersioning.md) |
+
+
 ### Tutorials
 Follow these tutorials to get started working with the sample plug-in:
 1. [Setting up:](cli-setting-up.md) Clone the project and prepare your local environment.
@@ -36,20 +50,25 @@ The following guidelines and documentation will assist you during development:
 ### Imperative CLI Framework documentation
 [Imperative CLI Framework documentation](https://github.com/zowe/imperative/wiki) is a key source of information to learn about the features of Imperative CLI Framework (the code framework that you use to build plug-ins for Zowe CLI). Refer to these supplementary documents during development to learn about specific features such as:
 
-* Auto-generated help
-* JSON responses
-* User profiles
-* Logging, progress bars, experimental commands, and more!
+- Auto-generated help
+- JSON responses
+- User profiles
+- Logging, progress bars, experimental commands, and more!
+- Authentication mechanisms
 
-### Contribution guidelines
-The Zowe CLI contribution guidelines contain standards and conventions for developing Zowe CLI plug-ins.
+### Authentication mechanisms
 
-The guidelines contain critical information about working with the code, running/writing/maintaining automated tests, developing consistent syntax in your plug-in, and ensuring that your plug-in integrates with Zowe CLI properly:
+As an extender, you can change the way Zowe CLI uses various mechanisms of authentication when communicating with the mainframe.
 
-| For more information about ... | See: |
-| ------------------------------ | ----- |
-| General guidelines that apply to contributing to Zowe CLI and Plug-ins | [Contribution Guidelines](https://github.com/zowe/zowe-cli/blob/master/CONTRIBUTING.md) |
-| Conventions and best practices for creating packages and plug-ins for Zowe CLI | [Package and Plug-in Guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/PackagesAndPluginGuidelines.md)|
-| Guidelines for running tests on Zowe CLI | [Testing Guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/TESTING.md) |
-| Guidelines for running tests on the plug-ins that you build| [Plug-in Testing Guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/PluginTESTINGGuidelines.md) |
-Versioning conventions for Zowe CLI and Plug-ins| [Versioning Guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/MaintainerVersioning.md) |
+Zowe CLI accepts various methods, or mechanisms, of authentication when communicating with the mainframe, and the method that the CLI ultimately follows is based on the service it is communicating with.
+
+However, some services can accept multiple methods of authentication. When multiple methods are provided (in a profile or command) for a service, the CLI follows an *order of precedence* to determine which method to apply. Extenders can modify this order for their plug-in.
+
+To learn the authentication methods used for different services and their order of precedence, refer to the following table:
+
+service | Zowe V1 order of precedence | Zowe V2 order of precedence
+|:--- |:--- |:--- |
+API ML | 1. username, password<br/> 2. API ML token | 1. username, password<br/> 2. API ML token<br/> 3. PEM certificate |
+Db2, <br/> FTP,<br/> most other services | username, password | username, password
+SSH | 1. SSH key<br/> 2. username, password | 1. SSH key<br/> 2. username, password
+ ZOSMF<br/> direct connection | username, password | 1. username, password<br/> 2. PEM certificate

docs/troubleshoot/cli/troubleshoot-cli-credentials.md

@@ -0,0 +1,13 @@
+# Troubleshooting Zowe CLI credentials
+
+## Secure credentials
+
+### Authentication mechanisms
+
+You can troubleshoot a failed log-in to a mainframe service by reviewing the authentication mechanisms used by Zowe CLI.
+
+Zowe CLI accepts various methods, or mechanisms, of authentication when communicating with the mainframe, and the method that the CLI ultimately follows is based on the service it is communicating with.
+
+However, some services can accept multiple methods of authentication. When multiple methods are provided (in a profile or command) for a service, the CLI follows an *order of precedence* to determine which method to apply.
+
+To find the authentication methods used for different services and their order of precedence, see the table in [Authentication mechanisms](../../extend/extend-cli/cli-devTutorials.md#authentication-mechanisms).

docs/user-guide/cli-ftpplugin.md

@@ -13,15 +13,21 @@ As a z/OS user, you can use the plug-in to perform the following tasks:
 
 ## Commands
 
-For detailed documentation on commands, actions, and options available in this plug-in, see our Web Help. It is available for download in three formats: a PDF document, an interactive online version, and a ZIP file containing the HTML for the online version.
+:::
 
-- <a href="/stable/web_help/index.html" target="_blank">Browse Online</a>
-- <a href="/stable/zowe_web_help.zip" target="_blank">Download (ZIP)</a>
-- <a href="/stable/CLIReference_Zowe.pdf" target="_blank">Download (PDF)</a>
+When transferring files, data sets, or data set members, use only ASCII characters. If a file contains non-ASCII characters (such as glyphs or mathematical symbols), a translation error can happen when the file is downloaded from, or uploaded to, the mainframe. This error can result in data loss.
+
+:::
+
+For detailed documentation on commands, actions, and options available in this plug-in, see the Web Help. It is available for download in the following formats:
+
+- <a href="/stable/web_help/index.html" target="_blank">Browse the online Web Help</a>
+- <a href="/stable/zowe_web_help.zip" target="_blank">Download the ZIP file</a>
+- <a href="/stable/CLIReference_Zowe.pdf" target="_blank">Download the PDF document</a>
 
 ## Software requirements
 
-Before you install the plug-in, meet the software requirements in [Software requirements for Zowe CLI plug-ins](cli-swreqplugins.md).
+Before you install the plug-in, meet the [Software requirements for Zowe CLI plug-ins](cli-swreqplugins.md).
 
 ## Installing
 

docs/user-guide/configure-uss.md

@@ -1,5 +1,4 @@
-<!-- omit in toc -->
-# UNIX System Services considerations for Zowe
+# Address UNIX System Services (USS) Requirements
 
 The Zowe z/OS component runtime requires USS to be configured. As shown in the [Zowe architecture](../getting-started/zowe-architecture.md), a number of servers run under UNIX System Services (USS) on z/OS. Review this topic for knowledge and considerations about USS when you install and configure Zowe.
 

docs/user-guide/systemrequirements-zos.md

@@ -32,13 +32,15 @@ Be sure your z/OS system meets the following prerequisites:
 
 ### z/OS
 
-- z/OS version is in active support, such as Version 2.3 and Version 2.4
+- z/OS version is in active support, such as Version 2.4, 2.5, and 3.1
 
-   **Note:** z/OS V2.2 reached end of support on 30 September 2020. For more information, see the z/OS v2.2 lifecycle details [https://www.ibm.com/support/lifecycle/details?q45=Z497063S01245B61](https://www.ibm.com/support/lifecycle/details?q45=Z497063S01245B61). 
+   **Note:** Zowe Version 2.11 or higher is required when using z/OS Version 3.1
 
-- zFS volume has at least 833 mb of free space for Zowe server components, their keystore, instance configuration files and logs, and third-party plug-ins.
+   **Note:** z/OS V2.3 reached end of support on 30 September 2022. For more information, see the z/OS v2.3 lifecycle details [https://www.ibm.com/support/pages/zos23x-withdrawal-notification](https://www.ibm.com/support/pages/zos23x-withdrawal-notification)
 
-- (Optional, recommended) z/OS OpenSSH V2.2.0 or later
+- zFS volume has at least 1200 mb of free space for Zowe server components, their keystore, instance configuration files and logs, and third-party plug-ins.
+
+- (Optional, recommended) z/OS OpenSSH
 
   Some features of Zowe require SSH, such as the Desktop's SSH terminal. Install and manage Zowe via SSH, as an alternative to OMVS over TN3270. 
 
@@ -48,19 +50,19 @@ Be sure your z/OS system meets the following prerequisites:
 
 ### Node.js
 
-- Node.js v14.x (except v14.17.2), or v16.x
+- Node.js v16.x or v18.x
 
   Node is not included with z/OS so must be installed separately.  To install Node.js on z/OS, follow the instructions in [Installing Node.js on z/OS](install-nodejs-zos.md).
 
-  **Note:** If you are a software vendor building extensions for Zowe, when using Node.js v14.x or later, it is highly recommended that plug-ins used are tagged. For more information, see [Tagging on z/OS](../extend/extend-desktop/mvd-buildingplugins.md#tagging-plugin-files-on-z-os).
+  **Note:** If you are a software vendor building extensions for Zowe it is highly recommended that plug-ins used are tagged. For more information, see [Tagging on z/OS](../extend/extend-desktop/mvd-buildingplugins.md#tagging-plugin-files-on-z-os).
 
 ### Java 
 
 - IBM SDK for Java Technology Edition V8
 
 ### z/OSMF (Optional) 
 
-- (Optional, recommended) IBM z/OS Management Facility (z/OSMF) Version 2.2, Version 2.3 or Version 2.4.
+- (Optional, recommended) IBM z/OS Management Facility (z/OSMF) Version 2.4, Version 2.5 or Version 3.1.
 
   z/OSMF is included with z/OS so does not need to be separately installed.  If z/OSMF is present, Zowe will detect this when it is configured and use z/OSMF for the following purposes:
 
@@ -182,12 +184,18 @@ Zowe requires ACF2 APAR LU01316 to be applied when using the ACF2 security manag
 
 ## Memory requirements
 
-Zowe API ML components have following memory requiremets:
+Zowe's components have following memory requiremets:
+
+Component name | Category | Average memory usage
+---|---|---
+Gateway service | API Mediation Layer | 512MB
+Discovery service | API Mediation Layer |  512MB
+API Catalog | API Mediation Layer |  512MB
+Metrics service | API Mediation Layer |  512MB
+Caching service | API Mediation Layer |  512MB
+ZSS | Application Framework | 32MB
+App Server | Application Framework | 350MB
+
+Each of the above components can be enabled or disabled to optimize your resource consumption according to your use cases.
+Zowe can use more memory if there are extensions installed.
 
-Component name | Memory usage
----|---
-Gateway service | 256MB
-Discovery service | 256MB
-API Catalog | 512MB
-Metrics service | 512MB
-Caching service | 512MB

docs/user-guide/ze-ftp-using-ze-ftp-ext.md

@@ -10,6 +10,12 @@ Contact your system administrator to determine if your FTP server is configured
 
 ## Using
 
+:::caution
+
+When transferring files, data sets, or data set members, use only ASCII characters. If a file contains non-ASCII characters (such as glyphs or mathematical symbols), a translation error can happen when the file is downloaded from, or uploaded to, the mainframe. This error can result in data loss.
+
+:::
+
 To use the FTP Extension with Zowe Explorer:
 
 1. Select the **Zowe Explorer** icon on the **Activity Bar** in VS Code.