Automating RACF Administration with PowerShell

Automating RACF Administration with PowerShell? Yes, I’m writing this post from the past as it is 2019 and certain technologies are not in my job description anymore like Faxing Solutions and Mainframe Administration. I guess its been one of those months. Recently I needed to automate some RACF Administration tasks. Naturally I wanted to perform this with my favourite scripting tool, PowerShell.

After much searching, I couldn’t find any references to anyone doing such a thing. Of course, its 2019 so who would need to do this? Anyway, I’ve come up with a solution that works for me, so I am posting it for anyone else that needs to reluctantly go down this path.

The key components are an x3270 client that supports scripting. Scripting with an HTTP daemon provides a rudimentary interface that allows orchestration from any language that can perform a web request, but in this post I detail using PowerShell.

3270 Client

To Telnet to a z/OS Host we can use any Telnet client. But ideally we want to use one that can connect and communicate using TN3270. There are serveral 3270 clients available but one of the most feature rich and open source is x3270. The Windows console version is wc3270.

x3270 HTTP Scripting Support

The x3270 HTTP Scripting option provides the ability to send commands to the x3270 client via web requests. HTTP Rest support means we can then issue commands from anything that can make a web request. e.g PHP, Python, C# and my favourite PowerShell.

RACF Command Syntax

There are numerous sites providing documentation around RACF commands. If you haven’t had exposure to RACF or haven’t had to do it for 20 years, most of them are rather obtuse. One of the better sites summarising RACF commands is available from IBM here. It details all the common tasks you are probably looking to automate. Tasks such as User and Group administration.

Integration Overview

An overview of the integration is provided below. The remainder of this post details each of these processes.

  1. Start the wc3270 Client in NVT mode to allow simple Telnet integration. Tracing enabled for live integration communication feedback
  2. HTTP daemon enabled for a REST interface for the wc3270 Client
  3. PowerShell scripting to post commands to the HTTP daemon using Invoke-RestMethod
  4. PowerShell functions to start and stop the wc3270 client and to monitor responses to commands to the HTTP daemon and the Tracing file for wc3270 session status
  5. PowerShell script to issue login commands to z/OS RACF
  6. Issue Automation commands to the z/OS host using PowerShell
  7. Disconnect

RACF Automation

Download and install the wc3270 (Windows) client from the x3270 site here. I’m using the 64-bit Client so the installation path by default is c:\program files\wc3270

You will obviously need a RACF account to connect to z/OS that has the appropriate permissions to perform the tasks you are looking to automate. You will also need the FQDN or IP Address of the z/OS Host you are connecting to.

Start the wc3270 Client and TN3270 Session with Tracing and HTTPD

To start the wc3270 client and have it connect to your z/OS host in a mode that allows easy automation, use the command

wc3270 A:hostAddress|hostName -httpd localhost:port -trace -tracefile c:\tracefilepath

  • The hostAddress is the IP Address or DNS name of the z/OS host
  • HTTPD host and port starts the HTTP daemon. If you are running everything on the local host then 127.0.0.1 is appropriate and any free port (e.g 6001). If you are going to host the x3270 HTTPD on a host for connection from other clients then use the IP/FQDN for that host
  • TraceFile Path is the location of the tracefile where session tracing will be exported to

Sending z/OS Commands using the HTTP Daemon

A list of the actions that can be sent via the HTTP Daemon are detailed in the x3270 Scripting Guide here. The key commands are;

  • string(text to send)
    • command or text to send
  • enter
    • send CRLF to submit what has been sent
  • disconnect
    • disconnect the session. There is no LOGOFF action using the HTTP Daemon

Automating RACF Administration with PowerShell.PNG

To test the connection using HTTP we can provide the HTTPD address and port along with the query command using any web browser.

e.g. http://127.0.0.1:6001/3270/rest/stext/query()

Query zOS with Browser using x3270 HTTPD.PNG
Automating RACF Administration with PowerShell

Success. We have connectivity from a Browser to the HTTP daemon to the wc3270 client to z/OS and back again.

How about providing login information that it is requesting? Below shows sending the text myUserID using

http://127.0.0.1:6001/3270/rest/stext/string(myuserID)

Sending commands to zOS using HTTP Daemon.PNG
Sending commands to zOS using HTTP Daemon

You will need to follow that up with ENTER to get the Password Prompt, submit your password and then Enter again and you will be logged on to your Mainframe. e.g

http://127.0.0.1:6001/3270/rest/stext/enter
http://127.0.0.1:6001/3270/rest/string(myPassword)
http://127.0.0.1:6001/3270/rest/stext/enter

Logged in to zOS via REST and HTTP using a web browser.PNG
Logged in to zOS via REST and HTTP using a web browser

End wc3270 Client and Session

To end the session, issue the Disconnect command.

http://127.0.0.1:6001/3270/rest/stext/disconnect

Disconnect from zOS via HTTP.PNG
Disconnect from zOS via HTTP

Using PowerShell to automate z/OS Tasks

Now that we have the fundamentals in place lets automate this.

Here is an example PowerShell script to connect and list all users. There are a couple of functions that automate the tasks of;

  • starting and stopping the wc3270 client
  • monitor the TraceLog during a Wait for Processing loop

and then the process of logging on and executing a command (Search CLASS (User)).

Update the beginning of the script with the details of your environment along with UserID and Password.

Summary

So, there you have it. Automating RACF Administration with PowerShell thanks to the x3270 Client along with the HTTP Daemon that allows us to utilise our favourite scripting tool to automate tasks on z/OS. Happy Mainframe scripting.