This repository is derived from: https://github.com/epicsdeb/sysv-rc-softioc
This repository contains a systemd style initialization script for a softioc using procServ.
= Usage =
Use "install.sh" (with sudo access) to install this package. By default, the source files are installed in /usr/local/systemd-softioc and a symlink "/usr/bin/manage-iocs -> /usr/local/systemd-softioc/manage-iocs" is created. Since this package is dependant on procServ, install.sh will try its best to get procServ's github repository, then build it and install the executable to /usr/bin/.
Source files:
epics-softioc.conf: this is where you can customize a few things;
manage-iocs: the main script;
library.sh: functions used in the script manage-iocs;
The following are provided as information:
config.example: a template showing how to create a file named 'config' for an IOC instance/application;
softioc-example.service: the unit file generated by "manage-iocs install example" for the IOC named "example";
softioc-logrotate: installed in /etc/logrotate.d for rotating IOC log files;
README.md (this file)
In the following sections, a command starting with '#' means sudo is required, '$' means non-sudo required.
== manage-iocs ==
The script 'manage-iocs' has several sub-commands to help in managing softiocs. See its manpage for details.
$manage-iocs help
Usage: manage-iocs [-v] [-x] cmd
Available commands:
help - display this message
report [ioc] - Show config(s) of an IOC/all IOCs on localhost
status - Check if installed IOCs are running or stopped
nextport - Find the next unused procServ port
install <ioc> - Create /etc/systemd/system/softioc-[ioc].service
uninstall <ioc> - Remove /etc/systemd/system/softioc-[ioc].service
start <ioc> - Start the IOC <ioc>
stop <ioc> - Stop the IOC <ioc>
startall - Start all IOCs installed for this system
stopall - Stop all IOCs installed for this system
enable <ioc> - Enable auto-start IOC <ioc> at boot
disable <ioc> - Disable auto-start IOC <ioc> at boot
list - a list of all IOC instances under /epics/iocs:/opt/epics/iocs;
including those IOCs running on other hosts
== Initial Setup ==
- Choose a location for all softIoc instances / applications
This will be a path which will contain a subdirectory for each softIoc instance. A good choice would be '/epics/iocs' (or '/opt/epics/iocs', or both). You can customize this path in '/usr/local/systemd-softioc/epics-softioc.conf' (not 'epics-softioc.conf' in your cloned repository). This is the default path:
IOCPATH=/epics/iocs:/opt/epics/iocs
- Create a Unix user/group 'softioc'
Altough each softIOC can run as a separate user/group, it is recommended using a single username 'softioc'. This provides a nice division and allows Channel Access security to distinguish all instances on a given machine. The script "install.sh" will try to create a username 'softioc'. If the user account 'softioc' does not exist, you can create it:
#useradd softioc
-
Create a directory (/epics/iocs or /opt/epics/iocs is recommended) for softIOC instances
#mkdir -p /epics/iocs
#chown softioc:softioc /epics/iocs
#chmod g+ws /epics/iocs
Now, you can switch to 'softioc': #sudo -s -u softioc, then do whatever you want in /epics/iocs.
Note: softioc:softioc is recommended. You can use other 'username:groupname', but you might get permission issues when 'autosave' is used in an IOC.
- Optional: Install Conserver
Conserver is a process which connects to the telnet servers provided by all the softIocs on a host. It then allows (secure) remote access and continuous logging.
#apt-get install conserver-server
Edit /etc/conserver/conserver.cf to include the following line.
default softioc { type host; host localhost;}
#include /etc/conserver/iocs.cf
See the conserver documentation for information on access control.
Note: Conserver uses the tcpd for authentication.
== Per-Instance Setup ==
-
Firstly, choose a name. Try to pick something more creative than example1. If you have not switched to 'softioc' yet, do this: #sudo -s -u softioc
-
Create an IOC instance directory
$cd /epics/iocs/
$mkdir -p example1
Note: If you do not want to use the user account 'softioc' to run your IOC, you can create a user 'example1' specifically for the IOC 'example1': #useradd -c 'example1' -d /epics/iocs/example1 -g softioc -N example1
-
Create and customize the instance's configuration file 'config'
$cd /epics/iocs/example1
$touch config
Each instance must have a unique name and a unique port number (for procServ). It is also a good idea to include the server's hostname to prevent accidentally running it on the wrong server. Copy & paste the following must-have variables to the file 'config', then make changes accordingly.
NAME=example1
PORT=4051
HOST=myserver
USER=softioc
NAME: required to match your IOC instance name.
PORT: type 'manage-iocs nextport', which tries to pick an unused port number for procServ. DO NOT use any well-known ports (23, 80, 5064, 5065, 8080, etc.).
HOST: required to match the result of 'hostname -s' or 'hostname -f'.
USER: a user account which must exist on localhost.
CHDIR/EXEC: if you do not have a 'st.cmd' in /epics/iocs/example1, you have to set CHDIR and EXEC accordingly in the 'config'. See config.example for allowed items in a IOC config file.
After you are done with customizing the file 'config', it is a good practice to use 'manage-iocs report' to confirm your IOC's configuration.
-
install the systemd unit file (/etc/systemd/system/softioc-example.service).
#manage-iocs install example1
(#manage-iocs uninstall example1: this removes the unit file)
-
Start the IOC instance. You will be asked if you want auto-start IOC at boot. If yes, the IOC will automatically startup after the host server boots up.
#manage-iocs start example1
It is a good practice to use 'manage-iocs status' to confirm your IOC's status.
-
Telnet to the IOC's EPICS shell to see if it is really working.
$telnet localhost procServ-port-number
== IOC runtime environment ==
The following environment variables are automatically set before procServ is started. They may be overridden in the IOC shell.
IOCNAME - The IOC name.
USER - The system user account name which runs the procServ/IOC.
HOSTNAME - The short name of the host running the IOC.
TOP - The absolute path of the base IOC directory which contains the 'config' file