CDF SAM Station Installation |
| These instructions are for a first time installation, for a station modification, OR for a station addition as indicated by the buttons to the right. To see instructions for a different task, click on it. |
- the machine has never run a SAM station before and/or may not have all of the necessary products. - the machine is running a SAM station, and you want to modify some aspects of the configuration or update the versions of some of the products. - the machine is currently running a station, and you want to add a new SAM station. |
Page Legend:
|
|
In the following text replace <stationname> with
your station name (example:
--station=<stationname> becomes
--station=cdf-caf). Alternatively, you can set an
environmental variable and omit the --station option
in many cases:
It is recommended that you set this variable at the end of the "Set up needed products" step.
Please ensure you have completed all the steps shown on the Requirements page before attempting the instructions below.
Log into the workstation as user "sam".
If the changes you are making to a station are minor, then you can
leave the station running while making the changes and skip this
step. At a later step, you will apply your changes using the
"ups update sam_bootstrap" command.
If you are doing major upgrades of an existing station that is running, you will need to stop it. If multiple services are running on the machine, you will need to make sure that you do not interfere with services you are not working with. Stopping a service will disrupt any jobs running through it, so you need to edit the server list file to comment out services you do not want to effect. Open the server list file
with your favorite editor. On each line of the file the first
four words describe the service
type, the sam_config flavor, the
sam_config
version number, and the service name, respectively. Place a comment
character ("#") at the beginning of all lines
except the line for the station you want to work on and
save the file. Now execute the command to stop stations:
To clean up, re-edit the file to remove all the comment characters
you just put in, and save it again. It is okay to leave all
services uncommented when running the start command
later because already running services will just print a warning
message and continue to run.
If you want to make a backup of the existing installation, make
a copy of the
private and products directories:
init_sam script
(In some cases an init_sam script already exists
on the machine. If so, you can reuse that script and skip to
the next step.)
Get the
init_sam
script from cdfkits via anonymous ftp. For
example, you can use:
and make the script executable with:
init_sam script
Run the installation script
watching the output for errors.
A version number can be added as a third argument. If it is not specified the current version will be taken (recommended).
If you see any problem with the tailoring of vdt,
edit the init_sam file to comment out the
vdt product and then rerun init_sam.
init_sam script
The init_sam automatically updates itself
if a newer version exists.
In such a case it prints a message that a new version was
downloaded and you should rerun it. If you see this message
when running init_sam, run it again.
To give your environment information about how to connect to SAM, you need a few products set up:
You can save yourself some typing by setting the
SAM_STATION environmental variable to the name of
the station you are interested in:
With the SAM_STATION variable set, you may omit the
--station command line option in most cases.
Aside: Assuming the sam client is
installed on the "cdfsoft" account, the procedure
to set up sam for any user other than
"sam" is:
sam_config
Adding a new station to a machine that is already running a
station is a little tricky since you cannot use the
init_sam script. Hopefully a configuration that
suits your needs already exists. You can see all available
configuration qualifier names by typing:
To get detailed information about any particular configuration, use:
You can find out which qualification is currently set up using
and looking for the value following the "-q" option.
If you find a qualifier whose parameters work for your new station, all you need to do is use the qualifier name in the server list file entry for your new station when you reach the "Adapt server list file" step.
If you do have to create a new qualifier instance, you can do
so by "tailoring" sam_config
and selecting the "a)dd" option. The
tailor commands are self-explanatory, but if
you have any problems or questions you can open a
SAM Issue Ticket
to ask an expert for help.
Remember that the sam_config
qualification for
the station you are working on has to be set up in your
environment for later testing to work. To set up the qualification
version, run this command:
A SAM station routes directory paths by using a combination of database information and the station's server list file. This step deals with entering the information listed in part 3 of the Requirements page into the database. This data entry should be done by a shifter or expert - the steps have been included here for their reference. If you are not authorized to deal with the database, please make sure the data has been entered and skip to the next numbered step.
If you use the database browser to look at "SAM: Data Disks", you will see entries containing a station name, a node name, and a corresponding node mount point. The combination of these pieces of information is what SAM uses to locate disks/directories. The node name is a simple string that, when combined with the node mount point, must be uniquely assigned to one station. If they do not already exist, you will need to create these "data disk" pathways for your station.
Note: When adding database information for a station that is not running, you will see error messages about the database not being able to connect to the station. This is okay and does not mean that the commands you issued have failed. Information that the database needs to communicate to the station will be taken care of once the station is started.
Also Note: The following several steps make use of the
samadmin command. You should execute them
as user "sam" (or any other registered station
administrator). Otherwise you will be prompted for a password
after every command. You may still be prompted in some cases.
To avoid a lot of re-typing, you can either include your
username/password in the command line using
--connect=, or you can set the environmental
variable SAM_ORACLE_CONNECT. If you use the
environmental variable
be sure to unset it when you are done!
Warning: Passwords containing dollar signs
("$") do not play nicely with
--connect= or SAM_ORACLE_CONNECT.
You must insert a backslash ("\") before each
dollar sign to force correct parsing.
If this new station will have an administrator that does not have a "person" entry in the database, you will need to create that entry. Note that having a user account that allows you access to the database is not the same as having a "person" entry in the database. The command is:
The parameter <username> is the person's account username. The other parameters are self-explanatory and optional, though very helpful so try to supply them. Note that if a parameter value is more than one word, you need to enclose the phrase in quotes (").
Add the new station's name to the database. The command is:
The parameter <stationname> is the name you want the new station to be called, <adminlist> is a comma-separated (but not space-separated) list of usernames who will administer the station, and <descrip> is a brief description of the station's purpose. Note that if the description is more than one word, you must enclose the phrase in quotes (").
Add a node name to the database. The node name should either be a machine name alias, or a dCache port alias. The command is:
where <hwtype> is the type of
machine (usually "PC"),
<ostype> is the flavor of
operating system running on the station machine (usually
"linux"), and
<nodename> is the alias you
want to use for your mount point. If several mount points
will be used, repeat the command (with a different name)
for each point.
While the node name is really just an
alias and has no physical meaning, do try to follow the
structure of entries already in the database when you create
a new one. For example, if your station is assigned a
door/port on the machine cdfdca, the command
should look something like this:
The last character can be used to group all the doors being used by a single station, and the integers can be incremented when a single station uses multiple doors. This convention is just a suggestion and is not consistant across the database.
Alternatively, if your station is using its own hard drive(s)
for a cache and it resides on the machine called
"cdfsam00.fnal.gov", the command should look
like this:
If your station is using dCache and will have a large number
of data disks, you should probably use an intermediate cache
to make successive file access faster. Such a node is called
a "backbone". To use one, start by adding an extra node now
with "-backbone" in place of the
"-door<nn>" part of the
node name.
Now you can create a full cache pathway by adding the disk/directory location(s) to the database:
The parameter <hostname>
is the full name of the machine that hosts the port your
station will connect to,
<pathname>
is the absolute path of the SAM cache disk/directory, and
<disksize> is the
available space, e.g. 20GB. You should use
only 95% of the actual disk size to allow some buffer.
Make sure only one SAM station writes to any given path.
Here is an example for a standard hard drive. The cache
pathway is /sam/cache1 on machine
cdfsam00 for a station called
cdf-blah. The cache1 directory is
partitioned to be 4 gigabytes. The station name and node
name have been entered in the previous steps. The command to
create the last part of the data disk pathway is:
For a station that connects to dCache, the path format is
a little different. For example, you were told to use port
26125 on machine cdfdca for your
station called cdf-blah. Your cache space is
80 gigabytes. You have already entered the node name
"dcap://cdfdca-door01j" into the
database in the previous step. The command to create the data
disk entry is:
If you want to use a "backbone", you will need to give it a path as well. It usually shares one of the ports already in use by your station. In such a case, you should make the size of the backbone disk such that the sizes of the regular station disks add up to the size of the backbone disk.
If you want to remove a disk, there are two steps. If the disk is in use, you have to stop users from accessing it by issuing the command:
To remove the entry from the database, issue the command:
Add the name of the group to whom the station belongs.
For CDF, the group name is test. For DZero,
the group name is dzero. Set the maximum disk
space value according to your available disk size. The
command is:
The parameter <maxprojects>
is the limit on the number of projects that can be run
concurrently by members of the group (usually on the order
of 10-1000).
Remember to un-set the environmental variable
SAM_ORACLE_CONNECT (if you used it).
Stations get the startup information they need from a server list file. Edit the file
to add new stations or modify existing ones. The first four
words on each line of the server list file describe the service
type, the sam_config qualifier, the
sam_config version number, and the service name,
respectively. For a station, the first four words of the line
should look similar to this:
If adding a new station, here is a list of typical configuration parameters that complete the server file line.
Replace <disk_list> with a comma-separated list of the node names (as created in the database). Make sure there are no spaces in the list.
If a backbone node was created for the station, include the
--constrain-delivery parameter, replacing
<backbone_mountPoint> with the
backbone node name as entered in the database.
Further information about the station options can be found here or in the SAM documentation.
In the event of any problems the station sends automatic emails.
If you want these emails to be sent to an address other than
the default cdfsam-auto@fnal.gov, you have to "tailor"
sam_bootstrap:
Use the default for anything other than the email address.
If any sam product has been tailored and the product gets
updated to newer version, you might have to tailor it again.
Fortunately some of the configuration files are backed-up and can
be restored. To check what has changed and decide whether an old
configuration should be restored use the
restore_configs script in the backup directory:
Here <timestamp> indicates the date
and time when the init_sam script was run.
Do not restore an old configuration if you are unsure whether it is compatible with the new version.
If you stopped any stations with
"ups stop sam_bootstrap",
you can now start them with the following command:
Check the messages on the screen for errors.
If you just did the "Start station(s)" step and there were no problems, skip this step.
If you left a station running while making changes,
the station now needs to be informed of them. To do so, you can
use the ups update command to load the new
parameters without stopping the station:
This command can also be used to fix minor errors that might occur during the "Start station(s)" step (after the neccessary corrections are made, of course).
If you are unsure that all of the changes went into effect,
you can "restart" the station.
Warning: The "restart" command carries the
same possibility of job disruption as the "stop"
command. Follow the instructions for editing the server list
file as described in the
"Stop running station(s)" step.
Look at the modified station's log file:
Here, <flavor> is the type of
database you are connecting to ("dev",
"int", or "prd"). Control-C will exit
the tail -f command. If this seems okay,
dump information about the station:
If this command cannot connect to the station, double check that
you have the correct sam_config qualifier set up.
You can find out which qualification is currently set up using
The value listed after the "-q" option must be the
same as the qualifier in the server list file. If it is not,
set up the correct qualification using:
In case of problems try to figure out from the log file what the reason is. If you need help, contact cdfsam-admin@fnal.gov.
It is recommended to repeat these checks of the station after each of the following steps.
The following command will start a project for the dataset
definition test containing one single file
(ei031c2b.0001met0) and print the location of the
file in the cache after it was transfered to the station.
You can try this command as user "sam" or from
any other account if the SAM client is installed there.
If you want to test the file transfer, but the file is already in the station cache, you can remove the file from the cache before rerunning the test project:
Note: If you are trying to set up a station that uses
the integration database, the test dataset does not
exist there. Instead use test-sam-1g which contains
one file called gb01defd.0001exo0.
You may want to configure your station to use gridftp for file transfers. Follow the gridftp installation instructions.
If you are not already on the list it is recommended you subscribe to cdfsam-admin@fnal.gov in order to be informed about updates of the station software.