1. Introduction

This document covers the steps needed to update from FS9 to 10.0.0 (now patched as 10.0.1). The changes in the FS and drudg for 10.0.0 are covered in the separate Changes from FS9 document.

This update is intended for all stations using FS9, both the main, non-VGOS, branch (latest version 9.13.2) and the VGOS branch (latest versions 9.12.10-9.12.13).

It has been tested for several configurations but not all possible ones. You should test it carefully before using it for operations. Please email Ed if you encounter problems so that we can resolve them.

Installing the new version as an update is fairly simple but has several steps, see the Upgrading from an FS9 version section below. This update has more steps than usual due to the unification of the main and VGOS branches as well as several loose ends being cleaned-up.

The most significant changes in 10.0.0 are:

  1. One unified version for all FS users.

    Both non-VGOS and VGOS operations are supported by the new version. Previous installations of the main (non-VGOS) branch will need to have some new local control files added.

    The most significant change for users is that previous main branch users will find that in the new FS input is case sensitive, as it was already in the VGOS branch.

    Caution
    		 While it is possible to have different SNAP commands or procedures with names that differ only in case, it is strongly discouraged. In the future, case insensitivity may be introduced for command and procedure names.

  2. Support for use on both 32- and 64-bit systems.

    The new version should run on 32-bit systems that currently support the FS as well as on 64-bit systems. We have verified it will run on 32-bit systems as far back as FSL8. We have not yet tested it on even older systems, such as FSL7.

    There are also instructions for transitioning to a 64-bit system, which may require some relatively simple changes to station software. See the Converting to a 64-bit System document for more details. Also see the TIP in the Upgrading from an FS9 version section below.

    A new FS Linux distribution, FSL10 (based on Debian Stretch), is now available for 64-bit (and 32-bit) use. We recommend using this distribution if you would like to move to using a 64-bit OS or need a 32-bit OS that is still under support (the base Debian distribution, Wheezy, used for FSL9, and those for older FSLx versions, are no longer under support). This also may be an alternative for users with distributions (such as FSL7) that may be too old to support the current FS. Installation instructions for FSL10 can be found at https://nvi-inc.github.io/fsl10.

  3. Version control with git.

    The FS source is now managed using git and github is used for distribution. The source code is now under the GPL3 license.

    The details of the model used for FS releases under git are described in the Release Model document.

    We expect updates in the future to require fewer steps, typically less than in FS9 updates. This is in part due to the fact that distributing the FS via github will make it easier to have smaller incremental updates instead of having to collect lots of changes for infrequent updates.

    This change increases the importance of not modifying the /usr2/fs directory tree since such changes will make it more difficult to simply pull updates to install bug fixes and new features.

  4. The FS display server is now recommended for normal use.

Please see the separate Changes from FS9 document for the full details of changes since FS9.

The release of 10.0.0 would not have been possible without the many and large contributions of Dave Horsley (UTAS, Australia and NVI/GSFC). These contributions include, but are not limited to:

  1. Making the FS 32- and 64-bit compatible

  2. Placing the FS under git version control

  3. Importing the existent archive of FS versions into git

  4. Merging the main and VGOS branches of FS9

Dave single-handedly imported the entire existent history of FS source code into git. This includes over 130 FS9 versions (under Linux), 17 FS8 versions (under VENIX), and two older versions (under HP RTE-1000/A) going back to version 5.5 in 1988. Having the source code in git greatly simplified the task of merging the main and VGOS branches. Dave also did the most critical work on that and provided excellent guidance on using git. Having the historical code in git is a great resource for understanding its evolution.

An essential contribution was also made by Tetsuro Kondo (NICT, Japan and SHAO, China). Kondo-san pioneered 64-bit support in the FS with his 64-bit implementations for the Sejong and Ishioka stations. Dave built on his work in developing a version that would support both 32- and 64-bit systems.

As always, we are deeply indebted to Jonathan Quick (HartRAO, South Africa) for his many significant contributions that go far beyond what is explicitly mentioned here. For this particular release, his contributions include testing and insights for adapting the code for 64-bit use, patiently solving various problems, identifying and fixing issues with the new version on FSL8, developing FSL10, making many helpful suggestions for changes, testing, and providing feedback.

We also thank Beppe Maccaferri (Medicina, Italy) for being a diligent beta tester, reporting bugs, helping test several fixes, and making helpful suggestions for changes.

We would also like to thank Eskil Varenius (Onsala, Sweden) for bug reports and feedback, particularly on DBBC3 related issues.

2. Other useful documents

This section provides links to some other useful documents.

2.1. Other update documents

2.2. Miscellaneous documents

If you haven’t upgraded or installed the FS before, you may want to review the appendix. It is strongly recommended that you back-up your operational system before upgrading.

3. Upgrading from an FS9 version

Caution
 This release of the FS may not build on older Linux distributions, such as FSL7 (Etch). If you do try it on a FSL7 or an earlier distribution please email Ed with your experience. If it doesn’t work we will try to help resolve any issues.

This section covers upgrading from FS9, which was always 32-bit only, to 10.0.0. It is assumed you are upgrading on a 32-bit system. There are two possible paths for upgrading:

  1. Upgrading from a main branch version. The main branch versions are numbered 9.13.<x> and 9.11.<x> or older. Specifically, versions 9.12.<x> are not part of the main branch. If you are upgrading from a main branch version, it is assumed that upgrade is from 9.13.2, the previous stable release. If you have a main branch version older than version 9.13.2 you should upgrade to 9.13.2 first, please refer to the Upgrading from FS versions before the previous stable section in the Installation Reference document for more information.

  2. Upgrading from a VGOS branch version. The VGOS branch versions are numbered 9.12.<x>. The instructions provided in this section are for installing as an upgrade to versions 9.12.10-9.12.13, the latest VGOS branch releases. As far as we know, no other VGOS versions are in use. If you have a different version, please email Ed for more information.

The differences in upgrading the main branch and the VGOS branch are almost entirely in the Update control files step below. To upgrade from FS9 to FS10 on a 32-bit system, please follow the steps below.

Tip

It is also possible to upgrade as a new installation on a 64-bit system. Doing so will allow you to upgrade to 10.0.0 and 64-bit without disturbing your operational 32-bit system. However, the upgrade may be more involved because it may require additional changes and testing for your station software. The instructions for combining the FS and 64-bit upgrade are:

  1. Follow the steps in the Converting to a 64-bit System document down to the Make local software step. Instead of following that step, return to the next step in this TIP.

    Note
    		 After completing this step, you will have a base FS10 installation on a 64-bit system with your local software (updated for 64-bit), control files, and procedure files from your FS9 32-bit system. That is an inconsistent configuration that will not work properly. Your local software and other local files need to be updated for 10.0.0, which is covered in the next step in this TIP.

  2. To update your local software and other local files for 10.0.0, follow the instructions beginning with the Case sensitive strings in antenna= commands sub-step below and continue with the remaining sub-steps and steps thereafter.

    When you get to the Test the FS step below, you may need to debug your, 64-bit converted, station software.

3.1. Back-up your operational system

Having a back-up to return to will allow you to continue operations in case something goes wrong with the installation. For more details, please see the Making a back-up before installing section in the Installation Reference document.

Note
 If you are using FSL10 with a RAID, that sub-section points you to the improved backup and test procedure that is available with that distribution.
Note
 That section also includes a description of how to preserve your operational files and switch back and forth between an operational and a test set-up by changing symbolic links.

3.2. Login as root

Login as root.

3.3. Download the FS

Place a copy of the FS git repository in the /usr2 directory on your computer. For example, you might do the following:

cd /usr2
git clone https://github.com/nvi-inc/fs.git fs-git

or alternatively, if you are using FSL8 or other old Linux distribution, or otherwise need to use ssh instead:

cd /usr2
git clone git@github.com:nvi-inc/fs fs-git
Tip

Using ssh requires you to have a github account and for you to add an SSH public key from your machine’s root account to your github account. For more information, go to https://github.com/join and https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/adding-a-new-ssh-key-to-your-github-account.

Caution
 We recommend that you also add a SSH public key from your prog account. This will make it easier to install later updates from github as prog. All instructions for further github use are written for prog.
Tip

If you don’t have git, you may be able to install it. Some older Linux distributions, e.g., FSL8, have the git package available under a different name, git-core. To install git, we recommend trying to install the git-core package first. In older Debian-based distributions this should install the required package instead of another package that was named git in those distributions (Gnu IT). If you don’t see anything named git-core, then try installing git instead.

If you are unable to install git (or git-core), you can install the FS from an archive. Please follow these directions:

  1. Stopping just after the cd /usr2/fs-tag step, execute the steps in the Installing from an archive sub-section in the Release Model document.

  2. Return to the current document, jumping ahead to the Set the /usr2/fs link step below and continue the installation, but skip the cd /usr2/fs-git command in that step.

3.4. Checkout the release

Checkout the 10.0.1 release from the local repository:

cd fs-git
git checkout -q 10.0.1
Note
 The use of 10.0.1 is not a typo. That is the latest patch release for 10.0.

3.5. Set the /usr2/fs link

Set the link for the new FS version:

cd /usr2/fs-git
make install

Answer y to confirm installation.

Caution
 This step will change your /usr2/fs symbolic link to point to /usr2/fs-git. To switch back to your old version, you will need to change the link manually.
Note
 The make install command may create and possibly rename some existing directories if the FS was never installed on this system before. However, since you should only be following this path if you are upgrading an FS9 installation, there should not be any problem.

3.6. Fix file permissions

Having the wrong ownership and/or permissions on the operational files (procedure libraries, control files, schedules, and logs) can cause errors during FS operations. For a full discussion, please refer to the Set operations file permissions section of the Installation Reference document. For stations where all the operational files are expected to be owned by user oper in group rtx, with permissions ug+rw,o+r,o-w, the following command will enforce this (note that the execute/search bits are not changed):

/usr2/fs/misc/fix_perm

Answer y to the prompt if you wish to proceed. It is recommended for most stations.

3.7. Login as prog

Important
 Logout as root, and login as prog.

3.8. Set FORTRAN compiler

Starting with version 10.0.0, the standard FORTRAN compiler for use with the FS is f95 (gfortran). We recommend that you use it. On the 32-bit systems you can still use fort77, but you should only use it if you either don’t have f95 or if you have FORTRAN station code that is too difficult to convert to f95, see the Conversion of FORTRAN code sub-step below for more details.

To select f95 as your compiler, you will need to set the FC variable to this value. If your shell is tcsh you can use:

setenv FC f95

If your shell is bash, you can use:

export FC=f95
Warning
 If you are testing the installation on a 32-bit system, you may not want to make this change permanent since it is incompatible with pre-10.0.0 versions.

To make this change permanent, you should add the appropriate command to the appropriate rc file depending on your login shell: ~prog/.login for tcsh or probably ~prog/.profile for bash.

3.9. Make the FS

Tip
 If you are using an old distribution that is not compatible with the latest update of the server, you can still use the FS without the server by removing it from the make process. If your first attempt to build the FS fails because of the server (most likely while working in third_party/), please follow the steps in the description of the not building the display server change (in the FS changes that are in common since FS9 sub-section of the Changes from FS9 document). Please email Ed about needing to do this or if you still can’t build the FS. 
cd /usr2/fs
make >& /dev/null

and then

make -s

to confirm that everything compiled correctly (no news is good news).

3.10. Update station programs

This step is for modifying your station programs in /usr2/st. There are four possible issues:

  1. Conversion of FORTRAN code

  2. Case sensitive strings in antenna= commands

  3. Update local lo/lo_config commands

  4. Update metserver

They are discussed next.

3.10.1. Conversion of FORTRAN code

If you don’t have any FORTRAN station code, you should skip this sub-step. If you do have some, please email Ed so he is aware.

Basically you have two options (also see the Set FORTRAN compiler step above):

  1. Change to using f95 for both the FS and your station FORTRAN programs. It is recommended that you follow this approach for 32-bit systems and it is necessary when moving to a 64-bit system.

    You will need to adapt your Makefiles to use the same compiler options as the FS, which can be found in /usr2/fs/include.mk. As a first cut, it may work to add the following two lines to your Makefiles for FORTRAN programs:

    FFLAGS  += -ff2c -I../../fs/include -fno-range-check -finit-local-zero -fno-automatic -fbackslash
FLIBS   += -lgfortran -lm

  2. Continue to use fort77 for both the FS and your station programs. You should follow this approach only if you are on a 32-bit system and it is too difficult to convert to f95.

3.10.2. Case sensitive strings in antenna= commands

If you don’t have a local antenna=…​ command, you should skip this sub-step.

In FS9 versions, the strings used in antenna=…​ commands were always converted to uppercase before being sent to antcn. That no longer happens due to FS input becoming case sensitive. If your antenna, or your side of the antenna interface, requires that the strings passed by the antenna=…​ command are uppercase, you have two options:

  1. Convert your code. For simple backward compatibility, change your antcn program to always convert the antenna=…​ strings to upper case. Alternatively, make your code case insensitive.

  2. Convert the strings in your antenna=…​ commands wherever they occur: SNAP procedures, SNAP schedules, external programs, or scripts, to upper case.

The former choice is probably easier, but in some cases the second is probably better (it keeps with the spirit of case sensitivity). If you have questions about which to use and how to do it, please email Ed.

3.10.3. Update local lo/lo_config commands

If you don’t have a local (station) lo or lo_config command, you should skip this sub-step.

  • Local lo command

    If you have a local lo command, you will need to update it (or replace it, see the next paragraph) to get full support for rack types that were not in your previous FS9 version and to implement the new capability described in the logging .rxg files change (in the FS changes that are in common since FS9 sub-section of the Changes from FS9 document).

    You should consider switching to use the new version of the lo command described in the LO hooks change (in the FS changes that are in common since FS9 sub-section of the Changes from FS9 document). This approach may not be suitable for all stations, but it may work well for your station. If so, it should reduce, and in most cases eliminate, the need to update your local software when the FS lo command changes in the future.

  • Local lo_config command

    Likewise, if you have a local lo_config command, it will need to be updated to get full support for the new rack types. You should also consider switching to using the new hook for this described in the LO hooks change (in the FS changes that are in common since FS9 sub-section of the Changes from FS9 document).

3.10.4. Update metserver

If you don’t use metserver as a local program, you should skip this sub-step.

This sub-step is optional even if you use metserver. You should consider it if you are upgrading from the VGOS branch or you are upgrading from the old main branch and have not already updated to the latest metserver from that branch. The latest version of metserver has several improvements:

  1. A new command line argument to disable errors messages for specific sensors if they are broken.

  2. Support for the FS_SERIAL_CLOCAL make time environment variable for FSL9 and later.

  3. Improved reporting of errors when opening serial devices.

  4. Reduction in the threshold for old data being declared stale to 10 seconds, which is more than sufficient.

See st.default/st-0.0.0/metserver/INSTALL for the installation instructions.

3.11. Make local software

If /usr2/st/Makefile is set-up in the standard way, you can do this with:

cd /usr2/st
make rmdoto rmexe all
Note
 At this point, you are only trying to verify the code will make successfully. You may still need to debug it in the step Test the FS below.

3.12. Reboot

Important
 Reboot the computer. This is necessary to allocate FS, and possibly station, shared memory for the new version. It will also make sure you are using the latest version of the display server.

3.13. Login as oper

The remaining steps assume you are logged in as oper.

3.14. Update control files

This step is for updates to the local control files. There are seven sub-steps:

  1. Update stcmd.ctl

  2. Copy control files

  3. Update equip.ctl

  4. Review control files

  5. Update rdbemsg.ctl

  6. Update aquir control files

  7. Update skedf.ctl

Differences for updating from different previous versions are noted. Please read all cases in each sub-step carefully to make sure you find all the cases for your old version; sometimes an old version is included in more than one case in a given sub-step.

3.14.1. Update stcmd.ctl

  1. Old version 9.13.2:

    The non-comment lines need another digit added to the subroutine number. This sub-step is only needed for updates from 9.13.2. You can fix your file with the commands:

    cd /usr2/control
/usr2/fs/misc/cmdctlfix6 stcmd.ctl

    You may also want to expand the (typically) second comment line to correspond to the new format by adding a U after character 18 to read as follows:

    *COMMAND     SEG SUBPA BO

3.14.2. Copy control files

You will need to execute the following commands to copy the new files that are needed (copy-and-paste is your friend). There are three cases depending on what your old version was:

  1. Old versions 9.12.10 - 9.12.12:

    cd /usr2/control
cp /usr2/fs/st.default/control/clpgm.ctl .
cp /usr2/fs/st.default/control/rdbemsg.ctl .

  2. Old version 9.12.13:

    cd /usr2/control
cp /usr2/fs/st.default/control/rdbemsg.ctl .

  3. Old version 9.13.2:

    cd /usr2/control
cp /usr2/fs/st.default/control/dbba2.ctl .
cp /usr2/fs/st.default/control/mk6c?.ctl .
cp /usr2/fs/st.default/control/monit6.ctl .
cp /usr2/fs/st.default/control/rdbc?.ctl .
cp /usr2/fs/st.default/control/rdbe.ctl .
cp /usr2/fs/st.default/control/rdbemsg.ctl .

3.14.3. Update equip.ctl

It is necessary to add lines for the FiLa10G input select and the DBBC3 configuration. There are three cases, please check which applies for you. In any event, you should compare your equip.ctl to the example as described when you get to the Review control files sub-step below, to make sure there are no duplicated lines or other problems caused by the commands in this current sub-step (i.e., Update equip.ctl).

  1. If your old version was 9.12.10 or 9.12.11 (or 9.12.12 at GGAO only), you will need to add the final four lines of the example equip.ctl file to yours:

    cd /usr2/control
tail -n 4 /usr2/fs/st.default/control/equip.ctl >>equip.ctl

  2. If your old version was 9.12.12 (but not at GGAO) or 9.12.13, you will need to insert two lines before the final two lines. This is covered in the Review control files sub-step below.

  3. If your old version was 9.13.2, you will need to add the final two lines of the example equip.ctl file to yours:

    cd /usr2/control
tail -n 2 /usr2/fs/st.default/control/equip.ctl >>equip.ctl

3.14.4. Review control files

You should compare your versions of the following files:

  • clpgm.ctl

  • equip.ctl

  • stpgm.ctl

to the example files, e.g., using:

cd /usr2/control
diff clpgm.ctl /usr2/fs/st.default/control/ | less

and consider whether and what changes you should make to your copies.

Tip
 If you are familiar with vimdiff, you may find it a more convenient way to compare files and update your local copy. Like vim, vimdiff may be challenging to use until you are familiar with it. Some help is available from web searches. Don’t use it if you aren’t comfortable with it.

The following sub-sections give the details of the changes in these example files. You will need to make the corresponding changes to your copies of the files.

3.14.4.1. Review clpgm.ctl

You may only need to replace your copy with the new one.

  1. Old versions 9.12.10 - 9.12.12:

    This file was not present so the new default version (copied by commands in the Copy control files sub-step above) should not require modification.

  2. Old versions 9.12.13, and 9.13.2:

    1. The -title …​ parameter for each window was removed so that it is uniquely supplied by the .Xresources file.

    2. The value of the -name parameter for erchk was changed from ERRORS to erchk.

    3. The useful display window scnch was added.

    4. The xterm program was added.

    5. For RDBE systems, the useful RDBE display windows: monit6, and mon<x> (<x>=[a-d]) were added. If these are not relevant for your site, you may not want to add them.

      The mon<x> displays use the rdbe30_mon.py script written by Russ McWhirter (Haystack). It is not distributed with the FS at this time, but should already be available at all stations with RDBEs.

    6. The monan program was added to the default since it is used at several sites. If it is not relevant for your site, you may not want to add it.

3.14.4.2. Review equip.ctl
Caution
 This sub-step has the most complicated changes. Please read all clauses to make sure you see all that apply to your old version.

There are two sub-sections. The first sub-section covers changes to non-comment lines; the second, comments. The former are required. The later are in some sense optional, especially when they refer to equipment you don’t (or never will) have. However, changing them now may help avoid confusion at a later date.

Non-comment lines

  1. Old versions 9.12.10-9.12.13:

    1. The line for DBBC PFB version was changed to have a minimum version number of v15_1. The line is shown here with the typical preceding comment:

      *DBBC PFB version
v15_1    v15_1 or later

    2. The line that defines the DBBC2 CoMo configuration was changed. Please see item (12) in the installation instructions in /usr2/fs/misc/fs91119up.txt for full details on handling this. However, the following commands will probably make the needed change if you don’t have a DBBC2 or if your DBBC2 configuration is four CoMos with one Core per CoMo:

      cd /usr2/control
/usr2/fs/misc/dbbc_equip '1 1 1 1' equip.ctl

      If the script prints a warning about the number of IF power conversions being incorrect, the issue must be resolved before continuing, either by adjusting the number of power conversions, adjusting the CoMo configuration, or both.

  2. Old versions 9.12.10 and 9.12.11 (and 9.12.12 at GGAO only):

    A FiLa10G input select line was added, but the Update equip.ctl sub-step above should have handled that.

  3. Old versions 9.12.12 (but not at GGAO) and 9.12.13:

    A stanza (actually one comment and one FiLa10G input select line) was inserted before the final stanza (typically one comment and one DBBC3 configuration line). An example of the lines inserted can be found near the end of the default example /usr2/fs/st.default/control/equip.ctl file. They are listed here as well (one comment and one FiLa10G input select line):

    *FiLa10G input select, one of: vsi1, vsi2, vsi1-2, vsi1-2-3-4, gps, tvg
vsi1-2

  4. Old versions 9.12.10, 9.12.11, and 9.13.2 (and 9.12.12 at GGAO only):

    A new line for the DBBC3 configuration was added at the end, but the Update equip.ctl sub-step above should have handled that.

Comment lines

  1. All old versions:

    Compared to all old versions, comment lines were added or modified for new equipment type options.

  2. All old versions:

    The trailing comment on the line for the met. device was removed and the preceding comments were reworded.

  3. Old versions 9.12.10-9.12.13:

    The comment lines describing the available clock rates was completely rewritten and greatly expanded, and an additional clock rate (128) was appended to the end of the comment on the clock rate line itself.

3.14.4.3. Review stpgm.ctl
Warning
 If you are planning to not use the FS display server, we recommend that you comment out the lines for erchk, monit2, and scnch and not add any other monit<x> programs or other uses of xterms. If they are used in stpgm.ctl without the display server and they are accidentally closed, the FS will be killed. This applies as well if you built the FS without the display server as described in the not building the display server change (in the FS changes that are in common since FS9 sub-section of the Changes from FS9 document).

  1. For all old versions, if you are planning to use the FS display server:

    1. The line for erchk is now uncommented as the default and differs from the previous commented version with the addition of the -name erchk parameter and the removal of the -title …​ and -geom …​ parameters, so that the latter two are uniquely supplied by the .Xresources file.

      You should change the second field in the erchk line from n to x as shown in the /usr2/fs/st.default/control/stpgm.ctl example.

      Note
      		 An x should be used as the second field for all X window display programs. They will be automatically started and stopped with each instance of the display client, on its display.

    2. New lines were added for monit2, and scnch for when the display server is in use. You may want to include those if you would like them to start automatically when you launch the FS or separate display clients.

      If you are using the display server you may want to add other monit<x> programs. If so, you may also want to add resources for them (if they aren’t already there) in the ~/.Xresources files for oper and prog.

    3. If you are using the display server and were starting any xterms with sy=…​ from your initi procedure in your station library, you should remove those (see the sub-section Remove running xterm from your SNAP procedures farther below) and probably add them to stpgm.ctl, usually with x for the second field. The syntax is slightly different than what is used with sy=…​ command. You can use the /usr2/fs/st.default/control/stpgm.ctl file as an example.

3.14.5. Update rdbemsg.ctl

  1. Versions 9.12.10-9.12.13:

    If you have RDBEs for your back-end and will use the rdbemsg utility to send operations messages, you will need to customize your /usr2/control/rdbemsg.ctl file.

    1. You will need to update the station two letter code (lowercase) to your station’s value.

    2. You will need to update the name station name to your station’s value.

      Note
      		 The station name is also defined in the /usr2/control/location.ctl file.

    3. You should set the addresses for the RBDE-A (R-A) through RDBE-D (R-D).

      The example file uses aliases, rdbea through rdbed, that you can define in /etc/hosts. Likewise, if you have an mci node, you can set its alias, perhaps hubpc, in /etc/hosts. Alternatively of course, you can use any scheme you prefer for the nodes names used in rdbemsg.ctl.

      Note
      		 It is usually necessary to have root access to modify /etc/hosts.

    4. The default email address to is for the ivs-ops mail list. You can of course change that to whatever you like.

      Note
      		 You can also temporarily override the address in the rdbemsg utility itself.

    5. If you don’t have an MCI node (hubpc) for front end monitor and control, you should comment out that line.

    6. If you do have an MCI node, change the node name from hubpc if it is different (possibly an alias from /etc/hosts).

    7. For stations with a prototype MCI node (GGAO and Westford):

      If your MCI node uses a different station code (gg at GGAO) and/or the values are reported in a different position (3 at GGAO). You can set these values with the mci-code and mci-parameter lines. As needed, uncomment the example lines and update them with appropriate values.

      If you have version 0 of the MCI node (Westford), you will need an updated rdbemsg program that uses the mci-version line. This is described in rdbemsg.ctl sub-section of the FS RDBE Support document. If you need advice on extracting the version of rdbemsg in commit fb57201c and installing it, please contact Ed.

3.14.6. Update aquir control files

If they are not already, convert the contents of your aquir control files to lowercase. This is usually necessary since the FS is now case sensitive. However, you could arrange your control files and procedure libraries to use uppercase if you want. That would be an unusual situation. For the typical situation, you can convert as oper, for example, with:

Caution
 These commands will change all the uppercase in the file(s) to lowercase, including in comments. The change for the comments should be benign. While it might not be what is desired for some of the comments, it will enforce lowercase for lines that are currently commented out, but may be uncommented in the future. You can always use an alternative method of conversion to retain uppercase in comments only in places where you want it. 
cd /usr2/control
/usr2/fs/misc/to_lower ctlpo.ctl

You can repeat this for other aquir control files you may have. The to_lower script can process multiple files given on the command line. It will make a back-up of original files with an added .bak extension. It will not overwrite any existing .bak file. It stops if any error is encountered.

Caution
 Each aquir control file has its own horizon mask that is separate from the one in location.ctl.

3.14.7. Update skedf.ctl

  1. All versions:

    1. This sub-step applies only if you use the fesh script to fetch schedules, and optionally run drudg for them. There are two possible changes:

      1. If not already set, specify a directory for .skd files in the $schedules block of the /usr2/control/skedf.ctl control file. You can use any value you want, but to be backward compatible with the previous behavior of fesh it must be /usr2/sched.

      2. Likewise, directories should be specified in the $snap and $proc blocks of /usr2/control/skedf.ctl. You can use any values you want, but typically they should be set to /usr2/sched and /usr2/proc, respectively, to agree with the FS.

    2. Due to an error (as described in the FS changes that are in common since FS9 sub-section of the Changes from FS9 document) in the example /usr2/fs/st.defaut/control/skedf.ctl file in previous releases, most stations probably incorrectly show the lo_config keyword as if_config in their local /usr2/control/skedf.ctl version. Please check your local copy and update any occurrences, even in comments, of if_config to lo_config.

3.15. Update .prc files

This step is for updates to your .prc SNAP procedure libraries. Except where a script is provided to make the change (which must be used only when the FS not running), all changes should be made with pfmed.

There are four sub-steps. The first change is required for all users: converting from using the old FS go program to rte_go.

The second change is required for all users converting to or already using the display server: remove any instances of running xterms in your procedures.

The third change is optional and only relevant if upgrading from 9.13.2: removing if=cont_cal,, from the fivpt and onoff procedures for calon and caloff procedures.

The fourth change, switching to using s_client from other deprecated TCP communication scripts, is only relevant if you are updating from the VGOS branch, versions 9.12.<x>, and probably only if you had a RDBE rack.

3.15.1. Convert from go to rte_go

Convert use of the old FS go program to use rte_go. This is required because the compiler for the go language conflicts with the old program name go. This change is necessary even if you do not have the go language compiler installed.

To make this change for all your .prc procedure libraries, execute:

cd /usr2/proc
/usr2/fs/misc/go_fix *.prc

Files that are changed will have a pre-change back-up copy with the extension .bak. You can use the .bak files to recover in case of a problem.

3.15.2. Remove running xterm from your SNAP procedures

This step is only needed for stations using the display server. You should remove any instances of running xterms from your SNAP procedures. Typically this would only occur in the initi procedure in the station library, where it might be used to start monitor displays automatically when the FS is launched. In addition to there being issues with the functioning of such xterms with the display server, a more comprehensive solution is now provided through the stpgm.ctl control file (see the Review stpgm.ctl sub-step farther above for more information on setting this up).

To check whether you have an instance of running xterms in your procedures, you can use:

cd /usr2/proc
grep xterm *.prc

This will only identify which libraries have commands that run xterms. You can list those libraries with less to find which procedures they are in. You should use pfmed to modify the procedures involved. You can delete or comment out the relevant commands.

3.15.3. Remove extra if commands

This sub-step is optional and only relevant if you are upgrading from 9.13.2. You can remove the if=cont_cal,, as a prefix from before the calon and caloff commands in your calonnf, calonfp, caloffnf, and calofffp procedures, probably located in your point procedure library. This is just a clean-up and not making this change will have no impact.

3.15.4. Switch to using s_client

This sub-step is optional and only relevant if you were using the VGOS branch, versions 9.12.<x>. You should replace use of the deprecated scripts be_client and mcicn, if you were using them, with the more general s_client. You can find instances of these commands, using, e.g., for be_client:

cd /usr2/proc
grep be_client *.prc

You can use less to identify the SNAP procedures in each file that uses the script. Use pfmed to make the changes.

Information about using s_client can be found using help=sy in the FS.

3.16. Miscellaneous FS related changes

There are three changes:

  1. Set FS_DISPLAY_SERVER environment variable for oper and prog. This is only needed if you were not running the FS display server before.

  2. Set environment variables for fesh. These are optional changes to consider if you use fesh.

  3. Update .Xresources file for the oper and prog accounts.

3.16.1. Set FS_DISPLAY_SERVER

Set the FS_DISPLAY_SERVER environment variable for oper and prog. This will make using the display server the default for your system. We strongly recommend this, but if it is not suitable for you for some reason you can skip this. If you are already using the display server, you should also skip this. You should not implement this step (or instead remove setting the variable if already being set), if you built the FS without the display server as described in the not building the display server change (in the FS changes that are in common since FS9 sub-section of the Changes from FS9 document).

Warning
 If you don’t use the display server, you will probably need to update the stpgm.ctl file for that case as described in the WARNING in the Review stpgm.ctl sub-step above.

  1. As oper:

    1. Set the variable

      • If using the bash shell then in the ~oper/.profile file, you can uncomment or insert

        export FS_DISPLAY_SERVER=on

      • If using the tcsh shell then in the ~oper/.login file, you can uncomment or insert

        setenv  FS_DISPLAY_SERVER on

    2. You should logout and login again after making this change.

  2. You should make the corresponding change for prog while logged in as prog.

3.16.2. Set environment variables for fesh

These are optional changes that should be considered if you use fesh.

  1. The fesh script uses cddis as the default data center. You can specify a different data center by setting the FESH_DATA_CENTER environment variable. Available data centers for geodesy are bkg, cddis, and opar; for astronomy, vlbeer.

    Tip
    		 For FSL8 and other old Linux distributions, access to cddis may not be possible, due to out-of-date certificates (for both FTP-SSL or HTTPS). If you are in that situation, bkg or opar may be suitable alternatives.

  2. The fesh script uses FTP-SSL as the default access method for the cddis data center. For this case, you can avoid having to answer a prompt for your email address each time you run fesh by setting your email address in the FESH_EMAIL environment variable.

    Tip
    		 The FTP-SSL method may not work from behind some firewalls. If it doesn’t work for you, either use a different data center (see above) or use HTTPS for cddis (see below).

  3. You can change the access method for cddis to HTTPS, by setting the FESH_CDDIS_METHOD environment variable to https.

    Note
    		 Using HTTPS requires an EarthData login and setting it in your .netrc file. If you don’t have an EarthData login, you should be able to get one by selecting REGISTER at: https://urs.earthdata.nasa.gov/.

A more complete description of the new features in fesh is available in the FS 10.0.0 fesh Changes document. Please use fesh -h for more information on using these features.

3.16.3. Update .Xresources

The main change was to add values for the erchk, scnch, and helpsh windows. There were some minor changes for other windows, but what to use for the changed values may depend on the resolution of your display. The example values worked well for an FSL10 installation on a system with a non-GPU CPU.

Tip

Fine tuning the geometry values is probably best done with the windows open while the FS is running. So you may want to defer the tuning until the Test the FS step below.

You can find an effective strategy to help with setting the geometry values for an xterm window (and others with a name property) in the Setting geometry values in .Xresources section of the Installation Reference document.

As oper, you can find the differences between your file and the example file with:

cd
diff .Xresources /usr2/fs/st.default/oper
Tip
 If you are familiar with vimdiff, you may find it a more convenient way to compare files and update your local copy. Like vim, vimdiff may be challenging to use until you are familiar with it. Some help is available from web searches. Don’t use it if you aren’t comfortable with it.

Please make any changes to your file that you find appropriate, but at a minimum you should probably add the lines for monit6, erchk, scnch, and helpsh if not already present. You will need to logout and login again (or reload the X-resources a different way) for the changes to become effective.

Caution

The example .Xresource file for 9.13.2 did not have any of these items, but you may have already included some in your local file. Similarly, the example files for the 9.12.<x> versions only had monit6 included, but you may have already included some of the others in your local file.

You should be careful to not specify values for a window more than once. So don’t use the suggested commands below if they cover windows that already values in your .Xresources file. Instead you will need to hand edit to make the appropriate changes.

Every station will probably need the lines for helpsh.

  • All the new lines are at the end of the file, so if you need to add lines for monit6, erchk, scnch, and helpsh, you can use:

    cd
tail -n 24 /usr2/fs/st.default/oper/.Xresources >>.Xresources

  • To add lines for just erchk, scnch, and helpsh, you can use:

    cd
tail -n 20 /usr2/fs/st.default/oper/.Xresources >>.Xresources

  • To add lines for just helpsh, you can use:

    cd
tail -n 6 /usr2/fs/st.default/oper/.Xresources >>.Xresources

You can update prog's .Xresources file similarly, but you will need to be logged in as prog.

3.17. Miscellaneous FSLx changes

  1. Update ~/.xsession: If you are running the FS on the console and your login shell is tcsh (or if you are using AUID accounts, see the NOTE immediately below.)

    Note

    If you are using an AUID accounts (with bash as the login shell) in FSL10 (see the Adding AUID account sub-section, https://nvi-inc.github.io/fsl10/cis-setup.html#_adding_auid_accounts, of the CIS hardening for FSL10 document, https://nvi-inc.github.io/fsl10/cis-setup.html), you only need to update the ~/.profile files for the AUID accounts to set the needed environment variables.

    If you are using tcsh as the login shell for those accounts, you will need to make the changes below and add the environment variables to the ~/.login files for those accounts.

    If you are using tcsh as your login shell for oper or prog (or AUID accounts in FSL10), the (optional) changes in this sub-step will make sure any FS runtime environment variables are set properly for the console window display manager (fvwm2). This could be important for example, if you want to run fsclient (perhaps for a scan_check window) from a console hotkey. There are two cases: FSL9/FSL10 and FSL8.

    • FSL9/FSL10: If you are using one of these distributions (or any other that uses the graphical manager gdm3 for the console), update your ~/.xsession files.

      1. If oper uses tcsh as its login shell, then as oper, make these change to ~/.xsession:

        1. Change the first line to:

          #!/bin/tcsh

        2. Change the source .profile line to:

          source .login

      2. Likewise, if prog uses tcsh you should make the same changes, as prog.

    • FSL8: If you are using this distribution (or any other that uses the graphical manager gdm for the console), update your ~/.profile files.

      1. If oper uses tcsh as its login shell, then as oper, you will need to update the ~/.profile file to set any FS runtime environment variables you are using in .login. The syntax in .profile is different from that in .login. You can look at an example in /usr2/fs/st.default/oper/.profile.

      2. Likewise, if prog uses tcsh you should make the same changes, as prog.

3.18. Test the FS

There is one item that might need to be completed and two things that need to be tested:

  1. Complete: You may want to tune the positions of the various windows on the display. For this, you can follow the suggested method from the TIP in the Update .Xresources sub-step above.

  2. Test: the FS and drudg:

    Important

    Before testing, if as part of your testing of station code you ran the FS under the prog account, either reboot or use the command:

    fsserver stop

    to make sure the server is no longer running as prog.

    For details on why this is needed, please see the second IMPORTANT item in Server continues running after FS termination sub-section of the FS 10.0.0 fsserver Changes document.

    Generally speaking, a fairly thorough test is to run a test experiment. Start with using drudg to rotate a schedule, drudging it to make .snp and .prc files, making listings, and any other pre-experiment preparation and tests you normally do, then execute part of schedule, and perform any normal post-experiment plotting and clean-up that you do. The idea here is to verify that everything works as you expect for normal operations.

  3. Test: fesh, if you use it:

    If you use fesh to download schedules, you should test that using the latest version. If you also use it to drudg schedules, you should test that as well.

    Caution
    		 If you have been using an updated version of fesh outside the FS, be sure to test and use the new FS version. For example, if you have been using ~/fesh to run a version in ~oper, be sure to use fesh to get the new FS version.

    A quick check is to just make sure the files have reasonable contents. If you want to make a detailed check, a strategy for that might be:

    1. Move an old schedule file and its the drudg output, e.g., r4948.skd, r4948<xx>.lst, r4948<xx>.snp, and r4948<xx>.prc, (where <xx> is your station’s two letter code) to a different directory, e.g., /tmp.

    2. Rerun fesh for that schedule.

    3. Compare the old and new versions with diff (or vimdiff). They only differences should be:

      1. Comments in the .snp and .prc files.

      2. Compared to .snp files produced by 9.12.<x> versions for Mark 6 recorders, the GB used in the mk6=record= commands (third parameter) will be slightly, by a factor of 1024/1000, larger, truncated to an integer.

      3. The timestamps in the define lines in the .prc file. However, it is possible the procedures will be in a different order if you edited the old version.

      4. Compared to drudg summary listings produced by 9.12.<x> versions, the GB shown will slightly, by a factor of 1024/1000, larger.

      5. Insignificant rounding differences in drudg summary listing files.

    4. Copy your original files back from where you placed them, if you want to preserve them.

3.19. Consider when to update your back-ups

It would be prudent to wait until you have successfully run an experiment or two and preferably received word that the experiment(s) produced good data. The chances of needing to use your back-up should be small. If something does happen, you can copy the back-up to the (now assumed bad) updated disk. You can then either use the restored disk or apply the FS update again. The FSL10 test procedure has more options for recovery. Managing this is a lot easier and safer if you have a third disk.

4. Changes from FS9

Due to the large number of changes since FS9, they are provided in the separate Changes from FS9 document. That document includes sections:

Each of those sections is divided into three sub-sections:

  • Changes that are in common since FS9

  • Changes relative to the main branch

  • Changes relative to the VGOS branch

Please see the Changes from FS9 document for full details.