README

Contains a Debian SysV style initialization script for a softioc using procServ.

= Usage =

This package uses the following files

/usr/bin/manage-iocs
/etc/init.d/softioc-*
/etc/default/epics-softioc
/epics/iocs/*/config

The following are provided as information.

/usr/share/doc/sysv-rc-softioc/config.example
/usr/share/doc/sysv-rc-softioc/README (this file)

== 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 IOC.

HOSTNAME - The short name of the host running the IOC.

TOP - The absolute path of the base IOC directory.  Contains the 'config' file

EPICS_HOST_ARCH - Host target name (eg. linux-x86)

== 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 of all/an IOC
  status        - Check if IOCs are running
  nextport      - Find the next unused procServ port
  install <ioc> - Create /etc/init.d/softioc-[ioc]
  enable <ioc>  - Register IOC to start during system boot
  disable <ioc> - Un-register IOC

== Initial Setup ==

1) Choose a location for softIoc instance data (st.cmd, db, ...).

This will be a single directory which will contain a subdirectory for each softIoc instance.  A good choice would be '/epics/iocs'.

Set this path in '/etc/default/epics-softioc'.

$ cat /etc/default/epics-softioc
SOFTBASE=/epics/iocs
$

Note: Since version 1.3 SOFTBASE can be a ':' separated list of paths.

2) Create a Unix group softIocs

Each softIoc can run as a separate user.  This provides a nice division and allows Channel Access security to distinguish all the instances on a given machine.  It is recommended that all softIoc users be in the same group.

# groupadd softioc

3) Create the directory for softIoc instances

# mkdir /epics
# chgrp softioc /epics
# chmod g+s /epics
# mkdir /epics/iocs
# chmod g+ws /epics/iocs

4) (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 ==

1) Choose a name

Try to pick something more creative than example1 ;)

2) Create a user

# useradd -c 'softioc' -d /epics/iocs/example1 -g softioc -N example1
# mkdir /epics/iocs/example1

3) Configure the instance

Each instance must have a name and a 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.

# cat << EOF > /epics/iocs/example1/config
NAME=example1

PORT=4051

HOST=myserver
EOF

Note: The manage-iocs script has a subcommand 'nextport' which tries to pick an unused port number from procServ.

If given, the hostname is required to match the result of running 'hostname -s' or 'hostname -f'.

See /usr/share/doc/sysv-rc-softioc-#/config.example for allowed items in a IOC config file.

# manage-iocs install example1

This creates/replaces the script /etc/init.d/softioc-example1

4) Add the softioc to the boot sequence

# manage-iocs enable example1

5) To remove from the boot sequence

# manage-iocs disable example1

6) (optional) Configure Conserver

After creating /epics/iocs/example1/config run:

# update-iocs-cf

7) Manually starting the instance

# /etc/init.d/softioc-example1 start

8) (optional) View console

$ console example1

9) (alternative) Direct telnet

$ telnet localhost 4051