How to Add a UserID to z/OS Using a Zowe Script!

Written by Daniel Jast, member of OMP’s Zowe community and zSystems Technical Specialist at IBM Worldwide Client Experience Centers

Here in Poughkeepsie at the Client Experience Center, our Z team is constantly looking for opportunities to modernize, by using new tools and technologies coming available on the platform. I am always looking for ways to leverage the Zowe platform to better manage the Z Infrastructure I supports. I provide many technical demos for Zowe, where we show off plenty of “Out of the box” functionality, as well as some extensions and scripts used in the  Zowe environment. I previously worked with my internal team and others on creating a common process to plug Jupyter Notebook web applications into the Zowe Desktop.

My team and I have now moved onto some scripting use cases, to better manage and automate tasks across their systems. One task that a Systems Programmer is required to do on a regular basis, is create UserIDs on a system, so a user can log on and get access to z/OS. Not only is this a repetitive task, but one has to know all the different system specific information, depending on which system the UserID is being added to. With help from my colleague Alex Lieberman, we created a base script for Systems Programmers to start adding z/OS UserIDs to systems. You can download and customize this script to fit your environment and can find the Github repository where this code is stored here.

 

Prerequisites: What you need set up

There are some things we are going to need to have set up on our z/OS System and on our local workstation before this script will run successfully. This section describes what to do prior to running the script. This script is written in bash, so you will need to have bash installed on your workstation.

Creating Zowe CLI Profiles

There are 3 Zowe CLI profiles needed for each system you are accessing. These 3 profiles are a z/OSMF profile, a SSH profile, and a TSO profile. To create the 3 profiles, you can use the following command syntax:

z/OSMF Profile:
zowe profiles create zosmf SYSNAME –host IPAddress –user ibmuser –pass myp4ss –reject-unauthorized false –overwrite

  • The z/OSMF Profile is used for the dataset and job API commands. These commands allow us to upload our JCL to the z/OS System, and then submit those datasets as jobs.

SSH Profile:

zowe profiles create ssh SYSNAME –host sshhost –user ibmuser –password myp4ss

  • The SSH Profile is used to issue Unix commands. We issue commands against the UserID’s home unix directory to change ownership and permissions.

TSO Profile:
zowe profiles create tso SYSNAME –account ACCOUNTnumber

  • The TSO Profile is used to issue TSO commands. We issue LISTUSER commands to verify our script is creating what we want.

Wherever you see SYSNAME in the profile creation commands, you should replace that with the name of the system(LPAR) that you are creating that profile to connect to. It is a good practice to name your profiles after the system you are connecting them too, so it is easy to differentiate between profiles.

Allocate a PDS to Store the Jobs

When looking at the script, you will notice that there are 6 different jobs that are uploaded to our z/OS and then ran. When our JCL is uploaded to z/OS, we need to put it somewhere before we run it. Therefore, allocate a JCL library where these jobs can be stored. You then need to change this value in 2 different places throughout the script.

First change the target JCL Library where you want these jobs to be stored when they are uploaded to z/OS:

zowe zos-files upload stdin-to-data-set “DANJAST.JCL(ZWEUSERX)”

Second, where the job is being stored when submitting the job:

jobid1=`zowe jobs submit data-set “DANJAST.JCL(ZWEUSER1)” –rff jobid –rft string`

Add REXX to Your System

If your organization uses SMS to manage where a UserID’s datasets should be directed, you will need a program to go into your ACS.SOURCE(STORCLAS) member to add the new UserID. Alex Lieberman has written a basic REXX script which goes into the STORCLAS member and adds a new line for the new user being added. The REXX to do so has been uploaded to the Github repo here. This REXX needs to be added to your z/OS System prior to script execution. You also need to point JOB 1 at the dataset you created for the REXX.

Change the following line of JCL in JOB 1 to point to your REXX location:

EX ‘SYSL.REXX(INACSSRC)’ ‘${username},${description}’

NOTE: You may need to edit the REXX script to fit your organization’s STORCLAS member.

Script Part 1: Set Variables
Scripting with the Zowe CLI commands is easy. Dan is a programmer with few years of experience and recognizes an opportunity for automation, which is why he writes simple bash scripts to automate z/OS tasks. The first thing we are going to want to do in any script we write leveraging Zowe CLI commands, is to set our variables. In this use case, we need to get the UserID the Systems Programmer wants to add to the z/OS System using the following code:

echo ‘What is the UserID you would like to add to z/OS? This must be less than 8 characters long.’

read username

echo The username you are creating is: $username

This takes in the user’s input for what the username will be, and loads that into the $username variable. Now throughout the rest of our script, $username will be replaced with what the user specified. This can be within Zowe commands, as well as within JCL in the script. Some of the other variables we are going to want users to specify at the beginning of the script include:
$system = What z/OS system we are adding this new UserID too

$description = Why are you adding this userid to your system? (Documentation/management purposes)

In setting the $system variable, we need to add some logic to allow for the user to specify which system is their intended target system to add the UserID too. Customize this this script to fit the environments you would like to exploit.

Script Part 2: Edit Script JCL

Throughout the script, there are 6 different jobs we are going to submit. These jobs, in their current state, have JCL that is in the syntax which the Poughkeepsie Client Experience Center uses for their JCL. Your organization may customize your JCL differently, therefore you will need to review all JCL in the script. As good practice, you can manually load these jobs into datasets and add a user. This way, you can ensure the jobs function the way you intend, and then any changes you make to the JCL you can put in your script. The purpose for the 6 different jobs submitted are as follows:

  1. JOB1: Submit a REXX program that edits the ACS.SOURCE(STORCLAS) member to add SMS logic for UserIDs
  2. JOB2: Create RACF Permissions / Work for new userid
  3. JOB3: Create the ALIAS for the UserID on the system. This is a CATALOG entry to allow dataset creation for the HLQ of the UserID
  4. JOB4: The ISPPROF dataset is needed by ISPF for each userid when using ISPF. When they logon, the logon proc will need this dataset to be active before they can successfully access ISPF.
  5. JOB5: To access OMVS (USS), the userid on PEL systems will attempt an auto-mount of a ZFS file in naming convention: ZFS.USER.<userid>.  So, when the user enters TSO ISH or TSO OMVS, auto-mount will attempt a mount with the following specifications:   mount point /u/<userid>  mounted to file OMVS.ZFS.USER.<userid>. The ZFS file is needed.  Create the ZFS file with the following batch job.  Be careful to ensure that words “aggregate” and “compat” are lower-case.
  6. JOB6: Add OMVS segment for userid. Remember the UID we got from TSO ISH?….. It was 209.  This is where that comes in to play.  We need to add an OMVS segment to the userid.  OMVS segment requires the UID.  Be careful to check the GID (group ID) with TSO ISH.  Be careful that the syntax is case-sensitive!

To access the script, please visit the following repo: https://github.com/dan-jast/zowe-cli-sample-scripts/blob/master/shell/AddUserSAMPLE.sh

Good luck scripting with the Zowe CLI! If you create complex scripts on your own to automate z/OS tasks, consider contributing those scripts back to the open source community so others can use them!

We’d love to hear about what you’re doing. Join the Zowe channels on the Open Mainframe Project Slack today!