Added different addgroup/adduser commands for Debian authored by Caleb Wheeler's avatar Caleb Wheeler
This document will instruct the user on the post install setup of a Debian 10 Front-End computer used in a standalone test stand environment.
**For this documentation, our front end computer will be named ‘x2fec’**
# Update /etc/apt/sources.list
If there is a line trying to read packages from a DVD or CD, comment it out.
If these lines don't exist, add them
For bullseye:
```
deb http://deb.debian.org/debian/ bullseye main
deb http://deb.debian.org/debian/ bullseye-updates main
```
For buster:
```
deb http://deb.debian.org/debian/ buster main
```
# update package
Run the following:
```
apt-get update
```
All sources should load without error.
If there are any packages that need updating, update with
```
apt-get dist-upgrade
```
# Create 'controls' user and group
Log into the new front end as root. At the command line, type the following as root:
```plaintext
groupadd -g 1001 controls
useradd -u 1001 -s /bin/bash -m -g controls controls
passwd controls
```
# install some helpful packages
```
apt install vim emacs tmux sudo
```
**Note: The LIGO standard UID for controls is 1001 across all systems. Any hosts connected to the FEC should follow this standard**
Add 'controls' and 'cdsadmin' user to sudo group. Create /etc/sudoers.d/users with the following:
```plaintext
cdsadmin ALL=(ALL) NOPASSWD: ALL
controls ALL=(ALL) NOPASSWD: ALL
```
**_From this point on, we will be using the ‘controls’ user with sudo privileges to enter the commands. Commands will be entered into the command line and will be denoted with the prefix ‘controls@x2fec’_**
# Create CDS directories
as controls
```plaintext
sudo mkdir /opt/cdscfg /opt/rtcds /opt/rtapps
sudo chown -R controls:controls /opt/cdscfg /opt/rtcds /opt/rtapps
sudo mkdir -p /frames/full /frames/trend /frames/trend/minute /frames/trend/minute_raw /frames/trend/second
```
# Setup CDS Repositories for Debian 10
Instructions for CDS repositories setup can be found [here](https://git.ligo.org/cds/software/advligorts/-/wikis/Enabling-Debian-CDS-Software-Repositories)
# Create site, ifo directories
Modify the commands below to fit your ifo and site, as controls:
```
export SITE=TST
export site=tst
export IFO=X1
export ifo=x1
```
```plaintext
mkdir -p /opt/rtcds/$site/$ifo/chans/daq/archive
mkdir -p /opt/rtcds/$site/$ifo/log
mkdir -p /opt/rtcds/$site/$ifo/scripts
mkdir -p /opt/rtcds/$site/$ifo/chans/tmp
mkdir -p /opt/rtcds/$site/$ifo/chans/ipc
mkdir -p /opt/rtcds/$site/$ifo/rtbuild
mkdir -p /opt/rtcds/$site/$ifo/medm
mkdir -p /opt/rtcds/$site/$ifo/target/gds/bin
mkdir -p /opt/rtcds/$site/$ifo/target/gds/param
```
# Install Required Software
It is recommended to copy and paste the command below
```plaintext
sudo apt-get install nfs-common nfs-kernel-server subversion ntp dkms build-essential cmake pkg-config psmisc linux-headers-$(uname -r) flex bison ldas-tools-al-dev ldas-tools-framecpp-dev libboost-all-dev git
```
# Setup NFS export of /opt/rtcds directory
The FEC exports the /opt/rtcds directory to the directly connected workstation, insert workstation ip into `<workstation-ip>`. Directions for mounting the NFS mount on the workstation will be included in the workstation setup instructions.**If you are configuring your front-end as a cymac (front-end and workstation on the same host), you can skip this step.**
Add the following content to `/etc/exports` and run `/usr/sbin/exportfs -a`. Restart the nfs-server.service.
```plaintext
sudo cat /etc/exports
/opt/rtcds <workstation-ip>(rw,sync,no_subtree_check)
```
after /etc/exports is modified, update the ntp server with:
```
sudo /usr/sbin/exportfs -a
sudo systemctl status nfs-server.service
```
# Setup NTP
The front-end needs to be synced to an NTP source. You need to know the address of the local NTP server. At the IFOs, this may be the core router.
Define server in /etc/ntp.conf. Examples are server ntp.ligo-la.caltech.edu server lesath.ligo.caltech.edu server ntp.stanford.edu
# Install advligorts packages, Setup RCG
**Option A** - Install from packages
If you will not be doing RCG code development, but you are using Debian 10 or later, just check out the package
these are enough for a standalone (CyMAC) system.
```plaintext
sudo apt-get install advligorts-rcg advligorts-cpu-isolator-dkms advligorts-daqd
```
Install these also if the front end is not a standalone, i.e. if the DAQ will run on a different server.
```
sudo apt-get install advligorts-transport-common advligorts-transport-pubsub
```
**Option B** - Install master from Git repository If you are going to do development, especially on Debian 8 and newer, use a git checkout Create the 'rtscore' directory for it and go to it
```plaintext
controls@x2fec $ cd /opt/rtcds
controls@x2fec /opt/rtcds $ mkdir rtscore
controls@x2fec /opt/rtcds $ cd rtscore
```
Now clone the repo
```plaintext
controls@x2fec /opt/rtcds/rtscore $ git clone https://git.ligo.org/cds/advligorts
controls@x2fec /opt/rtcds/rtscore $ ln -s advligorts release
```
# Setup Environment variables
## lowercase vars
At the top of ```/etc/advligorts/env``` and ```/etc/advligorts/systemd_env```, make sure lowercase vars ```ifo``` and ```site``` are set as in this example:
```
SITE=TST
IFO=X1
site=tst
ifo=x1
```
## Set RCG_LIB_PATH
You will also need to set the RCG_LIB_PATH environment variable for the controls user. This can be set in ```/etc/advligorts/env```
with the following addition.
```plaintext
# LIGO site environment files with hand-curated model paths
if [ $BASH_VERSION ] ; then
if [ -e /opt/rtcds/userapps/release/etc/userapps-user-env.sh ] ; then
source /opt/rtcds/userapps/release/etc/userapps-user-env.sh
fi
fi
# Prefer USERAPPS_LIB_PATH for user model paths.
# LIGO sites use USERAPPS_LIB_PATH
# but fall back on RCG_LIB_PATH if USERAPPS_LIB_PATH
# is undefined
export RCG_LIB_PATH=${USERAPPS_LIB_PATH:-$RCG_LIB_PATH}
# make sure model host parameter is correct
CHECK_MODEL_IN_HOST=true
```
## add environment to controls bashrc
At the top of ```/home/controls/.bashrc``` add
```
# add CDS environment
if [ -e /etc/advligorts/env ]; then
source /etc/advligorts/env
fi
# ensure new files are group writeable
umask 0002
```
# finish user groups
Add the controls user to the advligorts group and vice versa
```plaintext
sudo usermod -a -G advligorts controls
sudo usermod -a -G controls advligorts
```
# Install userapps
Checkout trunk of cds_user_apps (this will take a long time) using Subversion
```plaintext
cd /opt/rtcds
mkdir userapps
cd userapps
```
then checkout the userapps directory from svn. You will need a kerberos name and password.
```
svn co https://redoubt.ligo-wa.caltech.edu/svn/cds_user_apps/trunk
ln -s trunk release
```
# Install EPICS Base
We will get the Base and the python scripts that go with it
```plaintext
sudo apt-get install epics-dev epics-seq-dev epics-asyn-dev medm striptool caqtdm epics-extensions-dev python3-pyepics python3-pcaspy epics-pcas-dev
```
## Install ezca, add soft-links (skip for CyMAC or standalone)
To build the real-time models, you also need the EPICS ezca package. However, this currently installs a level down at '/usr/lib/epics/extensions', so we need to add soft-links at /usr/lib/epics directories
```plaintext
sudo apt install epics-ezca-dev
cd /usr/lib/epics
cd include
sudo ln -s ../extensions/include/ezca.h ezca.h
cd ../lib/linux-x86_64
sudo ln -s ../../extensions/lib/x86_64-linux-gnu/libezca.h libezca.h
sudo ln -s ../../extensions/lib/x86_64-linux-gnu/libezca.so.3.15.3 libezca.so
```
# Install caRepeater service
We want to make sure caRepeater starts on boot. The file 'caRepeater.service' comes with EPICS base 3.15.5 and later. It needs to be customized to location of caRepeater. Create the file `/etc/systemd/system/caRepeater.service` with the following contents
```plaintext
#
# Linux systemd service file for the EPICS CA Repeater
#
# To install this file, as root:
# cp caRepeater.service /etc/systemd/system
# chmod 664 /etc/systemd/system/caRepeater.service
# systemctl daemon-reload
# systemctl enable caRepeater
# systemctl start caRepeater
#
# To check the status:
# systemctl status caRepeater
[Unit]
Description=EPICS CA Repeater
Requires=network.target
After=network.target
[Service]
ExecStart=/usr/bin/caRepeater
Restart=always
User=daemon
[Install]
WantedBy=multi-user.target
```
After creating the file in the above directory, complete the install by enabling the service to start at boot and starting the service now.
```plaintext
sudo chmod 664 /etc/systemd/system/caRepeater.service
sudo systemctl daemon-reload
sudo systemctl enable --now caRepeater
```
# CPU isolation
[Instructions](https://git.ligo.org/cds/software/advligorts/-/wikis/CPU-Isolation)
# Final housekeeping
To ensure we have the correct read and write permissions, perform the following commands
```plaintext
sudo chown -R advligorts:advligorts /frames/
sudo chown -R controls:advligorts /opt/rtcds/$site/
sudo chmod -R 0774 /opt/rtcds/$site/$ifo/
```
# Setup the DAQ
This document will instruct the user on the post install setup of a Debian 10 Front-End computer used in a standalone test stand environment.
**For this documentation, our front end computer will be named ‘x2fec’**
# Update /etc/apt/sources.list
If there is a line trying to read packages from a DVD or CD, comment it out.
If these lines don't exist, add them
For bullseye:
```
deb http://deb.debian.org/debian/ bullseye main
deb http://deb.debian.org/debian/ bullseye-updates main
```
For buster:
```
deb http://deb.debian.org/debian/ buster main
```
# update package
Run the following:
```
apt-get update
```
All sources should load without error.
If there are any packages that need updating, update with
```
apt-get dist-upgrade
```
# Create 'controls' user and group
Log into the new front end as root. At the command line, type the following as root:
## Rocky
```plaintext
groupadd -g 1001 controls
useradd -u 1001 -s /bin/bash -m -g controls controls
passwd controls
```
## Debian (bullseye, Debian 11)
```plaintext
/usr/sbin/addgroup --gid 1001 controls
/usr/sbin/adduser --uid 1001 --shell /bin/bash --ingroup controls controls
```
# install some helpful packages
```
apt install vim emacs tmux sudo
```
**Note: The LIGO standard UID for controls is 1001 across all systems. Any hosts connected to the FEC should follow this standard**
Add 'controls' and 'cdsadmin' user to sudo group. Create /etc/sudoers.d/users with the following:
```plaintext
cdsadmin ALL=(ALL) NOPASSWD: ALL
controls ALL=(ALL) NOPASSWD: ALL
```
**_From this point on, we will be using the ‘controls’ user with sudo privileges to enter the commands. Commands will be entered into the command line and will be denoted with the prefix ‘controls@x2fec’_**
# Create CDS directories
as controls
```plaintext
sudo mkdir /opt/cdscfg /opt/rtcds /opt/rtapps
sudo chown -R controls:controls /opt/cdscfg /opt/rtcds /opt/rtapps
sudo mkdir -p /frames/full /frames/trend /frames/trend/minute /frames/trend/minute_raw /frames/trend/second
```
# Setup CDS Repositories for Debian 10
Instructions for CDS repositories setup can be found [here](https://git.ligo.org/cds/software/advligorts/-/wikis/Enabling-Debian-CDS-Software-Repositories)
# Create site, ifo directories
Modify the commands below to fit your ifo and site, as controls:
```
export SITE=TST
export site=tst
export IFO=X1
export ifo=x1
```
```plaintext
mkdir -p /opt/rtcds/$site/$ifo/chans/daq/archive
mkdir -p /opt/rtcds/$site/$ifo/log
mkdir -p /opt/rtcds/$site/$ifo/scripts
mkdir -p /opt/rtcds/$site/$ifo/chans/tmp
mkdir -p /opt/rtcds/$site/$ifo/chans/ipc
mkdir -p /opt/rtcds/$site/$ifo/rtbuild
mkdir -p /opt/rtcds/$site/$ifo/medm
mkdir -p /opt/rtcds/$site/$ifo/target/gds/bin
mkdir -p /opt/rtcds/$site/$ifo/target/gds/param
```
# Install Required Software
It is recommended to copy and paste the command below
```plaintext
sudo apt-get install nfs-common nfs-kernel-server subversion ntp dkms build-essential cmake pkg-config psmisc linux-headers-$(uname -r) flex bison ldas-tools-al-dev ldas-tools-framecpp-dev libboost-all-dev git
```
# Setup NFS export of /opt/rtcds directory
The FEC exports the /opt/rtcds directory to the directly connected workstation, insert workstation ip into `<workstation-ip>`. Directions for mounting the NFS mount on the workstation will be included in the workstation setup instructions.**If you are configuring your front-end as a cymac (front-end and workstation on the same host), you can skip this step.**
Add the following content to `/etc/exports` and run `/usr/sbin/exportfs -a`. Restart the nfs-server.service.
```plaintext
sudo cat /etc/exports
/opt/rtcds <workstation-ip>(rw,sync,no_subtree_check)
```
after /etc/exports is modified, update the ntp server with:
```
sudo /usr/sbin/exportfs -a
sudo systemctl status nfs-server.service
```
# Setup NTP
The front-end needs to be synced to an NTP source. You need to know the address of the local NTP server. At the IFOs, this may be the core router.
Define server in /etc/ntp.conf. Examples are server ntp.ligo-la.caltech.edu server lesath.ligo.caltech.edu server ntp.stanford.edu
# Install advligorts packages, Setup RCG
**Option A** - Install from packages
If you will not be doing RCG code development, but you are using Debian 10 or later, just check out the package
these are enough for a standalone (CyMAC) system.
```plaintext
sudo apt-get install advligorts-rcg advligorts-cpu-isolator-dkms advligorts-daqd
```
Install these also if the front end is not a standalone, i.e. if the DAQ will run on a different server.
```
sudo apt-get install advligorts-transport-common advligorts-transport-pubsub
```
**Option B** - Install master from Git repository If you are going to do development, especially on Debian 8 and newer, use a git checkout Create the 'rtscore' directory for it and go to it
```plaintext
controls@x2fec $ cd /opt/rtcds
controls@x2fec /opt/rtcds $ mkdir rtscore
controls@x2fec /opt/rtcds $ cd rtscore
```
Now clone the repo
```plaintext
controls@x2fec /opt/rtcds/rtscore $ git clone https://git.ligo.org/cds/advligorts
controls@x2fec /opt/rtcds/rtscore $ ln -s advligorts release
```
# Setup Environment variables
## lowercase vars
At the top of ```/etc/advligorts/env``` and ```/etc/advligorts/systemd_env```, make sure lowercase vars ```ifo``` and ```site``` are set as in this example:
```
SITE=TST
IFO=X1
site=tst
ifo=x1
```
## Set RCG_LIB_PATH
You will also need to set the RCG_LIB_PATH environment variable for the controls user. This can be set in ```/etc/advligorts/env```
with the following addition.
```plaintext
# LIGO site environment files with hand-curated model paths
if [ $BASH_VERSION ] ; then
if [ -e /opt/rtcds/userapps/release/etc/userapps-user-env.sh ] ; then
source /opt/rtcds/userapps/release/etc/userapps-user-env.sh
fi
fi
# Prefer USERAPPS_LIB_PATH for user model paths.
# LIGO sites use USERAPPS_LIB_PATH
# but fall back on RCG_LIB_PATH if USERAPPS_LIB_PATH
# is undefined
export RCG_LIB_PATH=${USERAPPS_LIB_PATH:-$RCG_LIB_PATH}
# make sure model host parameter is correct
CHECK_MODEL_IN_HOST=true
```
## add environment to controls bashrc
At the top of ```/home/controls/.bashrc``` add
```
# add CDS environment
if [ -e /etc/advligorts/env ]; then
source /etc/advligorts/env
fi
# ensure new files are group writeable
umask 0002
```
# finish user groups
Add the controls user to the advligorts group and vice versa
```plaintext
sudo usermod -a -G advligorts controls
sudo usermod -a -G controls advligorts
```
# Install userapps
Checkout trunk of cds_user_apps (this will take a long time) using Subversion
```plaintext
cd /opt/rtcds
mkdir userapps
cd userapps
```
then checkout the userapps directory from svn. You will need a kerberos name and password.
```
svn co https://redoubt.ligo-wa.caltech.edu/svn/cds_user_apps/trunk
ln -s trunk release
```
# Install EPICS Base
We will get the Base and the python scripts that go with it
```plaintext
sudo apt-get install epics-dev epics-seq-dev epics-asyn-dev medm striptool caqtdm epics-extensions-dev python3-pyepics python3-pcaspy epics-pcas-dev
```
## Install ezca, add soft-links (skip for CyMAC or standalone)
To build the real-time models, you also need the EPICS ezca package. However, this currently installs a level down at '/usr/lib/epics/extensions', so we need to add soft-links at /usr/lib/epics directories
```plaintext
sudo apt install epics-ezca-dev
cd /usr/lib/epics
cd include
sudo ln -s ../extensions/include/ezca.h ezca.h
cd ../lib/linux-x86_64
sudo ln -s ../../extensions/lib/x86_64-linux-gnu/libezca.h libezca.h
sudo ln -s ../../extensions/lib/x86_64-linux-gnu/libezca.so.3.15.3 libezca.so
```
# Install caRepeater service
We want to make sure caRepeater starts on boot. The file 'caRepeater.service' comes with EPICS base 3.15.5 and later. It needs to be customized to location of caRepeater. Create the file `/etc/systemd/system/caRepeater.service` with the following contents
```plaintext
#
# Linux systemd service file for the EPICS CA Repeater
#
# To install this file, as root:
# cp caRepeater.service /etc/systemd/system
# chmod 664 /etc/systemd/system/caRepeater.service
# systemctl daemon-reload
# systemctl enable caRepeater
# systemctl start caRepeater
#
# To check the status:
# systemctl status caRepeater
[Unit]
Description=EPICS CA Repeater
Requires=network.target
After=network.target
[Service]
ExecStart=/usr/bin/caRepeater
Restart=always
User=daemon
[Install]
WantedBy=multi-user.target
```
After creating the file in the above directory, complete the install by enabling the service to start at boot and starting the service now.
```plaintext
sudo chmod 664 /etc/systemd/system/caRepeater.service
sudo systemctl daemon-reload
sudo systemctl enable --now caRepeater
```
# CPU isolation
[Instructions](https://git.ligo.org/cds/software/advligorts/-/wikis/CPU-Isolation)
# Final housekeeping
To ensure we have the correct read and write permissions, perform the following commands
```plaintext
sudo chown -R advligorts:advligorts /frames/
sudo chown -R controls:advligorts /opt/rtcds/$site/
sudo chmod -R 0774 /opt/rtcds/$site/$ifo/
```
# Setup the DAQ
[DAQ Setup](DAQ-Setup)
\ No newline at end of file