Managing Zowe’s App Server (and ZSS) via its Admin API

{Core} As a new administrator of the Open Mainframer Project’s Zowe application server (and perhaps a few other components), learning directory structures and access patterns may be a bit intimidating at first. No one wants to perform file searches with grep using solely intuition-based regexp as they plunder their working directory for something remotely resembling a server log. With the new Admin APIs, log files and server parameters for both Zowe’s application server and ZSS server can be queried and updated with just a few HTTP requests.

Zowe’s application server is a Node.js server which contains REST APIs including the server administration API which was added in early October 2019. The administration API was also added to the ZSS server which provides low-level microservices to the Zowe app server. It is critical that the API can be accessed via both the app server and the ZSS server because while ZSS is not required for the app server to run, it is a component that is provided for the app server and therefore should be as easy to administer. For ease of accessibility, both APIs are shaped with a closely related structure and provide similar information regardless of host operating system (z/OS, Linux, Windows, MacOS).

The API can only be accessed by users who are RBAC (role-based access control) authorized which means “rbac” must be set to true (boolean) under “dataserviceAuthentication” in the server configuration file, as well as the ZSS configuration file. To access the server administration API, users may perform a GET request to http[s]://<Zowe App Server Host>:<Zowe App Server Port>/server which will return a HATEOAS compliant response. The /server route details all other possible links starting from that URI.

From the API, administrators will have access to information including the current server configuration including command line arguments, the contents of the log file, the verbosity level for each logger, and details about the environment which the server is being hosted within. Additionally, trace levels for component loggers and certain server config attributes may be updated via POST requests. App servers running in cluster mode will NOT need tor restart to see the updates to take effect, simply wait for the server to reload.

One caveat to note with the /server[/agent]/log endpoint is that a large log file will inherently return a large HTTP response. A log file extending 105+ lines is especially common with production environments which utilize Node.js’ clustering support, or even environments which have simply been running for an extended period (with usage). This issue can be mitigated in instances where the verbosity of the log is set beyond what is desired by the administrator, in which case the granularity can be decreased thus reducing the total log output. Other solutions include setting the verbosity of loggers by component, such that undesired information does not appear in the log file.

The /server[/agent]/environment endpoint is especially useful for parsing general system information as well as debugging user environment related issues. The information returned varies slightly between the app server and ZSS because ZSS is restricted to z/OS, thus the server may only return what information can be derived from low-level system calls and built in Metal C functions. Namely, per core CPU information and available memory are missing from the /server/agent/environment route due to hardware and environment restrictions. Information such as the running server PID/PPID, operating system information, and user environment variables are returned for administrators (or developers with administrator access) to consume in a RESTful manner.

API Doc: https://github.com/zowe/zlux-app-server/blob/staging/doc/swagger/server-plugins-api.yaml

If you enjoyed this blog checkout more Zowe blogs here. Or, ask a question and join the conversation on the Open Mainframe Project Slack Channel #Zowe-dev, #Zowe-user or #Zowe-onboarding.

Click the links to learn more about Zowe and more Zowe blogs.