Environment Variables

This Puppet module installs and configures an EPICS soft IOC. The IOC is run in procServ to ease maintenance. The IOC can be started/stopped as a system service. On systems that use systemd as init system (e.g. Debian >=8) a systemd unit file will be created for each IOC process. On older systems (e.g. Debian 7) this module relies on sysv-rc-softioc for creating System V init scripts instead.

Environment Variables

Some attributes of the Epics_softioc::Ioc class cause environment variables to be set. Please refer to the following table for a list:

Attribute	Environment Variable
`ca_addr_list`	`EPICS_CA_ADDR_LIST`
`ca_auto_addr_list`	`EPICS_CA_AUTO_ADDR_LIST`
`ca_max_array_bytes`	`EPICS_CA_MAX_ARRAY_BYTES`
`log_port`	`EPICS_IOC_LOG_PORT`
`log_server`	`EPICS_IOC_LOG_INET`
`ca_sec_file`	`EPICS_CA_SEC_FILE`

Environment variables that are not on this list can be set using the env_vars attribute.

Examples

Simple

  $iocbase = '/usr/local/lib/iocapps'

  class { 'epics_softioc':
    iocbase => $iocbase,
  }

  epics_softioc::ioc { 'mysoftioc':
    ensure  => running,
    enable  => true,
    bootdir => 'iocBoot/ioclinux-x86_64',
    require => File["${iocbase}/mysoftioc"],
  }

Complex

In this example we run two IOC processes on the same machine. Thus different procServ ports need to be used. See the first block for an example of setting facility-wide defaults.

Epics_softioc::Ioc {
  log_port            => 6500,
  log_server          => 'logserver.example.com',
  manage_autosave_dir => true,
}

$iocbase = '/usr/local/lib/iocapps'

class { 'epics_softioc':
  iocbase => $iocbase,
}

epics_softioc::ioc { 'vacuum':
  ensure            => running,
  enable            => true,
  bootdir           => 'iocBoot/ioclinux-x86_64',
  console_port      => 4051,
  ca_addr_list      => '',
  ca_auto_addr_list => true,
  env_vars          => {
    'EPICS_CA_CONN_TMO'     => '1',
    'EPICS_CA_NAME_SERVERS' => 'nameserver.example.com',
  },
  uid               => 900,
  run_make          => false,
  require           => File["${iocbase}/vacuum"],
}

epics_softioc::ioc { 'llrf':
  ensure       => running,
  enable       => true,
  bootdir      => 'iocBoot/ioclinux-x86_64',
  console_port => 4052,
  uid          => 901,
  require      => File["${iocbase}/llrf"],
}

Reference

Class `epics_softioc`

This class takes care of all global tasks which are needed in order to run a soft IOC. It installs the needed packages and prepares machine-global directories and configuration files.

`gid`

Define the group id of the group the IOCs are run as. This group is used for granting access to the common log directory. The gid will be picked automatically if this option is not specified.

`iocbase`

By default the IOC directories are expected to be all in one location. This option specifies the path to this base directory. Default: /usr/local/lib/iocapps.

Defined Type `epics_softioc::ioc`

This type configures an EPICS soft IOC. It creates configuration files, automatically populates them with the correct values and configures the IOC for running it as a system service. The top-level IOC directory of the IOC is expected to be $iocbase/<ioc_name> where <ioc_name> is the name specified for the epics_softioc::ioc resource.

`abstopdir`

Absolute path to the IOC's top-level directory. Defaults to <iocbase>/<ioc_name>.

`auto_restart_ioc`

Whether to restart the IOC after recompiling. If set to true the IOC will be restarted automatically after recompiling the source code (see run_make). This ensures the latest code is being used. The default is true.

`autosave_base_dir`

The path to the base directory for the EPICS autosave module. Defaults to /var/lib.

`bootdir`

Path to the directory containing the IOC start script. This path is relative to abstopdir. This defaults to iocBoot/ioc\${HOST_ARCH}.

`ca_addr_list`

Allows to configure the EPICS_CA_ADDR_LIST environment variable for the IOC. The default is undefined (environment variable not set).

`ca_auto_addr_list`

Allows to configure the EPICS_CA_AUTO_ADDR_LIST environment variable for the IOC. Valid values are true and false. The default is undefined (environment variable not set).

`ca_max_array_bytes`

Allows to configure the EPICS_CA_MAX_ARRAY_BYTES environment variable for the IOC. The default is undefined (environment variable not set).

`cfg_append`

Allows to set additional variables in the IOC's config file in /etc/iocs/. This is not used on machines that use systemd.

`console_port`

Specify the port number procServ will listen on for connections to the IOC shell. You can connect to the IOC shell using telnet localhost <portnumber>. The default port is 4051.

Note that access is not possible if enable_console_port is set to false.

`coresize`

The maximum size (in Bytes) of a core file that will be written in case the IOC crashes. The default is 10000000.

`enable_console_port`

If set to true (the default) procServ will listen on the port specified by console_port for connections to the IOC shell. If this flag is true for at least one IOC telnet is being installed.

`enable_unix_domain_socket`

If set to true (the default) procServ will create a unix domain socket for connections to the IOC shell. If this flag is true for at least one IOC the BSD version of netcat is installed.

`ensure`

Ensures the IOC service is running/stopped. Valid values are running, stopped, and . If not specified Puppet will not start/stop the IOC service.

`enable`

Whether the IOC service should be enabled to start at boot. Valid values are true, false, and . If not specified (undefined) Puppet will not start/stop the IOC service.

`env_vars`

Specify a hash of environment variables that shall be passed to the IOC. Defaults to {}.

`log_port`

Allows to configure the EPICS_IOC_LOG_PORT environment variable for the IOC. The default is 7004 (the default port used by iocLogServer).

`log_server`

Allows to configure the EPICS_IOC_LOG_INET environment variable for the IOC. The default is undefined (environment variable not set).

`ca_sec_file`

Allows to configure the EPICS_CA_SEC_FILE environment variable for the IOC. The default is undefined (environment variable not set). To be used as input for asSetFilename(${EPICS_CA_SEC_FILE}).

`logrotate_compress`

Whether to compress the IOC's log files when rotating them. Defaults to true.

`logrotate_rotate`

The time in days after which a the log file for the procServ log will be rotated. Default is 30.

`logrotate_size`

If the log file for the procServ log reaches this size the IOC log will be rotated. Default is '10M'.

`manage_autosave_dir`

Whether to automatically populate the AUTOSAVE_DIR environment variable. Valid values are true and false. If true the specified directory will be created (users need to ensure the parent directory exists) and permissions will be set up appropriately. The AUTOSAVE_DIR environment variable will be set to <autosave_base_dir>/softioc-<ioc_name>. Also see autosave_base_dir.

`manage_user`

Whether to create the user account the IOC is running as. Set to false to use a user account that is managed by Puppet code outside of this module. Disable if you want multiple IOCs to share the same user account. Defaults to true.

`procserv_log_file`

The log file that procServ uses to log activity on the IOC shell. Default: /var/log/softioc-<ioc_name>/procServ.log.

`run_make`

Whether to compile the IOC when its source code changes. If set to true the code in the IOC directory will be compiled automatically by running make. This ensures the IOC executable is up to date. The default is true.

Note: This module runs make --question to determine whether it needs to rebuild the code by running make. Some Makefiles run a command on every invocation. This can cause make --question to always return a non-zero exit code. Beware that this will cause Puppet to rebuild your IOC on every run. Depending on the auto_restart_ioc setting this might also cause the IOC to restart on every Puppet run! Please verify that your Makefiles are behaving correctly to prevent surprises.

`run_make_after_pkg_update`

If this option is activated the IOC will be recompiled whenever a package resource tagged as epics_ioc_pkg is refreshed. This can be used to rebuild IOCs when facility-wide installed EPICS modules like autosave are being updated. The default is true.

`unix_domain_socket`

Specify the Unix domain socket file procServ will create for connections to the IOC shell. The file name has to be specified relative to the run-time directory (/run). You can connect to the IOC shell using nc -U <unix_domain_socket>. The default is softioc-<ioc_name>/procServ.sock.

Note that the unix domain socket will not be created if enable_unix_domain_socket is set to false.

Example

Facility-wide IOC profile:

  class { 'epics_softioc':
    iocbase => '/usr/local/lib/iocapps',
  }

  package { 'epics-autosave-dev':
    ensure => latest,
    tag    => 'epics_ioc_pkg',
  }

Machine-specific manifest:

  epics_softioc::ioc { 'mysoftioc1':
    ...
  }

  epics_softioc::ioc { 'mysoftioc2':
    ...
    run_make_after_pkg_update => false,
  }

In this example mysoftioc1 will automatically be recompiled (and restarted if auto_restart_ioc is true) when Puppet installs a new version of the epics-autosave-dev package.

`startscript`

Base file name of the IOC start script. This defaults to st.cmd.

`systemd_after`

Ensures the IOC service is started after the specified systemd units have been activated. Please specify an array of strings. Default: network.target.

This parameter is ignored on systems that are not using systemd.

Note: This enforces only the correct order. It does not cause the specified targets to be activated. Also see systemd_requires.

`systemd_requires`

Ensures the specified systemd units are activated when this IOC is started. Default: network.target.

This parameter is ignored on systems that are not using systemd.

Note: This only ensures that the required services are started. That generally means that systemd starts them in parallel to the IOC service. Please use systemd_after to ensure they are started before the IOC is started.

`systemd_requires_mounts_for`

Ensures the specified paths are accessible (e.g. the corresponding file systems are mounted) when this IOC is started. Specify an array of strings. Default: [].

This parameter is ignored on systems that are not using systemd.

`uid`

Defines the system user id the IOC process is supposed to run with. The corresponding user is created automatically. If you leave this undefined an arbitrary user id will be picked. This argument is only used if manage_user is true.

`username`

The user name the IOC will run as. By default softioc-<ioc_name> is being used.

Contact

Author: Martin Konrad

Name		Name	Last commit message	Last commit date
Latest commit History 113 Commits
lib/facter		lib/facter
manifests		manifests
spec		spec
templates/etc		templates/etc
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitlab-ci.yml		.gitlab-ci.yml
.pdkignore		.pdkignore
.puppet-lint.rc		.puppet-lint.rc
.rspec		.rspec
.rubocop.yml		.rubocop.yml
.travis.yml		.travis.yml
.yardopts		.yardopts
Gemfile		Gemfile
LICENSE		LICENSE
README.md		README.md
Rakefile		Rakefile
appveyor.yml		appveyor.yml
metadata.json		metadata.json

License

frib-high-level-controls/mark0n-epics_softioc

Folders and files

Latest commit

History

Repository files navigation

Environment Variables

Examples

Simple

Complex

Reference

Class epics_softioc

gid

iocbase

Defined Type epics_softioc::ioc

abstopdir

auto_restart_ioc

autosave_base_dir

bootdir

ca_addr_list

ca_auto_addr_list

ca_max_array_bytes

cfg_append

console_port

coresize

enable_console_port

enable_unix_domain_socket

ensure

enable

env_vars

log_port

log_server

ca_sec_file

logrotate_compress

logrotate_rotate

logrotate_size

manage_autosave_dir

manage_user

procserv_log_file

run_make

run_make_after_pkg_update

unix_domain_socket

Example

startscript

systemd_after

systemd_requires

systemd_requires_mounts_for

uid

username

Contact

About

Topics

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Languages

Class `epics_softioc`

`gid`

`iocbase`

Defined Type `epics_softioc::ioc`

`abstopdir`

`auto_restart_ioc`

`autosave_base_dir`

`bootdir`

`ca_addr_list`

`ca_auto_addr_list`

`ca_max_array_bytes`

`cfg_append`

`console_port`

`coresize`

`enable_console_port`

`enable_unix_domain_socket`

`ensure`

`enable`

`env_vars`

`log_port`

`log_server`

`ca_sec_file`

`logrotate_compress`

`logrotate_rotate`

`logrotate_size`

`manage_autosave_dir`

`manage_user`

`procserv_log_file`

`run_make`

`run_make_after_pkg_update`

`unix_domain_socket`

`startscript`

`systemd_after`

`systemd_requires`

`systemd_requires_mounts_for`

`uid`

`username`

Packages