IOCConsole

Basics

iocConsole is an EPICS extension used at various EPICS installations to create and manage a persistent console session into IOC's. iocConsole wraps the GNU screen program and creates/maintains screen sessions for each IOC. Typically, a user connects to an IOC using a command like iocConsole sioc-sys0-tm00. The connection details of the IOC's, sioc-sys0-tm00 in this example, are maintained in a screeniocs configuration file.

Installation

iocConsole is available as a git repository on AFS; the install bundle is a tar.gz of the git repo using a version tag. For example, pyIocConsole_V_1_0_6.tar.gz is a tar.gz of the V_1_0_6 checkout of the pyIocConsole git repo. To install iocConsole from the install bundle pyIocConsole_V_1_0_6.tar.gz,
  1. iocConsole is typically installed in the ${TOOLS}/script folder. Change your directory to this folder using cd ${TOOLS}/script
  2. Create a folder tree called release/pyIocConsole in ${TOOLS}/script using mkdir --parents release/pyIocConsole
  3. Change your directory to the release/pyIocConsole folder using cd release/pyIocConsole
  4. Untar the release bundle pyIocConsole_V_1_0_6.tar.gz in the ${TOOLS}/script/release/pyIocConsole folder using tar zxf /Path/To/pyIocConsole_V_1_0_6.tar.gz This should create a folder called pyIocConsole_V_1_0_6 in the ${TOOLS}/script/release/pyIocConsole folder
  5. Change your directory to the ${TOOLS}/script folder using cd ${TOOLS}/script
  6. In the ${TOOLS}/script folder, create a softlink called pyIocConsole using ln -s release/pyIocConsole/pyIocConsole_V_1_0_6 pyIocConsole. Now, if you do a ls -l pyIocConsole, you should see a softlink like so 
    $ ls -l pyIocConsole 
lrwxr-xr-x 1 user grp 28 May 12 15:08 pyIocConsole -> release/pyIocConsole/pyIocConsole_V_1_0_6/
  7. In ${TOOLS}/script, create a softlink to the iocConsole helper script pyiocscreen.py using ln -s pyIocConsole/pyiocscreen.py pyiocscreen.py
  8. In ${TOOLS}/script, create a softlink to the iocConsole main script iocConsole using ln -s pyIocConsole/iocConsole iocConsole
  9. Now, if you do a ls -l ${TOOLS}/script/ | grep pyIocConsole, you should see a set of softlinks like so 
    $ ls -l ${TOOLS}/script/ | grep pyIocConsole
lrwxr-xr-x 1 user grp     23 May 12 15:41 iocConsole -> pyIocConsole/iocConsole*
lrwxr-xr-x 1 user grp     28 May 12 15:08 pyIocConsole -> release/pyIocConsole/pyIocConsole_V_1_0_6/
lrwxr-xr-x 1 user grp     27 Apr 22 13:07 pyiocscreen.py -> pyIocConsole/pyiocscreen.py*
  10. That's it. If your screeniocs is setup correctly, you can test the install by listing the IOC's in your facility by executing a ./iocConsole --list

Upgrade

To upgrade iocConsole to a new version using the install bundle pyIocConsole_V_1_0_7.tar.gz,
  1. Change your directory to ${TOOLS}/script/release/pyIocConsole using cd ${TOOLS}/script/release/pyIocConsole
  2. Untar the release bundle pyIocConsole_V_1_0_7.tar.gz in the ${TOOLS}/script/release/pyIocConsole folder using tar zxf /Path/To/pyIocConsole_V_1_0_7.tar.gz This should create a folder called pyIocConsole_V_1_0_7 in the ${TOOLS}/script/release/pyIocConsole folder
  3. Change your directory to ${TOOLS}/script using cd ${TOOLS}/script
  4. Change the pyIocConsole softlink to the new pyIocConsole_V_1_0_7 release using
    1. rm pyIocConsole
    2. ln -s release/pyIocConsole/pyIocConsole_V_1_0_7 pyIocConsole
  5. Now, if you do a ls -l ${TOOLS}/script/ | grep pyIocConsole, you should see a set of softlinks like so 
    $ ls -l ${TOOLS}/script/ | grep pyIocConsole
lrwxr-xr-x 1 user grp     23 May 12 15:41 iocConsole -> pyIocConsole/iocConsole*
lrwxr-xr-x 1 user grp     28 May 12 15:08 pyIocConsole -> release/pyIocConsole/pyIocConsole_V_1_0_7/
lrwxr-xr-x 1 user grp     27 Apr 22 13:07 pyiocscreen.py -> pyIocConsole/pyiocscreen.py*

The screeniocs configuration file

iocConsole relies on a configuration file called screeniocs that contains the details for the IOC's. The screeniocs is external to the iocConsole package and is located using the IOC_SCREEN environment variable. 
$ ls -l ${IOC_SCREEN}/screeniocs
-rw-rw-r-- 1 user grp 84192 Jul  2 11:22 /path/to/iocCommon/All/Dev/screeniocs
You can also determine the location of the screeniocs using iocConsole -h which print the location of the screeniocs as part of the help text.
The screeniocs file is a text file that can contain
  1. Comments - Comments are content that begin with the '#' character. For example, 
    # This is a comment.
# -------- This is a line -----------------
  2. Hard IOCS - Hard IOC's are devices that we connect to using telnet sessions to a terminal server 
    
#                                        Host where
# Alias         Terminal     Port No.  screen is run     Comments (must start with #)
#-------       -------------  -------   --------------   ---------------------------------
ioc-b34-im01   ts-lclsdev07   2002      lcls-dev1        # b34-254-lab -(Dave Brown)
    In this example,
    • ioc-b34-im01 is the name of the IOC that will be used with iocConsole, for example, iocConsole ioc-b34-im01
    • ts-lclsdev07 is the terminal server that we need to connect to
    • 2002 is the TCP/IP port on the terminal server, ts-lclsdev07 that we need to connect to
    • lcls-dev1 is the host where the screen session is run
  3. Soft IOCS - Soft IOC's are typically Linux daemons that are run on servers. They are started up by iocConsole. For example, 
    # Matlab Support soft IOCs
sioc-sys0-ml00  /afs/slac/g/lcls/epics/iocCommon/sioc-sys0-ml00/iocSpecificRelease/bin/linux-x86/matlabSupport sioc lcls-dev1
    • sioc-sys0-ml00 is the name of the IOC that will be used with iocConsole, for example, iocConsole sioc-sys0-ml00
    • /afs/slac/g/lcls/epics/iocCommon/sioc-sys0-ml00/iocSpecificRelease/bin/linux-x86/matlabSupport is the path to the executable that will be used to start up the soft IOC (if it has not been started up already).
    • sioc is a hardcoded string that identifies this entry as a soft IOC.
    • lcls-dev1 is the machine where the softIOC and thus, the screen session are run.
  4. Virtual IOCS - Virtual IOC's are typically embedded Linux IOC's. Because they are Linux machines, we can connect to them using ssh. For example, 
    # Virtual IOC          Computer Host         User    Description
# ===================================================================================================================
vioc-b34-rf11         ioc-b34-cd35          daemon     # uTCA LLRF IOC TestStand
    • vioc-b34-rf11 is the name of the IOC that will be used with iocConsole, for example, iocConsole vioc-b34-rf11
    • ioc-b34-cd35 is the machine that ssh to.
    • daemon is the user id used for the ssh session.

Environment variables

iocConsole relies on a set of environment variables for its functioning.
  1. IOC_OWNER - This is the user id used for the screen sessions.
  2. IOC_SCREEN - IOC_SCREEN controls the location of the screeniocs file - which is ${IOC_SCREEN}/screeniocs
  3. IOC_DATA - Location of the bootparams file for soft IOCs. Location of the screenlog file. Location from which a soft IOC is started so that it will contain the core dump file if the soft IOC crashes
  4. SCREENBIN - Location of the screen executable - To support multiple users seeing the same sesion, the screen executable must be owned by root and have it's setuid bit set.

Troubleshooting

iocConsole supports a verbose mode that provides a lot of detailed logs to help diagnose issues. For example, run iocConsole -v sioc-troubled-ioc to see what's happening under the covers.

History

iocConsole has been thru multiple iterations - Stephanie Allison, Debbie Rogind, Jingchen Zhou, Steve Norum and Judy Rock have been involved at some time or another. Judy Rock maintained the definitive Perl version for many years; during her tenure, the Perl version was ported to Python. The Python version is currently working its way thru the various facilities.