Having an emulated mainframe environment is a fun side project, however if you want to allow for other systems to interact with it, you’ll need to enable HTTPD for easy REST/FTP access. If you followed my previous blog post, you’ll see that I set everything up to be automated via systemd. Which is great! However, it accidentally covers up important functionality such as direct access to the MVS operator console. So I had to do a few things to get everything how I want.

Update Ansible Playbooks#

My first task was to go into my Ansible playbook and do a few things:

  1. Create automated backups of my DASD for every time I do a fresh install of TK5. This is more of a best practice for me to make sure I don’t lose anything important when I actually start doing work on the instance.
  2. Use tmux to start the MVS program rather starting it directly. This way I can start the program in the background but still attach to the active tmux session. Shout out to Claude for this tip!

Why tmux?#

For those who are unfamiliar, tmux is a terminal multiplexor. That means that you can do a lot of interesting quality of life operations as a developer from a single terminal instance. You may want to have multiple panes open/tabs/sessions for different projects or more. It can also allow for you to “detach” from a session so that you can do something else. This is where tmux can really shine for our use case. By modifying the systemd profile to ExecStart with TMUX, we can now switch to our mvs user and attach to it’s tmux session so that we can access the MVS operator console. This will allow for us to easily issue commands that any admin will need such as start/stop/display/etc without needing a TSO session.

Connecting to the Hercules Console#

I can now use the mvs user’s tmux session with the following command: sudo -u mvs tmux a -t tk5. Once I’m done, I can use Ctrl-B D to detach and go do other administrative tasks.

What is HTTPD?#

In simple terms, it’s just an HTTP and FTP server that defaults to port 8080 on TK5. The main reason I require HTTPD in my MVS server is so that when I develop other services in the hybrid cloud environment, I need an easy/common method for them to communicate with each other.

For an in-depth look of how you can use HTTPD and how to run a game directly on the MVS server, I found thisYouTube video from moshix. The url would typically look like this: http://<IP address/domain name>:8080/. There you can find information about HTTPD documentation.

For those familiar with modern mainframe tools like z/OSMF or Zowe, you’ll recognize this pattern of being able to view jobs via a web portal. You can go to the URL http://<IP address/domain name>:8080/jesst.html to check out jobs on the system that map out to the outlist 3.8 panel. Which I personally think is cool!

You can also issue jobs or BREXX (which is the open source version of REXX) scripts remotely via HTTPD which will be very important for any hybrid cloud communication once I get to that part. I’ll cover that later on.

Starting HTTPD#

With the groundwork laid, let’s look at actually getting HTTPD running—both manually and automatically.

Starting via MVS Operator Console#

You can issue the operator command /S HTTPD from the MVS operator console to start the service. It should spew quite a few messages but once you see that it’s listening, the server started successfully. Here are some example logs:

/ 9.05.38 STC  116  HTTPD420I MQTT mqtt.start not enabled in config
/ 9.05.38 STC  116  HTTPD025I Time zone offset set to GMT -05:00:00
/ 9.05.38 STC  116  HTTPD048I Login not required for any request
/ 9.05.38 STC  116  HTTPD046I Disk#0 File System on DD UFSDISK1 READ/WRITE
/ 9.05.41 STC  116  HTTPD032I Listening for HTTP request on port 8080
/ 9.05.43 STC  116  FTPD0005I Listening for FTP  request on port 8021
/ 9.05.43 STC  116  HTTPD415I Loading stats from HTTPD.STATS
/ 9.05.44 STC  116  HTTPD001I Server is READY
/ 9.05.44 STC  116  HTTPD061I STARTING socket thread

Starting via System Automation#

Unlike modern z/OS with sophisticated automation frameworks, MVS 3.8j uses BSPPILOT—essentially a scripted operator that reads commands from PARMLIB at startup. No dynamic policies, just sequential execution. In order to leverage it to automatically start HTTPD on IPL, we can do the following:

  • Navigate to DSLIST utility on panel 3.4
  • Open the dataset SYS1.PARMLIB and edit either the member STARTSTD or STARTMIN.
    • You may want to run in the minimal config if you’re running on constrained hardware resources. For example, right now I’m running MVS on my Raspberry Pi 2b which doesn’t have a lot of oomph to it. So I needed to set the environment variable REP101A which omits some functions from standard MVS 3.8J so that it starts up more quickly. Because of this, I need to add a line near the end of STARTMIN.
  • Add CMD S HTTPD near the end of the file. I chose right above the last line that sends a message saying the startup completed successfully.

Stopping HTTPD#

You can stop HTTPD with purge like normal SDSF type operations. Issue a /P HTTPD from the MVS operator console. You’ll then see messages like this follow:

/P HTTPD
/ 9.02.43 STC  102  HTTPD100I CONS(3) START
/ 9.02.43 STC  102  HTTPD100I CONS(3) STOP
/ 9.02.43 STC  102  HTTPD002I Server is QUIESCE
/ 9.02.43 STC  102  HTTPD060I SHUTDOWN socket thread    TCB(99EAB8) TASK(1C6FC8) STACKSIZE(32768)
/ 9.02.44 STC  102  HTTPD060I SHUTDOWN worker(1BB6C8)   TCB(99D6A8) TASK(223FC8) STACKSIZE(65536)
/ 9.02.44 STC  102  HTTPD060I SHUTDOWN worker(1BA888)   TCB(99DEB8) TASK(1FAFC8) STACKSIZE(65536)
/ 9.02.44 STC  102  HTTPD060I SHUTDOWN worker(1BA908)   TCB(99E2E8) TASK(1E9FC8) STACKSIZE(65536)
/ 9.02.45 STC  102  HTTPD060I SHUTDOWN worker(1ACCC8)   TCB(99E618) TASK(1D8FC8) STACKSIZE(65536)
/ 9.02.46 STC  102  HTTPD047I Terminating File System
/ 9.02.46 STC  102  HTTPD416I Saving stats to HTTPD.STATS
/ 9.02.46 STC  102  HTTPD002I Server is SHUTDOWN
/ 9.02.46 STC  102  IEF404I HTTPD - ENDED - TIME=09.02.46
/ 9.02.46 STC  102  $HASP395 HTTPD    ENDED
/ 9.02.46 STC  102  $HASP150 HTTPD    ON PRINTER2       268 LINES
/ 9.02.47           $HASP160 PRINTER2 INACTIVE - CLASS=Z
/ 9.02.47 STC  102  $HASP250 HTTPD    IS PURGED

Common Problems#

The HTTPD service may fail during startup due to MQTT connection issues. Since MQTT telemetry isn’t required for basic HTTPD functionality, you can safely disable it. Navigate to the member SYS2.SYSINLIB(HTTPCONF) and modify the line mqtt.start="1" to mqtt.start="0".

Wrapping Up#

Now that HTTPD is running, you have the foundation for hybrid cloud communication. In future posts, I’ll cover how to use LUA370 scripts to create custom HTTP endpoints and how to integrate this with a Go API layer—the building blocks of Gameframe’s architecture.

Now of course a word of caution, you might want to be careful about publishing this on the internet directly because you’d need to add in extra security features. So be wary of that type of exposure. If you want a secure method to access your MVS server remotely with minimal configuration, try Tailscale. That’s how I was able to set up connections to my server outside my home WiFi network (and it’s free to get started!).