IOC is Born (cram init)
by Murali Shankar, with additions by An Le
August 30, 2019
Introduction
cram init is a tool used to initialize IOCs in $EPICS_IOCS and $IOC_DATA.
It generates the following directories, files, and links:
-
In $EPICS_IOCS:
-
cpuName
- kernel-modules.cmd
- epicsSpecificRelease
- cpuSpecificRelease
- startup.cmd
- screenrc
-
iocName
- iocSpecificRelease
- startup.cmd
- screenrc
-
In $IOC_DATA:
-
cpuName
-
iocName
- autosave/
- autosave-req/
- iocInfo/
- yaml/
In addition, it adds entries to screeniocs, cvs commits it, and cvs updates it on the destination host.
Finally, an email is sent to the requester and the controls team containing all the IOCs initialized, any CPUs that do not have DHCP entries, and any SIOC that do not have auto-restart scripts.
To initialize IOCs in a single application, cd into a release directory (e.g., Magnet-R7-1-7), enter
cram init
and follow the instructions in the wizard that appears.
cram init --batch
A new feature of cram init is the --batch (-b) option.
It creates directories and links for multiple IOCs using information from a CSV file.
A similar feature (--silent) was implemented a few years ago, but it required a JSON file with the following format (see sample file):
[
{
"facility": "cdlx27",
"pushCurrentRelease": "Yes",
"IOCsToInitialize": [ "vioc-mstest-003" ],
"iocType": "VIOC",
"description": "This is a VIOC",
"executable": "bin/linux-x86/mstest",
"user": "user01",
"CPU": "cpu01",
"cpuDescription": "This is a CPU description",
"screenHost": "CPUScreenHost",
"terminalPort": "9000",
"terminalServer": "CPUTermServ",
"sendEmail": "No",
"updateScreenIOCsForCPU": true
}
]
Batch mode internally generates this data from a CSV, simplifying the process for users.
To run cram init in batch mode, enter
cram init -b <csvfile> -f <facility>
It is possible to make incremental changes to your CSV input and run cram init over and over again.
cram init will rewrite files in $EPICS_IOCS and adjust screeniocs as necessary.
CSV file format
A sample CSV file is provided here.
Every IOC in the CSV file must be one of the following types:
- CPU: a hard IOC running LinuxRT
- HIOC: a hard IOC running RTEMS
- SIOC: a soft IOC running on a Linux server
- VIOC: a soft IOC running on a LinuxRT CPU
The proper CSV columns and sample entries are provided below. Blank cells indicate where data should not be provided.
Name |
Type |
Description |
Terminal Server |
Port |
Screen Host |
CPU |
User |
Executable |
Use cexp? |
Application Name |
Application Version |
cpu-bsy0-mg01 |
CPU |
A LinuxRT CPU |
ts-bsy0-nw01 |
2001 |
lcls-dev1 |
|
|
|
|
Magnet |
Magnet-R7-1-7 |
ioc-bsy0-mg01 |
HIOC |
An RTEMS IOC |
ts-bsy0-nw01 |
2002 |
lcls-dev1 |
|
|
|
|
Magnet |
Magnet-R7-1-7 |
sioc-bsy0-mg01 |
SIOC |
An SIOC on a Linux server |
|
|
lcls-dev1 |
|
|
bin/linux-x86/mgntSoft |
no |
Magnet |
Magnet-R7-1-7 |
vioc-bsy0-mg01 |
VIOC |
An SIOC on a LinuxRT CPU |
|
|
|
cpu-bsy0-mg01 |
laci |
bin/linuxRT-x86/mgntSoft |
yes |
Magnet |
Magnet-R7-1-7 |
The requirements for each IOC type are as follows:
-
CPU:
- Name: The name of the CPU. Must match the relative path from iocBoot.
- Type: CPU
- Description (optional): Description of the CPU. Appears on screeniocs as a comment.
- Terminal Server: The terminal server that the CPU uses.
- Port: The port of the terminal server.
- Screen Host: The host where screen session of the CPU is run.
- Application Name: The name of the application associated with the CPU.
- Application Version (optional): The version of the application associated with the CPU.
-
HIOC:
- Name: The name of the HIOC. Must match the relative path from iocBoot.
- Type: HIOC
- Description (optional): Description of the HIOC. Appears on screeniocs as a comment.
- Terminal Server: The terminal server that the HIOC uses.
- Port: The port of the terminal server.
- Screen Host: The host where screen session of the HIOC is run.
- Application Name: The name of the application associated with the HIOC.
- Application Version (optional): The version of the application associated with the HIOC.
-
SIOC:
- Name: The name of the SIOC. Must match the relative path from iocBoot.
- Type: SIOC
- Description (optional): Description of the SIOC. Appears on screeniocs as a comment.
- Screen Host: The host where screen session of the SIOC is run.
- Executable: The executable of the SIOC.
- Use cexp?: Whether to boot the SIOC with cexp. Valid values are yes, no.
- Application Name: The name of the application associated with the SIOC.
- Application Version (optional): The version of the application associated with the SIOC.
-
VIOC:
- Name: The name of the VIOC. Must match the relative path from iocBoot.
- Type: VIOC
- Description (optional): Description of the VIOC. Appears on screeniocs as a comment.
- CPU: The CPU on which the VIOC runs.
- User: The user under which the screen session of the VIOC runs.
- Executable: The executable of the VIOC.
- Use cexp?: Whether to boot the VIOC with cexp. Valid values are yes, no.
- Application Name: The name of the application associated with the VIOC.
- Application Version (optional): The version of the application associated with the VIOC.
Additional options
- -v, --verbose: Prints information about each step in depth
- -q, --quiet: Suppresses all output except for errors
- -j, --jsconsole: Send JavaScript console to stdout. Use for debugging only.
- -r, --remake-links: Remakes the following links for IOCs if they already exist:
- For type CPU:
- $EPICS_IOCS/iocName/iocSpecificRelease
- For types HIOC, SIOC, VIOC:
- $EPICS_IOCS/iocName/epicsSpecificRelease
- $EPICS_IOCS/iocName/cpuSpecificRelease
-
Additional notes:
- If --remake-links is not set, cram init will not touch the links if they already exist.
-
If --remake-links is set, the links already exist, and the application version is blank, then cram init will leave them alone.
If they do not already exist, the release links will point to current.
- -N, --new-startup-cmd: Create startup.cmd.new instead of startup.cmd
- -i, --ignore-iocboot: Do not verify that every IOC in the CSV file exists in iocBoot
- -T, --test-dir: Sandbox cram init work into a test directory. Reports are emailed to you instead of the controls group
Testing cram init --batch
As cram init --batch is an experimental feature, it is important to test it in a sandbox environment.
Here are the steps to activate cram init's test mode:
- Create a temporary directory containing iocCommon, iocTop, and iocData.
- Inside iocCommon, create a symbolic link common that points to $EPICS_IOCS/common.
- Inside iocCommon, create a symbolic link screenrc that points to common/screenrc.
- Next, copy $IOC_SCREEN/screeniocs to iocCommon.
- Then, in iocTop, create a symbolic link to your application (the topmost directory that contains the versions).
-
Finally, run
cram init -b csvFile -f Dev -i -T testDir
where csvFile is your CSV input and testDir is your test directory.
Notes
- cram init assumes that your application already exists in $IOC_DATA.
-
At the time of writing, startup.cmd templates are in $TOOLS/script/multi_facility_deploy/templates.
They will need to be moved to $TOOLS/script/templates.
- cram init will throw an error if a terminal port you specify conflicts with any existing port on the same terminal server in screeniocs.
-
It is recommended to run cram init on the same host as the facility specified in -f.
That way, cram init does not have to make any ssh hops.
For example, you should run
cram init -b <csvfile> -f LCLS
on lcls-srv01.
- Please use lcls-dev2, not lcls-dev3, to initialize IOCs on Dev, which is currently associated with lcls-dev2 in $TOOLS/script/multi_facility_deploy/facilities.cfg.
More details
This was taken from the original proposal for cram init and modified to reflect the correct directories.
What do we need to do as part of "IOC is born" aka "cram init"?
- We assume that cram describe has been run and we know what kind of software package this is.
- First have the user pick a facility from a list of facilities.
- Create the release folder in the facility if it does not exist.
- For IOCs, we create a folder in $EPICS_IOC_TOP of the facility if it does not exist.
- For HLAs, we create a folder in $PHYSICS_TOP/release of the facility if it does not exist.
- For tools, we create a folder in $TOOLS/script/release of the facility if it does not exist.
- cram push and cram ls should work at this point.
- If the release softlink does not exist, create a dummy release and a release softlink to the dummy release.
- Alternatively, we can cram push the current release; this assumes that we are running cram init from a tagged release.
- cram upgrade should work at this point.
- For HLAs and tools, run the post_initialization script if any to create additional softlinks. After this step, we are done for these software package types.
- For IOC's, ask for the IOC's that we'd want to initialize in this facility. Use folders in iocBoot that begin with ioc/eioc/sioc/vioc to determine the list of IOC's.
For each IOC chosen.
- If the folder $EPICS_IOCS/iocName does not exist, create it.
- For any directory created under $EPICS_IOCS, it also needs to be owned by $IOC_OWNER but make it writeable by the user only.
- If the file $EPICS_IOCS/iocName/screenrc does not exist, create it as a softlink to a template.
- If the file $EPICS_IOCS/iocName/startup.cmd does not exist, create it using a template.
- These templates are to be found in ${EPICS_IOCS}/templates and depend on the type of the IOC (HIOC/SIOC/VIOC).
We ask the user for the type of the IOC; the default is computed based on the prefix of the IOC.
- ioc and eioc's default to startup.cmd.rtems
- sioc's default to startup.cmd.soft
- vioc's default to startup.cmd.linuxRT
- If the softlink $EPICS_IOCS/iocName/startup.cmd does not exist, create it.
- If the softlink $EPICS_IOCS/iocName/iocSpecificRelease does not exist, create it and point to the current release softlink for this package.
- If the folder $IOC_DATA/iocName does not exist, create it.
- For any directory created under $IOC_DATA, please make sure it's owned by laci or spear (owned by $IOC_OWNER) and make it writeable by all (u,g,o).
- If the folder $IOC_DATA/iocName/autosave does not exist, create it.
- If the folder $IOC_DATA/iocName/autosave-req does not exist, create it.
- If the folder $IOC_DATA/iocName/iocInfo does not exist, create it.
- If the folder $IOC_DATA/iocName/yaml does not exist, create it.
- Ask the user for screenioc parameters. For all of these IOC types, we also ask for a description that gets added as a comment after the screenioc spec.
- For HIOCs, we ask for the terminal server, port and the host where screen is run (This should have a default based on facility).
- For SIOCs, we ask for the executable and the server where the softIOC is run.
- There is a possibility that we can use Garth's scheme to determine the executable automatically and avoid asking for the executable.
This will be investigated.
- For VIOCs, we ask for the executable, user (defaults to laci) and the CPU where the VIOC is run.
Create the files needed for the CPU if these are not present.
Create these in $EPICS_CPUS; if this environment variable is not defined, use $EPICS_IOCS
- If the folder $EPICS_CPUS/cpuName does not exist, create it.
- For any directory created under $EPICS_CPUS, it also needs to be owned by $IOC_OWNER but make it writeable by the user only.
- When creating CPU directories for a VIOC, also create $IOC_DATA/cpuName for the CPU console screenlog file and $IOC_DATA/cpuName/scanner for the ethercat scanner screenlog file
- If the file $EPICS_CPUS/cpuName/startup.cmd does not exist,
create it as a softlink to ../skel/startup_cpu.cmd
- If the file $EPICS_CPUS/cpuName/screenrc does not exist, create it as a softlink to a template.
- If the file $EPICS_CPUS/cpuName/kernel-modules.cmd does not exist, create it using a template.
- If the CPU does not have an entry in screenioc's, add one. We ask for the terminal server, port and the host where screen is run (This should have a default based on facility).
- iocConsole should work at this point for this IOC.
- Prepare an email for the systems group for /etc/init.d or DHCP configuration.
- TODO - Add button to the network EDM panel.
- TODO - Add ioc to IOCManager, tag, release and reboot ioc.
- TODO - Add ioc alarms to AlarmConfigs-ntwk tag, release reboot alarm ioc, restart alarm gui.
- TODO - Automate the crate and ipmi things that have to be added and the other things to set up linuxRT
- Archive IOC pvs from INFO tags in the db files.