Merge pull request #3926 from zowe/feature/network-tables

Add network tables for helping with network setup
zowe · Oct 8, 2024 · 3cb0211 · 3cb0211
2 parents 71b0ad1 + 51f8c9d
commit 3cb0211
Show file tree

Hide file tree

Showing 5 changed files with 200 additions and 64 deletions.
diff --git a/docs/user-guide/address-network-requirements.md b/docs/user-guide/address-network-requirements.md
@@ -8,18 +8,46 @@ Values presented in the table are default values. You can change the values by u
 
 For more information about variable names in the following table, see the [Zowe YAML configuration file reference](../appendix/zowe-yaml-configuration.md) in the References section.
 
+## Component Ports
+
+Most Components of Zowe are HTTPS servers. The ports of each and their default jobnames are listed below.
+The ports can be customized for each component by editing the value of `components.<component-name>.port` within the Zowe YAML file.
+Each Jobname has a default prefix of ZWE1, but that can be customized via the `zowe.job.prefix` value in the Zowe YAML file.
+
+| Port number | Category | Component | Default Jobname | Log Suffix | Purpose |
+|------|------|------|------|------|------|
+| 7552 | API Mediation Layer | api-catalog | ZWE1AC | AAC | Used to view API swagger / openAPI specifications for registered API services in the API Catalog. 
+| 7553 | API Mediation Layer | discovery | ZWE1AD | ADS | Discovery server port which dynamic API services can issue APIs to register or unregister themselves.
+| 7554 | API Mediation Layer | gateway | ZWE1AG | AGW | The northbound edge of the API Gateway used to accept client requests before routing them to registered API services.  This port must be exposed outside the z/OS network so clients (web browsers, VS Code, processes running the Zowe CLI) can reach the gateway.
+| 7555 | API Mediation Layer | caching-service | ZWE1CS | ACS | Port of the caching service that is used to share state between different Zowe instances in a high availability topology.
+| 7556 | App Framework | app-server | ZWE1DS | D | The Zowe Desktop (also known as ZLUX) port used to log in through web browsers.
+| 7557 | App Framework | zss | ZWE1SZ | SZ | Z Secure Services (ZSS) provides REST API services to ZLUX, used by the File Editor application and other ZLUX applications in the Zowe Desktop.
+| 7558 | API Mediation Layer | zaas | ZWE1AZ | AZ | 
+
+## Caching Service Infinispan ports
+
+The Caching Service will use these additional ports if enabled (`zowe.components.caching-service.enabled: true`) and set to use infinispan (the default, `zowe.components.caching-service.storage.mode: infinispan`).
+
 | Port number | zowe.yaml variable name | Purpose |
 |------|------|------|
-| 2157 | NA | The port at which the key server in Infinispan is listening. If the port is not available, the next port is probed, up to port+5. Used by the key server (server) to create an SSLServerSocket and by clients to connect to the key server.
-| 7098 | zowe.components.caching-service.storage.infinispan.jgroups.port | Bind port for the socket that is used to form an Infinispan cluster.
-| 7552 | zowe.components.api-catalog.port | Used to view API swagger / openAPI specifications for registered API services in the API Catalog. 
-| 7553 | zowe.components.discovery.port | Discovery server port which dynamic API services can issue APIs to register or unregister themselves.
-| 7554 | zowe.components.gateway.port | The northbound edge of the API Gateway used to accept client requests before routing them to registered API services.  This port must be exposed outside the z/OS network so clients (web browsers, VS Code, processes running the Zowe CLI) can reach the gateway.
-| 7555 | zowe.components.caching-service.port | Port of the caching service that is used to share state between different Zowe instances in a high availability topology.
-| 7556 | zowe.components.app-server.port | The Zowe Desktop (also known as ZLUX) port used to log in through web browsers.
-| 7557 | zowe.components.zss.port | Z Secure Services (ZSS) provides REST API services to ZLUX, used by the File Editor application and other ZLUX applications in the Zowe Desktop.
-| 7558 | zowe.components.zaas.port | 
-| N/A | zowe.components.explorer-jes | Port of the JES Explorer GUI for viewing and working with jobs in the Zowe Desktop.
-| N/A | zowe.components.explorer-mvs | Port of the MVS Explorer GUI for working with data sets in the Zowe Desktop.
-| N/A | zowe.components.explorer-uss | Port of the USS Explorer GUI for working with USS in the Zowe Desktop.
+| 7601 | zowe.components.caching-service.storage.infinispan.jgroups.keyExchange.port | The port at which the key server in Infinispan is listening. If the port is not available, the next port is probed, up to port+5. Used by the key server (server) to create an SSLServerSocket and by clients to connect to the key server.
+| 7600 | zowe.components.caching-service.storage.infinispan.jgroups.port | Bind port for the socket that is used to form an Infinispan cluster.
+
+## IP Addresses
+
+Zowe's servers by default use the TCP IP address `0.0.0.0` which assigns the servers to be available on all network interfaces available to the jobs.
+
+If this default is not desired, it is recommended to use [TCPIP port assignment statements](https://www.ibm.com/docs/en/zos/2.4.0?topic=assignments-profiletcpip-port) to restrict the IP & ports of each server by their jobnames. The jobnames of each Zowe component is derived from the property `zowe.job.prefix` and `<component-suffix>` as shown in the table prior.
+
+When `zowe.job.prefix` is "ZWE1", An example of port reservations with a fixed IP of "10.11.12.13" could be:
+
+```
+   7552 TCP ZWE1AC BIND 10.11.12.13 ; Zowe API Catalog
+   7553 TCP ZWE1AD BIND 10.11.12.13 ; Zowe Discovery
+   7554 TCP ZWE1AG BIND 10.11.12.13 ; Zowe Gateway
+   7555 TCP ZWE1CS BIND 10.11.12.13 ; Zowe Caching Service
+   7556 TCP ZWE1DS BIND 10.11.12.13 ; Zowe App Server
+   7557 TCP ZWE1SZ BIND 10.11.12.13 ; Zowe ZSS
+   7558 TCP ZWE1AZ BIND 10.11.12.13 ; Zowe ZAAS
+```
 
diff --git a/versioned_docs/version-v2.15.x/user-guide/address-network-requirements.md b/versioned_docs/version-v2.15.x/user-guide/address-network-requirements.md
@@ -8,19 +8,46 @@ Values presented in the table are default values. You can change the values by u
 
 For more information about variable names in the following table, see the [Zowe YAML configuration file reference](../appendix/zowe-yaml-configuration.md) in the References section.
 
+## Component Ports
+
+Most Components of Zowe are HTTPS servers. The ports of each and their default jobnames are listed below.
+The ports can be customized for each component by editing the value of `components.<component-name>.port` within the Zowe YAML file.
+Each Jobname has a default prefix of ZWE1, but that can be customized via the `zowe.job.prefix` value in the Zowe YAML file.
+
+| Port number | Category | Component | Default Jobname | Log Suffix | Purpose |
+|------|------|------|------|------|------|
+| 7552 | API Mediation Layer | api-catalog | ZWE1AC | AAC | Used to view API swagger / openAPI specifications for registered API services in the API Catalog. 
+| 7553 | API Mediation Layer | discovery | ZWE1AD | ADS | Discovery server port which dynamic API services can issue APIs to register or unregister themselves.
+| 7554 | API Mediation Layer | gateway | ZWE1AG | AGW | The northbound edge of the API Gateway used to accept client requests before routing them to registered API services.  This port must be exposed outside the z/OS network so clients (web browsers, VS Code, processes running the Zowe CLI) can reach the gateway.
+| 7555 | API Mediation Layer | caching-service | ZWE1CS | ACS | Port of the caching service that is used to share state between different Zowe instances in a high availability topology.
+| 7556 | App Framework | app-server | ZWE1DS | D | The Zowe Desktop (also known as ZLUX) port used to log in through web browsers.
+| 7557 | App Framework | zss | ZWE1SZ | SZ | Z Secure Services (ZSS) provides REST API services to ZLUX, used by the File Editor application and other ZLUX applications in the Zowe Desktop.
+| 7558 | | jobs-api | ZWE1EJ | EJ |Disabled by default, as it duplicates APIs found in zOSMF, and is only retained if needed by extensions.
+| 7559 | | files-api | ZWE1EF | EF | Disabled by default, as it duplicates APIs found in zOSMF, and is only retained if needed by extensions.
+
+## Caching Service Infinispan ports
+
+The Caching Service will use these additional ports if enabled (`zowe.components.caching-service.enabled: true`) and set to use infinispan (the default, `zowe.components.caching-service.storage.mode: infinispan`).
+
 | Port number | zowe.yaml variable name | Purpose |
 |------|------|------|
-| 2157 | NA | The port at which the key server in Infinispan is listening. If the port is not available, the next port is probed, up to port+5. Used by the key server (server) to create an SSLServerSocket and by clients to connect to the key server.
-| 7098 | zowe.components.caching-service.storage.infinispan.jgroups.port | Bind port for the socket that is used to form an Infinispan cluster.
-| 7552 | zowe.components.api-catalog.port | Used to view API swagger / openAPI specifications for registered API services in the API Catalog. 
-| 7553 | zowe.components.discovery.port | Discovery server port which dynamic API services can issue APIs to register or unregister themselves.
-| 7554 | zowe.components.gateway.port | The northbound edge of the API Gateway used to accept client requests before routing them to registered API services.  This port must be exposed outside the z/OS network so clients (web browsers, VS Code, processes running the Zowe CLI) can reach the gateway.
-| 7555 | zowe.components.caching-service.port | Port of the caching service that is used to share state between different Zowe instances in a high availability topology.
-| 7556 | zowe.components.app-server.port | The Zowe Desktop (also known as ZLUX) port used to log in through web browsers.
-| 7557 | zowe.components.zss.port | Z Secure Services (ZSS) provides REST API services to ZLUX, used by the File Editor application and other ZLUX applications in the Zowe Desktop.
-| 7558 | zowe.components.jobs-api.port | Port of the service that provides REST APIs to z/OS jobs used by the JES Explorer.
-| 7559 | zowe.components.files-api.port | Port of the service that provides REST APIs to MVS and USS file systems.
-| N/A | zowe.components.explorer-jes | Port of the JES Explorer GUI for viewing and working with jobs in the Zowe Desktop.
-| N/A | zowe.components.explorer-mvs | Port of the MVS Explorer GUI for working with data sets in the Zowe Desktop.
-| N/A | zowe.components.explorer-uss | Port of the USS Explorer GUI for working with USS in the Zowe Desktop.
+| 7118 | zowe.components.caching-service.storage.infinispan.jgroups.keyExchange.port | The port at which the key server in Infinispan is listening. If the port is not available, the next port is probed, up to port+5. Used by the key server (server) to create an SSLServerSocket and by clients to connect to the key server.
+| 7600 | zowe.components.caching-service.storage.infinispan.jgroups.port | Bind port for the socket that is used to form an Infinispan cluster.
+
+## IP Addresses
+
+Zowe's servers by default use the TCP IP address `0.0.0.0` which assigns the servers to be available on all network interfaces available to the jobs.
+
+If this default is not desired, it is recommended to use [TCPIP port assignment statements](https://www.ibm.com/docs/en/zos/2.4.0?topic=assignments-profiletcpip-port) to restrict the IP & ports of each server by their jobnames. The jobnames of each Zowe component is derived from the property `zowe.job.prefix` and `<component-suffix>` as shown in the table prior.
+
+When `zowe.job.prefix` is "ZWE1", An example of port reservations with a fixed IP of "10.11.12.13" could be:
+
+```
+   7552 TCP ZWE1AC BIND 10.11.12.13 ; Zowe API Catalog
+   7553 TCP ZWE1AD BIND 10.11.12.13 ; Zowe Discovery
+   7554 TCP ZWE1AG BIND 10.11.12.13 ; Zowe Gateway
+   7555 TCP ZWE1CS BIND 10.11.12.13 ; Zowe Caching Service
+   7556 TCP ZWE1DS BIND 10.11.12.13 ; Zowe App Server
+   7557 TCP ZWE1SZ BIND 10.11.12.13 ; Zowe ZSS
+```
 
diff --git a/versioned_docs/version-v2.16.x/user-guide/address-network-requirements.md b/versioned_docs/version-v2.16.x/user-guide/address-network-requirements.md
@@ -8,19 +8,46 @@ Values presented in the table are default values. You can change the values by u
 
 For more information about variable names in the following table, see the [Zowe YAML configuration file reference](../appendix/zowe-yaml-configuration.md) in the References section.
 
+## Component Ports
+
+Most Components of Zowe are HTTPS servers. The ports of each and their default jobnames are listed below.
+The ports can be customized for each component by editing the value of `components.<component-name>.port` within the Zowe YAML file.
+Each Jobname has a default prefix of ZWE1, but that can be customized via the `zowe.job.prefix` value in the Zowe YAML file.
+
+| Port number | Category | Component | Default Jobname | Log Suffix | Purpose |
+|------|------|------|------|------|------|
+| 7552 | API Mediation Layer | api-catalog | ZWE1AC | AAC | Used to view API swagger / openAPI specifications for registered API services in the API Catalog. 
+| 7553 | API Mediation Layer | discovery | ZWE1AD | ADS | Discovery server port which dynamic API services can issue APIs to register or unregister themselves.
+| 7554 | API Mediation Layer | gateway | ZWE1AG | AGW | The northbound edge of the API Gateway used to accept client requests before routing them to registered API services.  This port must be exposed outside the z/OS network so clients (web browsers, VS Code, processes running the Zowe CLI) can reach the gateway.
+| 7555 | API Mediation Layer | caching-service | ZWE1CS | ACS | Port of the caching service that is used to share state between different Zowe instances in a high availability topology.
+| 7556 | App Framework | app-server | ZWE1DS | D | The Zowe Desktop (also known as ZLUX) port used to log in through web browsers.
+| 7557 | App Framework | zss | ZWE1SZ | SZ | Z Secure Services (ZSS) provides REST API services to ZLUX, used by the File Editor application and other ZLUX applications in the Zowe Desktop.
+| 7558 | | jobs-api | ZWE1EJ | EJ |Disabled by default, as it duplicates APIs found in zOSMF, and is only retained if needed by extensions.
+| 7559 | | files-api | ZWE1EF | EF | Disabled by default, as it duplicates APIs found in zOSMF, and is only retained if needed by extensions.
+
+## Caching Service Infinispan ports
+
+The Caching Service will use these additional ports if enabled (`zowe.components.caching-service.enabled: true`) and set to use infinispan (the default, `zowe.components.caching-service.storage.mode: infinispan`).
+
 | Port number | zowe.yaml variable name | Purpose |
 |------|------|------|
-| 2157 | NA | The port at which the key server in Infinispan is listening. If the port is not available, the next port is probed, up to port+5. Used by the key server (server) to create an SSLServerSocket and by clients to connect to the key server.
-| 7098 | zowe.components.caching-service.storage.infinispan.jgroups.port | Bind port for the socket that is used to form an Infinispan cluster.
-| 7552 | zowe.components.api-catalog.port | Used to view API swagger / openAPI specifications for registered API services in the API Catalog. 
-| 7553 | zowe.components.discovery.port | Discovery server port which dynamic API services can issue APIs to register or unregister themselves.
-| 7554 | zowe.components.gateway.port | The northbound edge of the API Gateway used to accept client requests before routing them to registered API services.  This port must be exposed outside the z/OS network so clients (web browsers, VS Code, processes running the Zowe CLI) can reach the gateway.
-| 7555 | zowe.components.caching-service.port | Port of the caching service that is used to share state between different Zowe instances in a high availability topology.
-| 7556 | zowe.components.app-server.port | The Zowe Desktop (also known as ZLUX) port used to log in through web browsers.
-| 7557 | zowe.components.zss.port | Z Secure Services (ZSS) provides REST API services to ZLUX, used by the File Editor application and other ZLUX applications in the Zowe Desktop.
-| 7558 | zowe.components.jobs-api.port | Port of the service that provides REST APIs to z/OS jobs used by the JES Explorer.
-| 7559 | zowe.components.files-api.port | Port of the service that provides REST APIs to MVS and USS file systems.
-| N/A | zowe.components.explorer-jes | Port of the JES Explorer GUI for viewing and working with jobs in the Zowe Desktop.
-| N/A | zowe.components.explorer-mvs | Port of the MVS Explorer GUI for working with data sets in the Zowe Desktop.
-| N/A | zowe.components.explorer-uss | Port of the USS Explorer GUI for working with USS in the Zowe Desktop.
+| 7118 | zowe.components.caching-service.storage.infinispan.jgroups.keyExchange.port | The port at which the key server in Infinispan is listening. If the port is not available, the next port is probed, up to port+5. Used by the key server (server) to create an SSLServerSocket and by clients to connect to the key server.
+| 7600 | zowe.components.caching-service.storage.infinispan.jgroups.port | Bind port for the socket that is used to form an Infinispan cluster.
+
+## IP Addresses
+
+Zowe's servers by default use the TCP IP address `0.0.0.0` which assigns the servers to be available on all network interfaces available to the jobs.
+
+If this default is not desired, it is recommended to use [TCPIP port assignment statements](https://www.ibm.com/docs/en/zos/2.4.0?topic=assignments-profiletcpip-port) to restrict the IP & ports of each server by their jobnames. The jobnames of each Zowe component is derived from the property `zowe.job.prefix` and `<component-suffix>` as shown in the table prior.
+
+When `zowe.job.prefix` is "ZWE1", An example of port reservations with a fixed IP of "10.11.12.13" could be:
+
+```
+   7552 TCP ZWE1AC BIND 10.11.12.13 ; Zowe API Catalog
+   7553 TCP ZWE1AD BIND 10.11.12.13 ; Zowe Discovery
+   7554 TCP ZWE1AG BIND 10.11.12.13 ; Zowe Gateway
+   7555 TCP ZWE1CS BIND 10.11.12.13 ; Zowe Caching Service
+   7556 TCP ZWE1DS BIND 10.11.12.13 ; Zowe App Server
+   7557 TCP ZWE1SZ BIND 10.11.12.13 ; Zowe ZSS
+```