Using the CTCSERV program in my container image

Overview of the CTCSERV application

Definately not my work, I would not have the patience. But brilliant work. This can be considered an undocumented feature of the container, in that by default it is not used and I need to revisit it so it starts under a userid yet to be added to my system with virtually no access, and make it do something I may find useful.

This is available from https://github.com/racingmars/ctc-mainframe-api

It comprises two components. The first is the CTCSERV program running within the MVS3.8J system as a server to handle the requests, using CTCE devices 502 and 503. The second component is a API server (written in GO) that runs on your Linux/MacOS machine to provide an API http server interface that accepts requests via utilities such as "curl" to pass commands to the CTCSERV program running in mvs38j and get reponses back across the CTCE adapters.

The container contains my customisations to CTCSERV and ctcserver. By default if USECTCSERV=YES is used with no other parameters both the MVS3.8J CTCSERV task is started and the ctcserver API task is also started within the container so curl can be used against whatever you map container port 8370 to.
If you want CTCSERV started but intend to run the ctcserver from the github source (without my modifications) then use the CTCRHOST parameter to set the ip-address to that of the machine you will be running ctcserver on and the customisations to use that will be done, and the in-container ctcserver will not be started. Note that my customised CTCSERV is still the one that will be started under MVS3.8J but it continues to support all parameters from the github source (as of 21Aug2023 anyway).

Changes made to my copy of CTCSERV run in the container

I have added one extra function, a "rexxexec" function to execute REXX scripts and return the resulting stdout output. This is currently of limited use to me as I have never been able to get the REXX function RXCONSOL to work (to return the console output from a command) so until I get that working running REXX scripts through this tool is only a feature I'm playing with.

As there is no security around this API facility you may not pass parameters to the rexx scripts being run, and rexx scripts can only run from dataset MARK.CTCSERV.EXEC so I know what can be run.
You can change that by updating SYS9.PROCLIB(CTCSERV) to change that library or concatenate others as long as you remember it is insecure (maybe I will make that a container parameter list/file one day as well).

How to configure my container to run it

By default the CTCE devices are not configured and you cannot use it. You must use container environment variables to make it available if you want to use it.

There are a couple of things to note.

• First, this is only in my "deb12" containers. They are the only ones I place new things into now
• Second, if possible you should use the container build to use hyperion. It will work with the spinhawk one but using ctrl-c on the ctcserver API program will always crash spinhawk hercules; there is not that issue with hyperion. However if using ctcserver running within the container you are unlikely to ctrl-C it so not an issue there either, but something to be aware of.
• Read the container notes to decide which to use, as the hyperion one does not run on all platforms (something docker on rhel host platforms doesn't like the hyperion version of hercules trying to do, but it runs runs fine on deb12 docker host platforms)

Additional container environment parameters that can be used to start the CTC API interface are shown below. The only one you need to use is "USECTCSERV=YES", you should only change the others if chosing to use a ctcserver program external to the container.

USECTCSERV=YES - default is NO, in which case all the below are ignored
CTC502LPORT    - default 15620 
CTC502RPORT    - default 15600
CTC503LPORT    - default 15630
CTC503RPORT    - default 15610
CTCRHOST       - default 127.0.0.1 (the host ctcserver API is running on,
		 if left as 127.0.0.1 the ctcserver process will be started running
		 within the container, expose port 8370 to use it)

Note: if you change CTCRHOST you must manually start a copy of ctcserver
      on the host with the ipaddr you configured, and expose ports
      15620 and 15630. You will not need to expose 8370 as that is
      the ctcserver port and you will not be using the one in the container.

I have placed the CTCSERV proc into SYS9.PROCLIB(CTCSERV) so it can be started with "S CTCSERV" as needed. It does not accept the park command so you must use "C CTCSERV" to stop it.... or the ctcserver API request /quit will stop it more cleanly.
As it will start if you used the environment variables to select it you would only need to stop/start it if you are also testing things.

The commands that are available through the API are documented at https://github.com/racingmars/ctc-mainframe-api.
The only additional command I have added at this time is "/rexxexec/membername".

For the "rexexec/membername" I have added, it is limited to running REXX scripts from the file MARK.CTCSERV.EXEC as lets face it you need to control what damage that function can do.