--- title: "Requirements and connecting to z/OS" --- # Requirements and connecting to z/OS What the Mainframe module needs on z/OS and on the workstation, connecting through z/OSMF with a Zowe profile or a connection added in the Editor, authentication, the connection status, proxies and in-house CAs. ## What you need ### On z/OS - **z/OSMF**, reachable over HTTPS from the workstation, directly or through the corporate HTTP proxy, with its z/OS jobs, data set and file, and TSO/E address space REST services. Users need access to them (the IZUUSER group, or what your site uses). - Your security product (RACF, ACF2 or Top Secret) still decides everything the host allows. The module adds no privileges. - The shop's own compile procedures (for example IGYWC or IGYWCL), and Enterprise COBOL, the binder, Db2 and CICS as the shop runs them. - Optional, for the features that use them: TSO/E with an account number and logon procedure; an OMVS segment for z/OS UNIX files; SDSF; a CICS management client interface (CMCI); Endevor Web Services; IBM z/OS Debugger with its Debug Profile Service; DBB with zAppBuild; DFSMShsm; users with OPERCMDS authority for console commands. ### On the workstation Nothing but the Editor for the z/OS side. Zowe CLI is not required; an existing Zowe team configuration is read if it is there. For the optional workstation path: GnuCOBOL 3.1 or later (`cobc`), GDB 8 or later, COBOL Check (verified with 0.2.19) with Java 8 or later. See [The workstation path](https://neuralinverse.com/docs/modules/mainframe/workstation/). ## Connect to z/OS 1. Run **Connect to z/OS** (Ctrl+Alt+Shift+Z), from the Command Palette or the empty editor. With an existing Zowe team configuration on the machine (global `~/.zowe` or `ZOWE_CLI_HOME`, the folder's project and user files, nested profiles, the base profile, `$VAR` substitution), pick its z/OSMF profile. Without one, it adds a connection; **Add z/OS Connection** does the same at any time. 2. Enter your password when it is first needed. It is asked again once after a rejection and then not again, so your user ID is not revoked. 3. The **z/OS Data Sets** view opens. The status bar shows the connection the active file uses. Both work with or without a folder. **Remove z/OS Connection** removes a connection from the z/OS Data Sets view. ### The connection in the status bar The status bar shows the connection the active file uses and warns when a password is rejected, the host does not answer, a certificate is not trusted, the proxy refuses, or the connection is refused as not secure. A `zosmvs:` or `zosuss:` resource always uses the connection its address names. Each profile keeps one kept-alive connection pool. ![A window without a folder or connection: the empty editor offers Connect to z/OS.](https://neuralinverse.com/docs-images/modules/mainframe/empty-window.webp) ![Add z/OS Connection asking for the z/OSMF host name, here an example host.](https://neuralinverse.com/docs-images/modules/mainframe/add-connection-host.webp) ### Authentication | Method | How | |---|---| | User and password | One z/OSMF session login per window session, then its token, logged in again once when it expires; Basic authentication on each request where z/OSMF returns no token | | API Mediation Layer | A Zowe profile with a `basePath` and the base profile's `tokenType: apimlAuthenticationToken` logs in to the gateway and keeps only the token, per gateway, in secret storage; it logs in again after a 401. **Log Out of API Mediation Layer** invalidates it | | Client certificate | `certFile` and `certKeyFile` in the profile; an encrypted key's passphrase is asked once | The profile's `authOrder` is honoured. Passwords and key passphrases are kept in the Editor's secret storage (the operating system's credential store) only when you choose **Remember Password** and the machine setting `neuralInverse.mainframe.security.rememberPasswords` allows it. Session tokens are never written to storage. **Forget z/OS Credentials** removes them. ![Add z/OS Connection offering user and password, an API Mediation Layer token or a client certificate.](https://neuralinverse.com/docs-images/modules/mainframe/add-connection-auth.webp) ![The password prompt for a sample user on an example host, shown when the password is first needed.](https://neuralinverse.com/docs-images/modules/mainframe/password-prompt.webp) Authentication methods and proxy types that are not supported yet are listed on [What's next](https://neuralinverse.com/docs/modules/mainframe/whats-next/). ### On a locked-down corporate desktop - **Proxy:** `http.proxy`, `HTTPS_PROXY` and `HTTP_PROXY`, the system proxy and PAC; `http.noProxy` and `NO_PROXY` with domains, ports and IPv4 CIDR; Basic or a given `Proxy-Authorization`. A 407 is explained. - **In-house CA:** `neuralInverse.mainframe.certificateAuthorities` (a machine setting) names PEM files of CAs to trust, together with the operating system's trust store and `NODE_EXTRA_CA_CERTS`. An unreadable or invalid file fails before anything is sent, naming the file. - **TLS 1.2 or later.** Plain HTTP and HTTPS without certificate verification are refused unless `neuralInverse.mainframe.security.allowInsecureConnections` is on, and the connection is then marked Not Secure. State: the transport is verified on Linux against local HTTPS servers with real TLS (in-house CA trusted, self-signed refused naming subject, issuer and fingerprint, client certificates, encrypted keys, TLS 1.1 refused). **Not yet run against z/OS or a real API Mediation Layer.** The Windows certificate store, the macOS keychain and PAC resolution (stubbed only) are not verified. ## The project file A Mainframe project is a folder with `mainframe.json` at the top, or IBM's ZAPP files, or zAppBuild's `application-conf`, read as they are. The keys, the form editor for ZAPP and zAppBuild files, and host projects without a local copy are on [Project files: mainframe.json, ZAPP and zAppBuild](https://neuralinverse.com/docs/modules/mainframe/project-files/). ## Try it without a host The workstation path runs without a z/OS connection: open a COBOL application's folder as it is, with GnuCOBOL installed (see [The workstation path](https://neuralinverse.com/docs/modules/mainframe/workstation/)). AWS's public CardDemo sample, a CICS, VSAM, Db2 and batch application, is the realistic application the module was checked on and opens as it is.