Editing CODA Setup

==Installation Instructions==

Below we have compiled a guide that walks through a basic setup of CODA 2.6.2. Our intention in writing this walkthrough is to assist CNU physics undergraduates in setting up a simple data acquisition system. The guide is geared toward first time Linux users, however for those users who are more advanced, the basic process may still be helpful. 

Notes: 

'''1. Operating System:''' For this guide we used CentOs 6.5, but any Linux distribution should be okay. (Some of the syntax and directory locations may change)

'''2. CODA Version:''' CODA 2.6.2

'''3. Hosted Files:''' Some sections we will have <span style="color:green">'''Links'''</span> that list examples of various files or websites that may be used for reference. 

'''4. Terminal Commands & Changes:''' We will be using a dollar sign ($) to signify a prompt for the regular user accounts, and a pound sign (#) for the root user. Also, we used greater than (>) and less than (<) symbols to signify user input.  

Example User: [coda@jlabdaq ~]$

Example Root User: [root@jlabdaq ~]#

Example User Input: <codauser>

'''6. Text Editor:''' For a quick text editor we used vi. If you are unfamiliar with vi, one can easily look up the commands or use any text editor that you prefer (i.e. emacs, gedit, etc).

'''5. Troubleshooting/Hints:''' We have added <span style="color:red">'''Possible Issue'''</span> and <span style="color:blue">'''Hint'''</span> sections to help with the installation process.   

'''6. Patience:''' Some portions of CODA (i.e. cedit and debedit) are finicky and take practice to learn how to handle/tolerate them.

==Our Setup==

Throughout the guide we will be using our own configuration to act as an example. Below we have listed our configuration outline: 

'''Experiment:''' Cosmic Ray Detector using two scintillator paddles with four PMTs.

VME Crate: 

'''1. Linux Controller Name:''' jlabvme (CentOs 5.8, i686)

'''2. ADC/TDC:''' v792n/v775n

'''3. Signal Units/Voltage:''' 1 FIFO, 1 CFD, 1 Delay Unit, 1 Quad Four Fold Logic Unit, 1 NIM/ECL Translator, 1 Trigger Interface, 1 HV Unit

Analysis/CODA Computer:  

'''1. Hostname/Computer Name:''' jlabdaq (CentOs 6.5, x86_64)

'''2. CODA Account:''' coda

Database: 

'''1. Database Name:''' PCSE

'''2. Configuration:''' ADCTDC

'''3. Session:''' Luter345

==Setting Up the Computer==

===BIOS Settings===


1. Enable the BIOS preference to boot from an external drive.
 
<span style="color:blue">'''Hint:''' Some older machines may not be able to boot from a USB Drive, instead a disc will be needed. </span>

2. Make sure that the USB ports are visible

===Downloading CentOs & Preparing the Computer===

====STEP 1: Installation====

i.	Click Next on the Centos logo page

ii.	Chose Basic Storage Devices, then click next 

iii.	Chose your installation preference, then click next

iv.	Chose a hostname (name of computer) 

v.	Select the time

vi.	Make a root password

vii.	Now select which type of installation you would like

viii.	Select your hard drive to install target devices

ix.	Then click on boot loader option (small button top left corner in the right window) 

x.	Writing storage configuration to disk, select write changes 

xi.	After some time, select which installation you would like: Desktop is ideal for this setup

xii.	Then wait for the installation to complete

====STEP 2: Create First User====

i.	First user account is going to be the bash shell analysis account (i.e. root, geant4, etc.) 

ii.	Skip the full name portion

iii.	Select date and time

<span style="color:red">'''Possible Issue:''' An error may occur upon selecting the time (CentOs). It is okay to ignore this message for our purposes.</span>

iv.	Click finish on the kdump screen

====STEP 3: Installing Libraries and Updating====
 
i.	Turn on the connection to the internet  

    1.	Go to system, preferences, network connections (GUI)
    2.	Double click System eth0
    3.	Select Connect Automatically and Available for all Users
    4.	Click Apply
    5.	Enter root password to save the information 

ii.	Turn off screen saver (Optional)

    1.	Go to system, preferences, screensaver
    2.	Uncheck the lock option when the computer goes to the screensaver
    3.	Change the elapsed time for the screensaver (~ 40 minutes)
    4.	Click Close

iii.	Open new shell (terminal)

        <span style="color:blue">'''Hint:''' Make sure that you are super user, connected to the internet, and are in the home directory </span>

    1.	$ su
    2.	$ <root password> 
<span style="color:green">'''Link:''' [[Setup Files#Library Script|Library Script]]</span>
    3.	Run the libraries script : # ./lib32_install.sh 
    5. <span style="color:red">  '''Possible Issue:''' DATABASE DISK IMAGE IS MALFORMED. Normally this can be ignored for our purposes.</span>	 
    6.	Once the script is done installing: # yum –y update
    7.	# exit

====STEP 4: Create Second User Account (tcsh)====

i.	Go to system, administration, users and groups (GUI)

ii.	Enter the root user password

iii.	Click Add User

iv.	Enter a username 

v.	No need to enter a full name

vi.	Enter a password

vii.	Change login shell to tcsh

====STEP 5: Network Settings====

i.	Go to system/preferences/network connections (GUI)

ii.	Double click System eth0

iii.	Click ipv4 settings tab

iv.	Method Dropdown: Change from DHCP to manual

v.	Press add button under Addresses 

<span style="color:blue">'''Hint:''' This network setup is meant for a CNU configuration.</span>

vi.	Enter the address: 137.155.2.XX, netmask: 255.255.255.0, and gateway for your network (may need to contact administrator):137.155.2.4 

vii.	Enter the DNS server addresses: 137.155.2.50, 137.155.2.14 (may need administrator)

viii.	Enter the search domain: pcs.cnu.edu (may need administrator)

ix.	Click apply

x.	Enter root password

====STEP 6: Hosts File Changes====

i.	$ su

ii.	$ <root password>

iii.	# vi /etc/hosts

iv.	Within the file add this line: <ip address> <domain name> <computer name>

    1.	Go to a new line in the file
    2.	Example: 137.155.2.58 jlabvme.pcs.cnu.edu jlabvme
    3.	Both computers need to be in the hosts file (i.e. jlabdaq & jlabvme)

v.	Save the file and exit

vi.	# exit

vii.	$ ssh root@jlabvme

viii.	$ <enter password for root@jalbvme>

ix.	# vi /etc/hosts

<span style="color:green">'''Link:''' [[Setup Files#Hosts File|Hosts File]]</span>

x.	Within the hosts file add this line: <ip address> <domain name> <computer name>

xi.	Save the file and exit

xii.	#exit

xiii. Any computers that you wish to ssh into, make sure that they are added to the hosts file.

====STEP 7: Turn Off Firewall (Otherwise add exceptions for the specific machines)====

i.	Go to system/administration/firewall (GUI) 

ii.	Enter root password

iii.	Click Disable

iv.	Click Apply (Look top left corner)

====STEP 8: SSH Without Password====
 
i.	Login to CODA Account

ii.	We are now switching so that all permissions are set to our CODA user account.
 
iii.	Open a new shell (terminal)

iv.	$ su

v.	$ <root password>

vi.	# /sbin/service sshd start

vii.	# exit

viii.	<span style="color:blue">'''Hint:''' Make sure you are in the home directory:  /home/<username></span>

ix.	$ ssh-keygen –t rsa

x.	$ <Press enter three times>

xi.	$ cat .ssh/id_rsa.pub | ssh root@jlabvme ‘cat >> .ssh/authorized_keys’

xii.	type yes

xiii.	$ ssh root@jlabvme “chmod 700 .ssh; chmod 640 .ssh/authorized_keys”

xiv.	$ ssh root@jlabvme

xv.	# exit

xvi. 	Back on the CODA user account: $ ssh-add

<span style="color:green">'''Link:''' If help is needed: http://www.tecmint.com/ssh-passwordless-login-using-ssh-keygen-in-5-easy-steps/</span>

==Installing CODA==

===Downloading & Preparing CODA===

====STEP 1: Downloading CODA====

i.	Make sure that you are a user in tcsh

ii.	Go to the jlab’s CODA wiki and download CODA 2.6.2

iii.	<span style="color:green">'''Link:''' https://coda.jlab.org/wiki/index.php/CODA_2.6.2_Downloads</span>  

iv.	Open a new shell (terminal)

v.	$ su

vi.	$ <root password>

vii.	# mkdir /usr/local/coda

viii.	# mv /home/<username>/Downloads/coda_2.6.2.tar.gz /usr/local/coda

ix.	# cd /usr/local/coda

x.	# tar –xf coda_2.6.2.tar.gz

xi.	# exit

====STEP 2: Making Directories for CODA====

i.	Open a new shell (terminal)

ii.	$ mkdir /home/<codauser>/bin

iii.	$ mkdir /home/<codauser>/msql

iv.	$ mkdir  /home/<codauser>/CODA

v.	$ mkdir /home/<codauser>/CODA/cool

vi.	$ mkdir /home/<codauser>/CODA/data

====STEP 3: Setting Up Environment Variables====

i.	Edit an example setup file to set up the environment variables (dosetupcoda262) 

<span style="color:green">'''Link:''' [[Setup Files#Environment Variables (dosetupcoda262)|Environment Variables (dosetupcoda262)]]</span>

ii.	Put dosetupcoda262 in the coda user’s home directory

iii.	Edit dosetupcoda262 with the following:

    1.	Variables that need editing:
     a.	MSQL_TCP_HOST <hostname>
     b.	MSQL_HOME /home/<codauser>/msql
     c.	EXPID <PCSE>
     d.	SESSION <Luter345>
     e.	CODA_DIRECTORY /home/<codauser>/CODA
     f.	CODADATA /home/<codauser>/CODA/data

iv.	Create a .tcshrc file in the home directory that sources dossetupcoda262

<span style="color:green">'''Link:''' [[Setup Files#.tcshrc|.tcshrc]]</span>

    1.	$ vi ~/.tcshrc
    2.	Include the following line in the file:
    3.	LIST WHAT GOES IN THIS
    4.	source {$HOME}/dosetupcoda262
    5.	<span style="color:blue">'''Hint:''' .tcshrc is a hidden file, to list it: $ ls -a </span>
    6.	To test if the sourcing worked properly, open a new shell to see if coda and AFECS is listed at the top of the window

====STEP 4: MSQL Setup====

i.	Starting the msql database

    1.	<span style="color:blue">'''Hint:''' The database must be running at all times. If the program is disrupted, the port that it is using will be left open. </span>
         <span style="color:blue">If this occurs, kill the msql process and re-launch the database.</span> 
    2.	Open a new shell (terminal) 
    3.	$ msqld
    4.	Rename the window ''msql'' for clarity

====STEP 5: Changing Soft Link for Problem Library (cedit)==== 

i.	Open new shell (terminal) 

    1.	$ su
    2.	$ <root password>
    3.	# cd /usr/lib
    4.	# ln –s libXm.so.4 libXm.so.3
    5.	This will create a soft link for the particular library that we need. (Previously used library: libXm.so.3.0.2)

====STEP 6: Cedit (GUI for database; Must be running msqld)====

i.	Open a new shell (terminal)

ii.	$ cedit

<span style="color:red">'''Possible Issue:''' If cedit does not open and throws an error: check if the database is running, the proper directories were made with the correct ownership, and that there are no missing libraries/links. </span>

iii.	Click: File->New Database

iv.	Name the database <database name>

v.	Create a new configuration

vi.	Click: File->New

vii.	Name the configuration <config name>

viii.	Create a basic setup: ROC, EB, ER, and a data file

ix.	See working example. 

<span style="color:green">'''Link:''' [[ADCTDC Configuration#CEDIT|CEDIT]]</span>

====STEP 7: Dbedit (text version of the database)====

i.	Open a new shell (terminal)

ii.	$ dbedit

iii.	Select local host from dropdown

iv.	Select <database name> from dropdown

v.	Compare all sections against a working example

<span style="color:green">'''Link:''' [[ADCTDC Configuration#DBEDIT|DBEDIT]]</span>

====STEP 8: NFS (Export the file systems from jlabdaq to jlabvme)====

i.	Open a new shell (terminal)

ii.	$ su

iii.	$ <root password>

iv.	# vi /etc/exports

<span style="color:green">'''Link:''' [[Setup Files#Exports File|Exports File]]</span>

<span style="color:blue">'''Hint:''' This is a CNU network configuration.</span> 

v.	Edit this file by adding these lines:

    1.	/home 137.155.2.0/255.255.255.0(rw,sync,no_root_squash)
    2.	/usr/local/coda 137.155.2.0/255.255.255.0(rw,sync,no_root_squash)
    3.	/usr/lib/jvm 137.155.2.0/255.255.255.0(rw,sync,no_root_squash)

vi.	Save and exit the file

vii.	<span style="color:blue">'''Hint:''' start NFS while super user</span> 

viii.	# /sbin/chkconfig --levels 345 nfs on

ix.	Check if NFS is on: # /sbin/chkconfig --list nfs status

x.	# /etc/init.d/nfs start

xi.	# exit

xii.	ssh into jlabvme: $ ssh root@jlabvme

xiii.	# vi /etc/fstab

<span style="color:green">'''Link:''' [[Setup Files#fstab File|fstab File]]</span>

xiv.	Add these lines in preparation for mounting

    1.    jlabdaq:/home                 /daqhome           nfs            rw,sync       0 0
    2.    jlabdaq:/usr/local/coda      /usr/local/coda    nfs            defaults       0 0
    3.    jlabdaq:/usr/lib/jvm       /usr/lib/jvm         nfs            defaults       0 0

xv.	Make the directories that were specified above

    1.    # mkdir /daqhome
    2.    # mkdir /usr/local/coda
    3.    # mkdir /usr/lib/jvm

xvi.	# mount –a

xvii.	Proper sourcing in jlabvme

    1.    Create a new environment variable file on jlabvme that has the NFS mounted directories. (We named ours coda_Luter345)  
    2.    <span style="color:green">'''Link:''' [[Setup Files#Environment Variables On jlabvme (coda_Luter345)|Environment Variables On jlabvme (coda_Luter345)]]</span>
    3.    Once the the environment variables are set, they must be sourced
    4.    Create a new script that sources coda_Luter345 (We named ours setLuter345.sh)
    5.    <span style="color:green">'''Link:''' [[Setup Files#setLuter345.sh|setLuter345.sh]]</span>

== Starting and Killing CODA ==

=== What needs to run? ===

In order to properly start CODA one must first run the following processes:

<span style="color:blue">'''Hint:''' Make sure that each of these processes is run independently in their own shell. </span>

1. To start database (new terminal): $ msqld

<span style="color:blue">'''Hint:''' Leave the database running, it does not need to be turned off. </span>

2. Remove session file (new terminal): $ rm /tmp/et_sys_$SESSION

<span style="color:blue">'''Hint:''' This file needs to be removed every time '''et_start''' is run. However, if the file has never been created, it will throw an error. It is okay to ignore this. </span> 

3. Begin the event transfer system(same terminal that you removed the session file in): $ et_start

4. Start the run control platform (new terminal): $ rcplatform

<span style="color:blue">'''Hint:''' Some time is needed for rcplatform to fully boot (about 5 seconds). Upon first running rcplatform, two prompts (within the rcplatform window) will ask the user if it is okay to start.</span> 

The next three steps allow the user to actively see the event builder, event recorder, and the readout controller. (Helpful for debugging)  

5. Start event builder (EB) (new terminal): $ coda_eb_rc3 -i -s $SESSION -name EB1 -type CDEB

6. Start event recorder (ER) (new terminal): $ coda_er_rc3 -i -s $SESSION -name ER1 -type ER

7. Start readout controller (ROC) (new terminal): $ ssh -t root@jlabvme coda_roc_rc3 -i -s $SESSION -name ROC1 -type ROC

<span style="color:blue">'''Hint:''' In step 7, the ROC must be accessed remotely using the ssh protocol.</span>

8. Start the graphical interface for the run controller (new terminal): $ rcgui

=== Bash Scripts === 

Location: '''Computer:''' jlabdaq '''User:''' coda '''Directory:''' ''home/coda/bin''

Small programs can be written in order to quickly start and end CODA in an efficient manner. To accomplish this, multiple terminals must be running in order to start various programs. Terminal emulation programs can easily solve this problem. 

Xterm is the emulator that we chose to use. 

1. StartCODA

<span style="color:green">'''Link:''' [[Setup Files#Startcoda Script|Startcoda Script]]</span>

Within the script xterm can be utilized to run multiple processes in the background. 

Example: '''xterm -bg white -fg black -geometry 96x12-0+192 -e $SHELL -c '$SHELL -c "echo Starting rcplatform; rcplatform"; read' &'''

The ampersand at the end lets the computer know to keep the process running without ending it when the script ends. Similar lines can be written in order to run all of the necessary processes.    

2. KillCODA 

<span style="color:green">'''Link:''' [[Setup Files#Killcoda Script|Killcoda Script]]</span>

Once one is ready to close CODA, a simple script can be written to end all of the processes in an orderly fashion. 

Example: '''ps wwwaux | grep rcplatform | awk '{print $2}' | xargs kill -9 &'''

Here is a statement that lists all running processes, finds the specific name, grabs the process ID, and then kills that process. This can be done for each process that was started.