========
Linux PC
========

IDCP is an
`EPICS <http://www.aps.anl.gov/epics/about.php>`_ application
that runs on an
`IOC <https://docs.epics-controls.org/en/latest/guides/EPICS_Intro.html?highlight=IOC#ioc-software-components>`.

This document describes how to set up a
`PC <https://en.wikipedia.org/wiki/Personal_computer>`_
with
`Linux <https://en.wikipedia.org/wiki/Linux>`_ for this IOC.

IDCP is tested on a
`Debian 12 ("bookworm") <https://www.debian.org/releases/bookworm/>`_
Linux system.

HTTP Proxy settings
-------------------

.. hint::
   The following information is specific for the BESSY II site, see also :doc:`Sites <sites>`.

At the HZB networks, in order to be able to connect to debian repositories
set the environment variables::

  export http_proxy=http://proxy.blc.bessy.de:3128
  export https_proxy=http://proxy.blc.bessy.de:3128

Basic setup
-----------

Create bootable image
+++++++++++++++++++++

Download a netinst ISO file here or from this link:

`Debian Network Install <https://www.debian.org/CD/netinst/>`_.

Here is an example how to copy the ISO image to an USB stick::

  cp debian.iso /dev/sdX

Install
+++++++

Boot live image and click on "Install Debian" icon:

Welcome: Select "american english"
Location: <YOUR LOCATION>
Keyboard: <DEFAULT FOR YOUR COUNTRY>
Partitions: Erase Disk (CAUTION!!! Not always the correct selection)
Users: <ADD A STANDARD INSTALLATION USER>
passwort: <MAKE UP A PASSWORD>

Then: start install

http proxy
++++++++++

If you have an HTTP proxy, the long in as the standard user, then::

  echo "export http_proxy=<YOUR PROXY>" > $HOME/setenv-proxy.sh
  echo "export https_proxy=<YOUR PROXY>" >> $HOME/setenv-proxy.sh
  source $HOME/setenv-proxy.sh

ssh setup
+++++++++

Enter::

  sudo apt-get install openssh-server
  sudo systemctl enable ssh

apt-file setup
++++++++++++++

Enter::

  apt-get install apt-file
  apt-file update

Packages
--------

Here is a set of commands to install all the required packages. Note that with
this list you can not only run IDCP but also *build* IDCP::

  sudo bash
  apt-get install bind9-host
  apt-get install mercurial
  apt-get install darcs
  apt-get install wget
  apt-get install python3-pip
  apt-get install w3m
  apt-get install neovim
  apt-get install bash-completion
  apt-get install rsync
  apt-get install libpopt-dev
  apt-get install re2c
  apt-get install python3-yaml
  apt-get install ripgrep
  apt-get install fd-find
  apt-get install python3-venv
  apt-get install libyaml-libyaml-perl
  apt-get install can-utils
  apt-get install git
  apt-get install ntp
  apt-get install ntpstat
  apt-get install ntpsec-ntpdate
  apt-get install chrony
  apt-get install procserv
  apt-get install autofs
  apt-get install sshfs
  apt-get install conserver-client
  apt-get install conserver-server
  <ctrl-d>

NTP setup
---------

The PC needs a working NTP setup for correct timestamps. Here we use "chrony".

In file /etc/chrony/chrony.conf add::

  pool YOURTIMESERVER iburst

.. hint::
   The timeserver IP address for the BESSY II site is the IP address of your
   IOC but with '18' as the last byte. See also :doc:`Sites <sites>`.

You can test if chrony is working with these commands::

  chronyc sources
  chronyc tracking

ioc user setup
--------------

.. hint::
   The user and group ID for user 'ioc' is specific for the BESSY II site, see
   also :doc:`Sites <sites>`.

The IOC should run as a specific user. I recomment to install a user "ioc" with
these commands::

  sudo groupadd -g 27000 iocs
  sudo useradd ioc -g iocs -m -s /bin/bash -u 27001
  sudo passwd ioc

The ioc user must have rights to start processes with real-time priorities. As root user create a file
``/etc/security/limits.d/security-limits-softIOC.conf`` with this content::

  ioc - rtprio unlimited
  ioc - memlock unlimited
  ioc - core unlimited

The ioc user also needs some sudo rights. Create file ``/etc/sudoers.d/ioc``
with this content::

  ioc ALL= NOPASSWD: /bin/systemctl restart ioc@*
  ioc ALL= NOPASSWD: /bin/systemctl stop ioc@*
  ioc ALL= NOPASSWD: /bin/systemctl start ioc@*
  ioc ALL= NOPASSWD: /bin/systemctl status ioc@*

.. hint::
   The following ssh setup is specific for the BESSY II site, see also
   :doc:`Sites <sites>`.

You have to be able to log in host 'stretch.acc.bessy.de' as user, ioc. Then do
as user 'ioc'::

  scp -r -p ioc@stretch.acc.bessy.de:.ssh .ssh-copy
  rm -rf .ssh && mv .ssh-copy .ssh
  ssh nfs.blc.bessy.de

Answer 'y' to the question 'add hostkey..?'.

idadm user setup
----------------

.. hint::
   The user and group ID for user 'idadm' is specific for the BESSY II site, see
   also :doc:`Sites <sites>`.

The 'idadm' user is there for administration of the insertion device.

Enter::

  sudo groupadd -g 44098 idadm
  sudo useradd idadm -g idadm -m -s /bin/bash -u 44098
  sudo passwd idadm

The idadm user also needs some sudo rights. Create file ``/etc/sudoers.d/idadm``
with this content::

  ioc ALL= NOPASSWD: /bin/systemctl restart ioc@*
  ioc ALL= NOPASSWD: /bin/systemctl stop ioc@*
  ioc ALL= NOPASSWD: /bin/systemctl start ioc@*
  ioc ALL= NOPASSWD: /bin/systemctl status ioc@*

Set up ssh::

  scp -r -p idadm@stretch.acc.bessy.de:.ssh .ssh-copy
  rm -rf .ssh && mv .ssh-copy .ssh
  ssh nfs.blc.bessy.de

Answer 'y' to the question 'add hostkey..?'.

Access to remote file system
----------------------------

You usually want to store your files not locally on the Linux PC but on a file
server.

Here I describe a method to do this with sshfs. You can, of course, also do
this with NFS or Samba.

First you need a user "ioc" on your fileserver.

The user "ioc" on the Linux PC must have a private ssh key without a
passphrase. This key must be added to file "$HOME/.ssh/authorized_keys" in the
home of user "ioc" on the file server.

Now it should be possible to log from the PC on the fileserver with ssh, ensure
that the following command works without the need to enter a password or
passphrase::

  ssh ioc@FILESERVER

Now you have to add the ssh key of user "ioc" also to user "root".

.. warning::
   The following command *overwrites* files that may already exist in directory ".ssh" of
   user root.

::

  sudo bash
  cd $HOME
  mkdir -p .ssh
  cd .ssh
  cp -a -i -b /home/ioc/.ssh/* .
  <ctrl-d>

Test if root can log on to the file server. Run as root::

  ssh ioc@FILESERVER
  <Ctrl-D>

.. hint::
   The server and directory names in the following autofs configuration are
   specific for the BESSY II site, see also :doc:`Sites <sites>`.

Now configure sshfs for the automounter. In this example directory "/opt/IOC"
on the file server is locally mounted on directory "/mnt/nfs-blc-IOC" on the
Linux PC::

  sudo bash
  echo 'nfs-blc-IOC -fstype=fuse,rw,allow_other :sshfs\#ioc@nfs.blc.bessy.de\:/opt/IOC' > /etc/autofs.sshfs
  echo "/mnt /etc/autofs.sshfs uid=$(id -u ioc),gid=$(id -g ioc),--timeout=60,--ghost" | sudo tee -a /etc/auto.master
  sudo systemctl restart autofs
  <ctrl-d>

Now test if everything works::

  ls -l /mnt/nfs-blc-IOC

You should see the files from directory "/opt/IOC" on the server.

Set up console server
---------------------

Install with::

  apt-get install conserver-client conserver-server

Edit /etc/conserver/conserver.passwd, add::

  idadm:sakyGDU6yNtyU
  tscadm:$1$ByyW4Y4m$DbVKaeOFtsGZraV/5CjnX.
  *any*:*passwd*

Edit /etc/conserver/conserver.cf, add::

  console CONSOLENAME {
          master IPADDRESS;
          timestamp 1l;
          type exec;
          exec telnet localhost 12345;
  }

In /etc/conserver/conserver.cf at the end of the file set up the 'access'
section like thos::

  access * {
          allowed 127.0.0.1, OWNNETWORK, OTHERMETWORK;
  }

Where OWNNETWORK is the CIDR notation of the Linux PC's own network, and the
optional OWNNETWORK, there may be more than one, are other network who are
allowed to access the console.

.. hint::
   CONSOLENAME and IPADDRESS depend on the installation size. At BESSY II
   CONSOLENAME is something like 'eis13g', IPADDRESS is always the IP address
   of the Linux PC. See also :doc:`Sites <sites>`.

Edit /etc/conserver/console.cf to have this content::

  # default config for console
  config * {
          master  localhost;
          port    782;
  }

Edit file /etc/conserver/server.local to have this content::

  OPTS='-p 782 '

In file /usr/lib/systemd/system/conserver-server.service out-comment the line::

  #User=conservr

.. note::
   The Logfile CONSOLENAME.log is at /var/log/conserver.

Now enable and start the service like this::

  systemctl enable conserver-server
  systemctl start conserver-server

.. hint::
   The following extra step is used at the BESSY II site to attach the console
   to our main console server configuration there. See also :doc:`Sites
   <sites>`.

In the HZB conserver project in file 'conserver.cf' at the end add these lines::

  console CONSOLENAME {
          master IPADDRESS;
          timestamp 1l;
          type exec;
          exec telnet localhost 12345;
  }

Install EPICS Base
------------------

This is done here in order to have the utilities:

- caget
- caput
- camonitor
- caRepeater

Prepare a directory::

  sudo mkdir -p /opt/EPICS
  sudo chown ioc:ioc /opt/EPICS
  mkdir -p /opt/EPICS/3.15.9
  cd /opt/EPICS/3.15.9

Download and build base::

  wget https://epics.anl.gov/download/base/base-3.15.9.tar.gz
  tar -xzf base-3.15.9.tar.gz
  rm *.tar.gz
  mv base-3.15.9 base
  make -C base -sj install

Make base utilities available::

  echo 'PATH=/opt/EPICS/3.15.9/base/bin/linux-x86_64:$PATH' >> $HOME/.bashrc

Set up caRepeater service
-------------------------

Then enter::

  sudo cp /opt/EPICS/3.15.9/base/bin/linux-x86_64/caRepeater.service /etc/systemd/system
  sudo chmod 664 /etc/systemd/system/caRepeater.service
  sudo systemctl daemon-reload
  sudo systemctl enable caRepeater
  sudo systemctl start caRepeater

Set up idcp script directory
----------------------------

Enter::

  sudo mkdir /opt/idcp-scripts
  sudo chown ioc:ioc /opt/idcp-scripts

Now provided the idcp source code is at directory IDCP-DIR, copy the CAN Bus
initialization script like this::

  cp -a IDCP-DIR/scripts/idcp-init-pcan-builtin.sh /opt/idcp-scripts

Copy the IOC start script with this command::

  cp -a IDCP-DIR/scripts/start-ioc.sh /opt/idcp-scripts

Note that this script expects the idcp application at directory
``/opt/IOC/idcp/links/$1`` where ``$1`` is the idcp key, for example ``idcp12``.

Set up CAN bus initialization service
-------------------------------------

Copy the CAN Bus service file like this::

  sudo cp -a IDCP-DIR/scripts/service/idcp-init-pcan-builtin.service /etc/systemd/system
  sudo chmod 664 /etc/systemd/system/idcp-init-pcan-builtin.service
  sudo systemctl daemon-reload
  sudo systemctl enable idcp-init-pcan-builtin
  sudo systemctl start idcp-init-pcan-builtin

Set up idcp IOC as a service
----------------------------

Copy the IOC service file like this::

  sudo cp -a IDCP-DIR/scripts/service/ioc@.service /etc/systemd/system
  sudo chmod 664 /etc/systemd/system/ioc@.service
  sudo systemctl daemon-reload

To enable the ioc you must know the idcp key. Here is an example for the UE48
undulator, which is "idcp12"::

  sudo systemctl enable ioc@idcp12
  sudo systemctl start ioc@idcp12

Console access
--------------

For now, you can access the IOC console with this command::

  telnet localhost 12345

In order to leave the telnet session enter::

  <ctrl-]>
  q