User Environment

From SRB

(This use to be the readme.dir/README.utilities document.)


Before a SRB client (Scommands or C client API or Jargon) can connect to the SRB server, the SRB user environment must be setup. There are two ways to accomplish this:

Contents

1) Have an environment file called .MdasEnv.

This file is located in the .srb sub-directory in your home directory. (Windows has difficulty creating a file or directory beginning with "." so the Windows Scommands look for the file in your home directory\srb. i.e. C:\Documents and Settings\myUserName\srb. The Jargon API will look for either directory. This file contains information for initializing the SRB client environment.) (A template of the MdasEnv file) This is a text file that contains lines of parameter/value pair where each values are in quote. The parameters are given in the following:

i) mdasCollectionHome - This is equivalent to the user's home directory (collection) and is created by the MCAT administrator at the time of the user registration.
ii) mdasDomainHome - This is the domain name associated with the user. This domain name is assigned to the user at the time of the user registration.
iii) srbUser - This is the user name of the user. This name is assigned to the user at the time of the user registration.
iv) srbHost - This is the default host address of the SRB server when a SRB client initiates a SRB connection. This parameter can be overridden at run time by setting the environment variable 'srbHost'.
v) srbPort (optional) - This is the port number of the SRB server.
If 'srbPort' is not specified, it will default to port number 5544.
vi) AUTH_SCHEME (optional) - This parameter defines the authentication scheme to be used. Valid input values are:
'ENCRYPT1' - A password scheme with the passwords encrypted going from clients to servers.
'GSI_AUTH' - Use the GSI authentication scheme. If this option is chosen, an additional parameter SERVER_DN given below is required.
'GSI_DELEGATE' - Use the GSI Delegation (proxy) certificate for authentication. The advantage is that this certificate can be passed from server to server whereby the user's identity continues to be maintained across servers and across zones. This scheme solves the cross zone authentication issues. A slight drawback is that the overhead is somewhat higher than the normal 'GSI_AUTH' scheme. If this option is chosen, an additional parameter SERVER_DN given below is required.
'GSI_SECURE_COMM' - Use the GSI authentication scheme and use the GSI I/O library for all socket communication between client and server. If this option is chosen, an additional parameter SERVER_DN given below is required. If this parameter is not defined, the 'ENCRYPT1' Authentication scheme will be used.
vii) SERVER_DN(optional) - This is the "Distinguish Name" of the user running the SRB server. Value for this parameter can be obtained from the SRB administrator. This input is meaningful only if the authentication scheme 'GSI_AUTH' or 'GSI_SECURE_COMM' is chosen.
viii) defaultResource (optional but recommended) - The reosurce to use if a user does not specify a resource in some Scommands (Sput, Scp, Sreplicate, etc).
ix) mcatZone (optional but recommended) - The Zone associated with this user. If this parameter is not given, the SRB server will query the MCAT for it. But this will add to the overhead.


2) Use the UNIX environment variables to specify these parameters.

This method of specification overrides those specified using the .MdasEnv file. Environment variables recognized by the Scommands are:

i) srbUser - The client user
ii) mdasDomainName - The domain of the client user
iii) srbHost - The hostname of the SRB-server
iv) srbPort - The port number of the SRB-server (optional)
v) mdasResourceName or defaultResource - The default resource
vi) mdasCollectionName - The current working collection.
vii) srbAuth - The password.
viii) AUTH_SCHEME - The authentication scheme to be used.
ix) SERVER_DN - The distinguished name of the server user (valid only for GSI authentication).
x) mcatZone (optional but recommended) - The Zone associated with this user.


Other relevant environment variables :

i) mdasEnvFile - Instead of the .srb/.MdasEnv file, this env variable specifies the alternative path for this file.
ii) mdasAuthFile - Instead of the .srb/.MdasAuth file, this env variable specifies the alternative path for this file.


Setting up user authentication

The SRB software can be built to handle ENCRYPT1 by default or to include GSI_AUTH if the --enable-gsi-auth option of the "configure" command is used when configuring the software for build.

At runtime, a client may choose an authentication scheme to use by defining the AUTH_SCHEME parameter in the .MdasEnv file. Each authentication scheme requires a different setup by the user.

Each authentication scheme requires a different setup by the user.

i) ENCRYPT1 setup - This is a plain text password setup where the password is generated at the time of user registration with the MCAT catalog. Upon receiving this password from the MCAT administrator, a user should place it in a file named ~/.srb/.MdasAuth which will be used by the SRB library to authenticate the user.
ii) GSI_AUTH setup - Please read GSI and follow the HTTP links for obtaining certificate/key and GSI server environment setup suggested by in the document. Once the certification/key has been obtained and converted to PEM format for GSI use, look into the cert pem file with a text editor and locate the user "Distinguish Name" string. The string representing the "Distinguish Name" should look like the following:
          subject=/C=US/O=NPACI/OU=SDSC/UID=srb/CN=Storage Resource Broker/Email=srb@sdsc.edu

Copy this string and register it as the "Distinguish Name" of the SRB server user. Supply this string to all clients for use as the SERVER_DN input in the clients' ~/.srb/.MdasEnv files.


Every time, you use the Client Utilities, from a new shell run 'Sinit' to initialize the environment and to check connection with SRBMaster. Running Sinit in the middle of a session will reset the client environmental file variables.


Use Sexit when finished with using Scommands. Use Serror to find the meaning of error numbers generated when running Scommands. The SRB_SRC env variable which defines the SRB source directory must be defined to be the 'src' sub-directory in the SRB's directory.

See also