ESD Software Engineering

IOC Console Access - iocConsole

The console to ESD iocs is accessed using the EPICS Extensions iocConsole Program.
Please refer to the former link for detailed information for iocConsole.

This page describes iocConsole useage that is specific to ESD. (Except for Screen Commands, etc., repeated here for easy reference.) This page is: $CD_WWW/ioc/iocConsole/iocConsole.html

Contents:

Screen Commands
CVS Repositories
Hard IOC Configuration
Soft IOC Configuration
Other ESD Configuration
---cdioc Accounts
---Environmment Variables
---Screen Configuration
---Socket Directory
Troubleshooting
How to Modify iocConsole Code
---Extensions source code modification
---ESD source code: screeniocs and iocConsoleLogEntry

See also:   EPICS Extensions iocConsole Program

ASD Standard Procedure for IOC Console Access

 

Screen Commands

Everything typed to the screen session is sent to the program running in the current window. The only exception is the one keystroke that is used to initiate a command to the screen session manager itself. By default each of these commands begins with a control-a (abbreviated C-a from now on) and is followed by one other keystroke.

The most important screen commands are:

  • C-a d : Detach the screen session from this terminal (C-a C-d also works).
  • C-a ? : Show all screen commands.
  • C-a * : Show a list of all users attatched to this screen session.
  • C-a [ : Enter copy/scrollback mode (C-a C-[ or C-a <esc> also works). In copy/scrollback mode you can use 'vi' or 'emacs' commands to move around the scrollback history. Some useful scrollback mode commands are:
    • Arrow keys move line by line or column by column.
    • h, j, k, l move line by line or column by column (vi-style).
    • + - move one line up/down.
    • C-u C-d move up/down one half a screen.
    • C-b C-f move up/down a full screen.
    • g moves to the beginning of the scrollback history.
    • % preceded by a number jumps to that percentage of the scrollback.
    • / or ? followed by some characters followed by a return searches forward or backwards for those characters.
    • <esc> exits copy/scrollback mode.
The entire list of screen commands can be found in the screen man page.

 

CVS Repositories

 

The perl scripts which comprise the source for iocConsole are contained in $EPICS/extensions/src/iocConsole. If changes to these source scripts are required, see How to modify iocConsole code.

In addition to the $EPICS/extensions/src/iocConsole repository, ESD maintains its own cvs repository, $CD_SOFT/ref/app/iocConsole. This area contains an ESD-specific configuration file, screeniocs, and makefiles for delivery of extensions source along with screeniocs to its own Unix Development Environment (UDE) area, $CD_SOFT/<dev|new|prod>/solaris/bin. (screeniocs is delivered to $CD_SOFT/dev/confsys.)

Hard IOC Configuration

(What's a hard ioc? - see Definition for a hard ioc.)
All ESD hard IOCs must be configured for use with iocConsole via file screeniocs (in $CD_SOFT/ref/app/iocConsole). This file is delivered to $CD_SOFT/dev/confsys directory. File screeniocs contains parameters for microname, terminal server, terminal port (or communication program for iocs without a terminal server), and screen host. The communication program for iocs without a terminal server could be either telnet or rlogin. The screen host for most production iocs is opi00gtw00, opi00gtw01, or slcs2. To add a host, see Screen Configuration.

An example of invoking iocConsole for an ESD hard ioc:
From your own afs user account, issue:
user@flora> iocConsole.pl CD03

Soft IOC Configuration

(What's a soft ioc (sioc)? - see Definition for a soft ioc.)
Use the following as a guide to setting up ESD soft iocs, as this setup allows connection via iocConsole after the soft ioc is started. See Mike Laznovsky for more details.

1) Setup the soft ioc directory structure similar to:
<user>@slcs2 $ cd $CD_IOC/rfw00pep00
<user>@slcs2 $ ls

base -> ../../ref/epics/R3.14.6/ioc
bin -> ./base/bin/solaris-sparc-gnu
dbd -> ./base/dbd
st.RW00
st.rfWatcher
start.RW00 -> st.RW00
startupE -> ../boot/startup/st.rw00.cmd
stop.RW00

2) Like hard iocs, all ESD soft iocs must be configured for use with iocConsole via file screeniocs. Use instructions in Configuration File Modification: screeniocs). Here is an example of a soft ioc entry in screeniocs:
RW00 $CD_IOC/RW00/bin/rfWatcher sioc slcs2

3) An example of starting an ESD soft ioc:
(NOTE: this is different than connecting to the sioc via iocConsole. Initial starting of the sioc is done infrequently in most cases.) Read comments in the st.RW00 file as to the sequence of starting; st.RW00 file issues "iocConsole.pl RW00..." in order to start the soft ioc.

4) To connect to sioc via iocConsole (for sioc just started, or in general):
From your own afs user account, issue:
user@flora> iocConsole.pl RW00
This invocation mirrors that used for hard iocs.

5) To stop a soft ioc, you can use a script like 'stop.RW00':
#!/bin/tcsh
# stop rfWatcher soft IOC
source /afs/slac/g/cd/soft/dev/script/ENVS.csh
setenv RFW RW00
setenv RFW_HOST_PROD slcs2
iocConsole.pl $RFW $CD_IOC/$RFW/st.rfWatcher sioc $RFW_HOST_PROD -cleanup

6) Soft IOCs with a certain CPE software startup file configuration (MORE INFO TO BE ADDED HERE, but an example is CW00 - if in doubt see Jingchen or the IOC's developer) can be restarted by logging into the IOC with iocConsole, then typing

   exit

at the epics prompt.  The IOC will stop, and then be automatically be restarted in 5 seconds (-:

Other ESD Configuration

cdioc Accounts

As a user of iocConsole, ensure that you have password-less login privileges for the cdioc account. Please refer to ESD iocConsole cdioc AFS and NFS Account information.

Environment Variables

The following env vars are contained in setEnv.csh:
$IOC_SCREEN is set to ${CD_SOFT}/dev/confsys
$IOC_OWNER is set to cdioc
   - if $IOC_OWNER is not defined, the default is "cdioc".
$CD_IOC/ postpended with ioc (4 digit) name is used as the path to the st.cmd file for soft iocs (ie $CD_IOC/HW21/st.cmd)
$IOC_LOGSCRIPT is set to iocConsoleLogEntry (in cvs app/iocConsole) to enable logging to the sw_log of the ELOG. It makes the following entry in sw_log: "iocConsole to <microname> by <user>. All users are encouraged to start iocConsole from their own unix account rather than the cddev account.

Screen Configuration

- opi00gtw00 is screen host for all IOCs on the private networks
- slcs2 and opi00gtw01 are screen hosts for some soft iocs
- the screen utility must be installed locally in /opt/screen/bin on screen hosts
- for Solaris machines, screen has been built by Jingchen Zhou and resides in /afs/slac/g/cd/soft/support/package/screen/screen-3.9.11.
- cdioc is the shared account for "iocConsole".
- the SUID root access mode is set via
1) chown root /opt/screen/bin/screen
2) chmod u+s /opt/screen/bin/screen
> ls -all /opt/screen/bin/screen
-rwsr-xr-x 1 root other 1479772 Nov 21 11:30 /opt/screen/bin/screen*
Notice the s bit. Now screen is owned by root and has the SUID access mode set,
so when cdioc executes screen, cdioc's EUID is changed to root for that command. That is to say, it only allows cdioc to have a root privilege on screen (the command-level basis) under controlled circumstances. This is felt to be more secure compared with allowing each developer to have a sudo privilege.

See also Installing Screen.

Socket Directory (/tmp/screens)

Since screen runs with SUID access mode, it keeps its sockets under /tmp/screens/S-<shared-account-name>. The /tmp/screens directory cannot be overridden by the $SCREENDIR environment variable. It must never be deleted and files under it must never be removed while screen is running.

Troubleshooting

Cleanup Option: If you are unable to connect to an ioc, perhaps due to an existing dead screen session, try:
user@flora> iocConsole.pl CD03 -cleanup
after cleaning up, reissue command
user@flora> iocConsole.pl CD03

For most terminal servers, a password must be provided the first time the screen process is started, or when power has been cycled on the terminal server. Please see Terri Lahey or Debbie Rogind for the password.

If someone has an existing telnet connection to the hard IOC terminal server port (or to the hard IOC itself if it's not connected to a terminal server), iocConsole will not be able to connect. If you receive the following message from iocConsole:
"No sockets found in /tmp...", followed by "Timeout waiting for Multiuser session.." it most likely means that other individual(s) have an rlogin/telnet session connected to that ioc currently. To cleanup, a) issue ps -ef | grep <iocname> on the screen host (such as opi00gtw00), and b) kill all rlogin (or telnet) pids associated with that <iocname>. Then issue iocConsole.pl <4-digit microname> again. After cleanup, for example, a healthy RF Station ioc that uses iocConsole with rlogin looks like:
opi00gtw00:/tmp/screens/S-cdioc% ps -ef | grep rfs12her01
cdioc 4338 4336 0 08:17:46 pts/5 0:00 rlogin rfs12her01
cdioc 4339 4338 0 08:17:46 pts/5 0:00 rlogin rfs12her01
root 4336 1 0 08:17:46 ? 0:00 /opt/screen/bin/screen -d -m -S HR21 -t HR21 rlogin rfs12her01

To view existing screen sessions (on slcs2):
user@flora> ssh -l cdioc slcs2
cdioc@slcs2 $ /opt/screen/bin/screen -list
There are screens on:
7703.CD06 (Dead?)
17734.TR07 (Detached)
10753.TR08 (Attached)
28246.TR09 (Attached)
4 Sockets in /tmp/screens/S-cdioc.
(The -cleanup option of iocConsole.pl first kills desired screen, then performs an /opt/screen/bin/screen -wipe)

To view existing (production) screen sessions on opi00gtw00:
user@flora> ssh -l cdioc opi00gtw00
opi00gtw00:cdioc% /opt/screen/bin/screen -list
No Sockets found in /tmp/screens/S-cdioc.

If you encounter the following message when connecting to or restarting a soft ioc:
29235
IOC HW41 already started
[screen is terminating]
and you have determined the ioc is not actually running, make sure the file argument to iocConsole (for soft ioc executable or startup script) is not so long that the pgrep system command inside of siocStart.pl can't match it.

Telnet user interference
To knock off another user using telnet (or to clear the line), do the following:
drogind@flora05 $ telnet b5as <<--list of terminal servers can be found in file screeniocs, amongst others
Trying 134.79.48.219...
Connected to b5as.slac.stanford.edu.
Password: <<---- ask Terri or Judy
b5as>enable
Password: <<---different than password above; ask Terri or Judy
b5as#systat
Line User Host(s) Idle Location
1 tty 1 pepii incoming 23:21 slcs2.slac.stanford.edu
5 tty 5 pepii idle 6d17 slcs2.slac.stanford.edu
6 tty 6 pepii idle 7 slcs2.slac.stanford.edu
* 18 vty 0 idle 0 flora05.slac.stanford.edu

b5as#clear line 6
[confirm]
[OK]
b5as#systat <<-- to see if line cleared (yes, 6 is gone:)
Line User Host(s) Idle Location
1 tty 1 pepii incoming 23:22 slc2.slac.stanford.edu
5 tty 5 pepii idle 6d17 slcs2.slac.stanford.edu
* 18 vty 0 idle 0 flora05.slac.stanford.edu
b5as#logout

How to Modify iocConsole code

  • Source Code Modification in SLAC-EPICS-Releases extensions repository

Before modifying iocConsole source perl scripts, check your proposed change with Stephanie Allison so that she can make sure the change is compatible with SPEARS iocs. Then,

setenv CVSROOT /afs/slac/package/epics/slaconly/cvs
....
Now go to Building iocConsole on the extensions webpage for detailed instructions for building iocConsole for all epics releases supported. Once done with building in the extensions area, come back here for instructions on how to release the extensions version just built into the ESD area:

Now gmake<tst>, <dev>, <new> to deliver the changes into the ESD escalation areas:
setenv CVSROOT /afs/slac/g/cd/soft/cvs
gmaketst<dev, new> app/iocConsole

  • ESD Source File Modification: 1) screeniocs and 2) iocConsoleLogEntry

1) screeniocs file is an ESD CONFSYS file (see BUG chapter on Configuration File Support); confsys config files are not escalated like exe scripts; they remain at the $CD_SOFT/dev/confsys delivery area, and in $CD_REF/confsys of course)used to connect to hard and soft iocs. This file lists all IOCs so that iocConsole can be called with just the IOC name and no further arguments. Examples of screeniocs entries:

  • Hard IOC Connected to a Terminal Server:
    <iocname> <terminal server> <port> <screen host>
  • Hard IOC Connected to an "ssh Terminal Server":
    <iocname> <terminal server> <sshport*> <screen host>
  • Hard IOC not Connected to a Terminal Server:
    <iocname> <ioc node name> <rlogin or telnet> <screen host>
  • Soft IOC:
    <iocname> <executable name> sioc <screen host>

    *port number is prefixed with 'ssh' (e.g. ssh3033) to identify it as an ssh terminal server

Screeniocs is setup with one line per ioc, each line containing multiple columns separated spaces:
Columns:
1st: Micro name or soft ioc name
  - if soft ioc, then soft ioc has been previously started with its st.<soft ioc name>
     (see Soft IOC Configuration above)
2nd: terminal server node name
  - if no terminal server, then this is the ioc node name
  - if soft ioc, then this is the executable name
3rd: port number on the therminal server
  - if no terminal server, then this is 'telnet' or 'rlogin'
  - if soft ioc, then this is 'sioc'
  - if ssh terminal server is used, then port number is prefixed with 'ssh', e.g. 'ssh3033'
4th: host name where screen is run
Separate all columns with a space " " - the perl scripts delimit on this.

2) iocConsoleLogEntry file, (in cvs repository; /afs/slac.stanford.edu/g/cd/soft/cvs/app/iocConsole)is a tshell script which logs user iocConsole activity to the elog (or cmlog).

To modify screeniocs or iocConsoleLogEntry(in ESD area),

setenv CVSROOT /afs/slac/g/cd/soft/cvs
cd <working directory>
cvs checkout app/iocConsole
.. make changes to screeniocs or iocConsoleLogEntry...
cvs commit
cd <working directory>
cvs release app/iocConsole
gmake<tst><dev><new> app/iocConsole 

[SLAC ESD Software Engineering Group]
[SLAC Home Page]
  
Author: Debbie Rogind, 08-April-2004  
Last Modified: Debbie Rogind, 25-Jan-2005