Binary Stars and z/OSMF

 I've been thinking of the term "binary stars" a lot recently.  The definition of a "binary star" is: 

  a system of two stars in which one star revolves around the other or both revolve around a common center.

Why would I be thinking of this?  Well, because I've been thinking a lot about a "new" z/OSMF secondary server.  I say "new" as likely many customers wouldn't have yet set it up.  The new "binary star" z/OSMF secondary server is for serving the z/OS Data Gatherer REST APIs. 

• Why would you want to use these new REST APIs?  Well, there are several use cases which depend on them.  Notably SMF Explorer.

Let's take a step back, to understand this z/OSMF secondary server more...

As you likely know, in z/OS V2.5, we restructured RMF extensively.  It was a major packaging change, with the one priced feature (RMF), turning into a base element (entitled with the z/OS base, Data Gatherer), and two priced features (RMF and the new Advanced Data Gatherer).  For this blog I'd like to concentrate on the z/OS base element portion, Data Gatherer, and its newer REST APIs.  

In z/OS V2.5 APAR OA64270, Data Gatherer added support for serving REST APIs and being able to look at SMF type 30 records. Part of this new support introduced this z/OSMF secondary server.  Now, the biggest question that we need to understand, is why is there *another* z/OSMF Server, when you've already got a z/OSMF server set up (likely, to do installation of z/OS)?  

Technically, the functions that Data Gatherer needed to support required a different set of open source packages* than the existing z/OSMF server did.  Because those open source packages were not able to coexist within the same server, a secondary server had to be created.  In addition, having a separate z/OSMF server that is responsible for the Data Gatherer REST API makes sense if you wanted to isolate programs needing these REST APIs (like heavy automation) from users interacting with the z/OSMF graphical user interface.  

However, just because there is a secondary z/OSMF server doesn't mean that you have to redo all your security definitions, thank goodness!  Admittedly, getting the security definitions set up for the first z/OSMF is the hardest part.  Luckily you can run under the same started task userid (IZUSVR, likely, if used our default security statements). And, the good news is that the z/OSMF secondary server can also share the same z/OSMF Angel (IZUANG1, likely, if you used our defaults), which makes it also easier. For that reason, running your primary and secondary z/OSMF servers on the same system is a good idea.  

If you've got the security work done already, what else do you need to do to get the z/OSMF secondary server up and running?  Actually, it's not that much and it's documented officially here.  Let's look at those steps now:

1. You'll need a new z/OSMF repository for this secondary server, so use the provided SYS1.SAMPLIB(IZUMKFS) job to define a new ZFS, mount it, and change some permissions and ownership to the userid which will be used for the secondary server started task (IZUSVR, likely). Of course, pick a different mount point than the one you have for your primary server.  For instance, on our system we are using /global/zosmf for the primary server, and /global/zosmf_dg for the secondary server ("dg" means Data Gatherer, of course!). 
2. Prepare a new parmlib member for your z/OSMF secondary server.  If you use IZUPRM00 for your primary z/OSMF server, copy it into another parmlib member (maybe, IZUPRMDG?).  You can use almost all the same values you had in your z/OSMF primary server. For your z/OSMF secondary server, you need to make the following changes:
• you must select a different HTTP_SSL_PORT, 
• you need to provide a different SERVER_PROC name (perhaps IZUSVRD?).   You can use the same HOSTNAME and ANGEL_PROC as your primary server. 
• you should remove all the PLUGINS(....), as this z/OSMF secondary server won't be using those plug-ins.   
3. Set up your z/OSMF secondary server proc (perhaps, IZUSVRD).  You can take the sample from your PROCLIB shipped with z/OS, IZUSVR1. In your new secondary proc:
• change the USERDIR= to your mountpoint for the z/OSMF secondary server's repository, for instance, /global/zosmf_dg
• change the IZUPRM= to your created new parmlib member (perhaps, IZUPRMDG).
• change the type of server to SERVER='STANDALONE'.  You do not want this z/OSMF server to be part of the same autostart group as your primary server. After all, they have different purposes. 
4. Start the new z/OSMF secondary server. For instance, you might start it with:  S IZUSVRD 
• An aside:  I don't want to confuse folks, so I'll just mention this once...instead of creating a new secondary server proc, you could use your existing one and then just use a different start command of S IZUSVR1 JOBNAME=<jobname>,IZUPRM=<parmlib suffix>,USERDIR=<user directory>, SERVER=STANDALONE)
5.  Logon to the new z/OSMF secondary server, remember to point to the right port! You'd point your browser to something like this:  https://hostname:port/zosmf/.
6.  Enable the z/OS Data Gatherer SMF REST services by following these steps:
• open the z/OSMF General Settings task.
• enable z/OS Data Gatherer SMF REST services that are listed under Optional Services.
• stop and then restart the z/OSMF secondary server.
7. Important to note!  On your *primary* z/OSMF server, do *NOT* enable the z/OS Data Gatherer SMF REST services that are found under Optional Services.  If you do that, you will disable all the plug-ins you are using on the primary server.  Remember, the entire point of having this z/OSMF secondary server, is that the Data Gatherer REST APIs are on a *different* server than  your normal plug-ins.
• If you forget, and try to enable the z/OS Data Gatherer SMF REST services on your primary server, you will see a stern warning.
8. At this the point there actually is a small amount of security work to uniquely do, to use the Data Gatherer REST APIs.  That information is found here. In short, it's:
• for SMF REST services, enable the z/OSMF server's userid to perform authorization checks for resources in the DATASET class
• for Monitor II and Monitor III REST services, setting up FACILITY class profiles.
9. To verify that everything was set up, use the Swagger interface to invoke the Data Gatherer REST APIs, and make sure you have the correct responses.  Details are here.

From this article, I hope you've learned that there are some great new modern interfaces to the data that Data Gatherer gathers!   The set up time, I feel, will be outweighed by the new enhanced functions which are very versatile.  Now...off to the stars!

----------------

*What is an open source package?* 

An open source package is a collection of code, often organized into libraries or frameworks, that is made available to the public under an open source license.