EPICS IOC Runner

Overview

epics-ioc-runner is a robust, dependency-free, and OS-native management environment for EPICS IOCs. It provides a streamlined approach to deploying, monitoring, and controlling IOCs running under procServ using standard Linux tools like systemd, bash, and sudo.

By eliminating heavy dependencies, this architecture adheres strictly to the KISS (Keep It Simple, Stupid) and DRY (Don't Repeat Yourself) principles, ensuring long-term maintainability across different Linux distributions.

Prerequisites

This architecture requires the following core utilities to be installed on your system (e.g., in ~/.local/bin for local-mode user installs, /usr/local/bin, or /usr/bin):

• procServ: https://github.com/jeonghanlee/procServ-env
• con: https://github.com/jeonghanlee/con (Recommended for clean detachment via Ctrl-A)
  • Fallback: If con is unavailable, the attach command automatically falls back to socat or nc (with -U UNIX Domain Socket support).

Key Highlights

• No Python or Framework Runtime: Built on Bash 4.3+ and native systemd. Runtime depends on procServ, con, lsof, ss, and awk; no Python interpreter or application framework is required.
• High-Performance Minimal-Fork Architecture: Utilizes pure Bash stream parsing and O(1) associative arrays to batch-fetch socket and systemd states, eliminating per-IOC subprocess overhead.
• Dual Execution Modes: Supports both system-wide deployment (via RBAC and sudoers) and isolated local user environments for testing.
• Input Isolation (monitor): Safe, uni-directional console observation to prevent interleaving of unintended inputs during sensitive hardware operations.
• Advanced Peer Tracking (inspect): Deep Netlink inode correlation to map and isolate specific external users attached to UNIX Domain Sockets.

Installation

A modular configure/ Makefile wraps deployment; run make help to list targets. Run the system targets as your user (each invokes sudo inside the recipe, so they work in place even on an NFS root_squash home):

make setup          # System-wide: accounts, group, sudoers, systemd template, CLI
make install        # System-wide CLI only (ioc-runner + completion + RHEL symlink)
make install.user   # User-home install under ~/.local/bin (no root)

See the System Installation Guide for the full procedure and a manual reference.

Quick Start / Usage

The ioc-runner provides a seamless workflow from automated configuration generation to system-wide deployment.

# 1. Generate & Review: Create a .conf file from an iocBoot directory
# (Interactive diff preview and startup script selection included)
ioc-runner generate /path/to/iocBoot/myioc

# 2. Install: Deploy the generated .conf to system-wide procServ.d
# (Accepts the same directory path to auto-resolve the .conf file)
ioc-runner install /path/to/iocBoot/myioc

# 3. Control: Start and manage the IOC daemon
ioc-runner start myioc
ioc-runner stop myioc

# Console Access: Read/Write vs. Read-Only
ioc-runner attach myioc            # Interactive console access
ioc-runner monitor myioc           # Safe, uni-directional observation

# Diagnostic & Tracking
ioc-runner list -vv                # Full kernel socket states and inodes
sudo ioc-runner inspect myioc      # Deep trace of active client PIDs (Admin only)

For isolated testing without root privileges, simply prepend --local to any command:

# Local user-space testing workflow
ioc-runner generate --local .
ioc-runner install --local .
ioc-runner start --local myioc

Repository Structure

epics-ioc-runner/
├── Makefile                      # Make front end (install / setup / install.user)
├── bin/
│   ├── ioc-runner                # Front-end CLI wrapper
│   └── setup-system-infra.bash   # Automated system infrastructure setup script
├── configure/                    # Modular Makefile system (CONFIG / RULES / .local overrides)
├── docs/                         # Detailed system documentation
├── policy/                       # RBAC and Sudoers reference configurations
├── system-wide/                  # External management tool integrations
├── tests/                        # Automated integration test suites
├── LICENSE                       # MIT License
└── README.md                     # Project overview and entry point

Documentation

For detailed operational instructions, security models, and architectural notes, please refer to the dedicated documentation in the docs/ directory:

1. System Installation Guide: Infrastructure setup for System Administrators & SREs.
2. Operations User Guide: Managing system-wide IOCs for EPICS Engineers.
3. Local Execution Guide: Testing IOCs in isolated local user space.
4. Architecture Overview: Security model, SetGID policies, and system design.
5. CLI Technical Reference: Kernel-level socket state mappings, and data flow architecture for diagnostic commands.
6. Exit Signal Handling: Signal propagation and systemd exit status technical notes.
7. Operations FAQ: Common operational questions and answers for facility engineers.

Acknowledgments

This project is inspired by the Python-based procServUtils maintained in the ralphlange/procServ repository.