Prerequisite - Accounts 

Windows Account - this gives you access to the SLAC Office network.
Linux Account - this gives you access to the SLAC Controls network - which can only be accessed from within the Office network.

Logging onto the Controls network

• An X-windows or remote desktop application is used to log into dedicated control system Linux servers.
• Computers on the Controls Networks are considered parts of a government computer system with no expectation of privacy.
  They should never be used for personal computing (e.g. browsing the internet) or for saving personal files.
• Somewhat oversimplified network layout:
  

Log onto the Public controls server using your Linux account and password

• SLAC IT supports several methods for remote access into the SLAC networks https://confluence.slac.stanford.edu/display/SCSPub/Remote+Access - this webpage has details for how to use these methods.
  • We typically use FastX, NoMachine (NX), or direct ssh from a terminal (usually from a Mac or Linux machine) or MobaXterm (typically from a Windows machine).
• Try out the various methods for logging in, following the instructions from the Confluence page listed above.
  • FastX web https://fastx3.slac.stanford.edu:3300 - bookmark the page, then launch both a terminal and a desktop session - leave it running and close the browser tab
  • NoMachine web https://nx.slac.stanford.edu:4443 - bookmark the page, then launch both a terminal and a desktop session - leave it running and close the browser tab
  • If your computer doesn't already have them, download and install both the FastX and NoMachine desktop applications from SLAC's Software Center (Windows) or Self Service (Mac) applications.
  • Log into both FastX and NoMachine desktop applications and resume the sessions you'd started in the web versions.
  • Choose your favorite of the two, and terminate the sessions on the other one. Personally I prefer to use desktop sessions with the NoMachine application.
• The web versions are the simplest and are sufficient for casual use, but can be sluggish so the desktop application are recommended. 
  
  • Note that the files on FastX/NoMachine are not accessible from the development servers so don't save files here.
  • Your sessions will stay running when you close the window so you can log back into them later and keep working.
  • Your logged in session expires every 25 hours, often without warning except some cryptic access denied errors!
    → To refresh the session type kinit and re-enter your password, then type aklog to make all your files writable again (I do this every morning when I log in so it doesn't catch me by surprise.)

Log onto the LCLS development server

• From the Public servers, you will 'ssh' or securely log into one of two development servers, depending on whether you want to read live control system data.

• For our main development machine, where you will not generally be able to read live data from the accelerator, open a terminal and log into lcls-dev3:

  ssh username@lcls-dev3

• For the same development filesystem, but with the default environment configured to view live accelerator data: open a terminal and log into mcclogin:

  ssh username@mcclogin

• From FastX, NoMachine, lcls-dev3, and mcclogin you cannot write to the live 'Production' control system so there is no risk of changing the accelerator equipment parameters.
• I find a nice workflow is to use different workspaces/desktops for each server I'm logged into - e.g. one each for dev3, mcclogin, production (more later), etc.

Set up your Linux Bash environment (one time only)

• When you first log into lcls-dev3 type the following so you always end up in the bash shell:

  ypchsh

  It will reply with "Login shell [/bin/bash]:", just hit enter and then enter your password when prompted.
  
  

• Copy bash configuration files to your home directory (this runs a little bash script that copies a couple of files into your home directory)

  bash /afs/slac/g/lcls/tools/script/get_my_bash

  Type 'exit' to log out of lcls-dev3, then ssh back in - if your prompt is now colorful it worked :)
  
  

• Take a look at your new .bashrc file - this file gets run every time you open a new terminal, so it is used to set up the correct environment configuration. I prefer to use a simple text editor called gedit when I'm working with files on Linux. In bash files, lines starting with '#' are comments. The '&' at the end of the command tells the program to run in the background so you can still use the terminal. If you forget the &, you can get back to the command line prompt by typing 'Ctrl-z' (stops/freezes the program), then 'bg' to make it run in the background. This command combination will become second nature to your fingers :)

  gedit .bashrc & # The first two 'source' lines set up default paths and control system settings # Next you can set up handy aliases (just check they're not already a command!) # Optionally (but strongly recommended!) customize your prompt - that's the PS1={stuff} # Google 'bash prompt generator' and have some fun :)

  I like to open the gedit preferences and change the theme to e.g. Cobalt, and set the tab width to 4 and select it to insert spaces instead of the actual tab character. Change the highlight mode (or language) to 'sh' to make these files easier to read (View > Highlight Mode > Scripts > sh, or from a quick menu on the bottom toolbar).

  Depending on your familiarity with Linux or what your mentor prefers, you may use other editors such as vi, emacs, or nano. Your mentor will likely have you add additional 'source' or 'export' lines to your bashrc file as needed depending on your projects.

• The most important entry in your .bashrc is a command to 'source' a file called ENVS64. This is a file managed by our control system network system administrators. Read the file with the handy Linux command 'less' (hit the 'q' key to quit and return to the terminal when you're done):

  less /afs/slac/g/lcls/tools/script/ENVS64.bash

  You can also open this file in gedit, but take extra care not to edit it! This is a common shared file that will affect everyone's setup. If it is accidentally changed let someone in controls software know right away and we'll revert it to the latest version checked into version control.
  Explore the content of these environment set up files. They define environment variables that tell the control system what versions of applications to use, and where on the controls network to connect to. They also source other scripts that have more specialized environment setups. Environment variables are typically written as ${VARIABLE}, and you can see what these are defined as on the command line with the Linux command 'echo'. Try the following to see what these common variables are (note you don't have to use the {})

  echo $LCLS_ROOT echo $APP echo $IOC

  You can also use the handy Linux tab-complete to fill in the rest of the entry, or to show you options. Try echo $EPICS  then hit tab a bunch of times until you get a list of all the variables that match. See what the values of $EPICS_TOP  and $EPICS_BASE are. Like everything else in Linux, these are case-sensitive, so for example $EPICS_Base does not exist and will simply return a blank line.

Become a Linux Wizard

• Go through this tutorial https://linuxconfig.org/linux-commands (ignore any parts that use 'sudo' or 'root'). This will give you a good introduction to the Linux command line - we simply can't do our work without becoming experts at this!
  Another good tutorial is https://www.tutorialspoint.com/unix/unix-getting-started.htm, especially the topics under Linux for Beginners (again, minus anything about changing passwords, using sudo/root, etc).

• Sometimes we work with command-line text editors like nano (described in the first Linux tutorial above) or vi. This is a really powerful editor with a steep learning curve, and it's worth exploring some of its capabilities with tutorials such as https://www.howtogeek.com/102468/a-beginners-guide-to-editing-text-files-with-vi/ .