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.
- Start the wc3270 Client in NVT mode to allow simple Telnet integration. Tracing enabled for live integration communication feedback
- HTTP daemon enabled for a REST interface for the wc3270 Client
- PowerShell scripting to post commands to the HTTP daemon using Invoke-RestMethod
- 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
- PowerShell script to issue login commands to z/OS RACF
- Issue Automation commands to the z/OS host using PowerShell
- 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
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()
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
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
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
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.