Prev   Next

Appendix B. Environmental Variables in GT 4.2.0

Table of Contents

1. Common Runtime Environmental Variables
1.1. Environmental variables for Java WS Core
1.2. Environmental variables for XIO
1.3. Environmental variables for C Common Libraries
2. Security Environmental Variables
2.1. Environmental Variables for GSI C
2.2. Environmental variables for WS Authentication & Authorization (Java)
2.3. Environmental variables for the Delegation Service
2.4. Environmental variables for CAS
2.5. Environmental variables for MyProxy
2.6. Environmental variables for GSI-OpenSSH
3. Data Management Environmental Variables
3.1. Environment variables for GridFTP
3.2. Environmental variables for RFT
3.3. Environmental variables for DRS
4. Execution Management Environmental Variables
4.1. Environment variables for GridWay

1. Common Runtime Environmental Variables

1.1. Environmental variables for Java WS Core

Table B.1. Globus standard environment variables

Name Value Description Comments
GLOBUS_LOCATION<path>The <path> is the root location of the Java WS Core installation. Must be an absolute path. Required
GLOBUS_TCP_PORT_RANGE<min,max>The <min,max> is the minimum and maximum port range for TCP server sockets (useful for systems behind firewalls). For example, if set, the notification sink on the client will be started within that port range. Optional
GLOBUS_TCP_SOURCE_PORT_RANGE<min,max>The <min,max> is the minimum and maximum port range for TCP outgoing sockets (useful for systems behind firewalls). Optional
GLOBUS_UDP_SOURCE_PORT_RANGE<min,max>The <min,max> is the minimum and maximum port range for UDP outgoing sockets (useful for systems behind firewalls). Optional
GLOBUS_HOSTNAME<host>The <host> is either a hostname or ip address. The host ip address under which the container and services will be exposed. Optional

Table B.2. Launch script specific environment variables

Name Value Description Comments
GLOBUS_OPTIONS<arguments> The <arguments> are arbitrary arguments that can be passed to the JVM. See below for a detailed list of supported options.Optional
JAVA_HOME<path>The <path> is the root location of the JVM installation. If set, the JVM from that installation will be used. Otherwise, the first one found in path will be used. Optional
CLASSPATH<classpath>This environment property is ignored by launch scripts. Ignored

Table B.3. Options supported by the GLOBUS_OPTIONS environment property

Name Value Description
-Dorg.globus.wsrf.proxy.portintThis property specifies the port number of the proxy server. The proxy server must run on the same machine as the container. This setting will cause the service address to have the port of the proxy instead of the container (only applies to code that uses the ServiceHost or AddressingUtils API.
-Dorg.globus.wsrf.container.server.idstringThis property specifies the server id. The server id is used to uniquely identify each container instance. For example, each container gets its own persistent directory based on the server id. By default the standalone container will store the persistent resources under the ~/.globus/persisted/<ip>-<containerPort> directory. While in Tomcat the ~/.globus/persisted/<ip>-<webApplicationName> directory will be used instead. This property overwrites the default server id and therefore indirectly controls which storage directory is used by the container. If set, the container will store the persisted resources under ~/.globus/persisted/<server.id>/ instead. Note, that if somehow multiple containers running as the same user on the same machine end up with the same server id / persistent directory they might overwrite each other's persistent data.
-Dorg.globus.wsrf.container.persistence.dirdirectoryThis property specifies the base directory that will be used for storing the persistent resources. This property overwrites the default (~/.globus/persisted/) base directory assumed by the container.

Any JVM options can also be passed using the GLOBUS_OPTIONS environment property.

1.2. Environmental variables for XIO

The vast majority of the environment variables that effect the Globus XIO framework are defined by the driver in use. The following are links to descriptions of the more common driver environment variables:

1.3. Environmental variables for C Common Libraries

  • GLOBUS_ERROR_VERBOSE=1 can be set to enable verbose error messages.
  • GLOBUS_ERROR_OUTPUT=1 can be set to enable output of all errors (including some that should be ignored).

2. Security Environmental Variables

2.1. Environmental Variables for GSI C

2.1.1. Credentials

Credentials are looked for in the following order:

  1. service credential

  2. host credential

  3. proxy credential

  4. user credential

X509_USER_PROXY specifies the path to the proxy credential. If X509_USER_PROXY is not set, the proxy credential is created (by grid-proxy-init) and searched for (by client programs) in an operating-system-dependent local temporary file.

X509_USER_CERT and X509_USER_KEY specify the path to the end entity (user, service, or host) certificate and corresponding private key. The paths to the certificate and key files are determined as follows:

For service credentials:

  1. If X509_USER_CERT and X509_USER_KEY exist and contain a valid certificate and key, those files are used.
  2. Otherwise, if the files /etc/grid-security/service/servicecert and /etc/grid-security/service/servicekey exist and contain a valid certificate and key, those files are used.
  3. Otherwise, if the files $GLOBUS_LOCATION/etc/grid-security/service/servicecert and $GLOBUS_LOCATION/etc/grid-security/service/servicekey exist and contain a valid certificate and key, those files are used.
  4. Otherwise, if the files service/servicecert and service/servicekey in the user's .globus directory exist and contain a valid certificate and key, those files are used.

For host credentials:

  1. If X509_USER_CERT and X509_USER_KEY exist and contain a valid certificate and key, those files are used.
  2. Otherwise, if the files /etc/grid-security/hostcert.pem and /etc/grid-security/hostkey.pem exist and contain a valid certificate and key, those files are used.
  3. Otherwise, if the files $GLOBUS_LOCATION/etc/grid-security/hostcert.pem and $GLOBUS_LOCATION/etc/grid-security/hostkey.pem exist and contain a valid certificate and key, those files are used.
  4. Otherwise, if the files hostcert.pem and hostkey.pem in the user's .globus directory, exist and contain a valid certificate and key, those files are used.

For user credentials:

  1. If X509_USER_CERT and X509_USER_KEY exist and contain a valid certificate and key, those files are used.
  2. Otherwise, if the files usercert.pem and userkey.pem exist in the user's .globus directory, those files are used.
  3. Otherwise, if a PKCS-12 file called usercred.p12 exists in the user's .globus directory, the certificate and key are read from that file.

2.1.2. Gridmap file

GRIDMAP specifies the path to the grid map file, which is used to map distinguished names (found in certificates) to local names (such as login accounts). The location of the grid map file is determined as follows:

  1. If the GRIDMAP environment variable is set, the grid map file location is the value of that environment variable.

  2. Otherwise:

    • If the user is root (uid 0), then the grid map file is /etc/grid-security/grid-mapfile.
    • Otherwise, the grid map file is $HOME/.gridmap.

2.1.3. Trusted CAs directory

X509_CERT_DIR is used to specify the path to the trusted certificates directory. This directory contains information about which CAs are trusted (including the CA certificates themselves) and, in some cases, configuration information used by grid-cert-request to formulate certificate requests. The location of the trusted certificates directory is determined as follows:

  1. If the X509_CERT_DIR environment variable is set, the trusted certificates directory is the value of that environment variable.
  2. Otherwise, if $HOME/.globus/certificates exists, that directory is the trusted certificates directory.
  3. Otherwise, if /etc/grid-security/certificates exists, that directory is the trusted certificates directory.
  4. Finally, if $GLOBUS_LOCATION/share/certificates exists, then it is the trusted certificates directory.

2.1.4. GSI authorization callout configuration file

GSI_AUTHZ_CONF is used to specify the path to the GSI authorization callout configuration file. This file is used to configure authorization callouts used by both the gridmap and the authorization API. The location of the GSI authorization callout configuration file is determined as follows:

  1. If the GSI_AUTHZ_CONF environment variable is set, the authorization callout configuration file location is the value of this environment variable.
  2. Otherwise, if /etc/grid-security/gsi-authz.conf exists, then this file is used.
  3. Otherwise, if $GLOBUS_LOCATION/etc/gsi-authz.conf exists, then this file is used.
  4. Finally, if $HOME/.gsi-authz.conf exists, then this file is used.

2.1.5. GAA (Generic Authorization and Access control) configuration file

GSI_GAA_CONF is used to specify the path to the GSI GAA (Generic Authorization and Access control) configuration file. This file is used to configure policy language specific plugins to the GAA-API. The location of the GSI GAA configuration file is determined as follows:

  1. If the GSI_GAA_CONF environment variable is set, the GAA configuration file location is the value of this environment variable.
  2. Otherwise, if /etc/grid-security/gsi-gaa.conf exists, then this file is used.
  3. Otherwise, if $GLOBUS_LOCATION/etc/gsi-gaa.conf exists, then this file is used.
  4. Finally, if $HOME/.gsi-gaa.conf exists, then this file is used.

2.1.6. Grid security directory

GRID_SECURITY_DIR specifies a path to a directory containing configuration files that specify default values to be placed in certificate requests. This environment variable is used only by the grid-cert-request and grid-default-ca commands.

The location of the grid security directory is determined as follows:

  1. If the GRID_SECURITY_DIR environment variable is set, the grid security directory is the value of that environment variable.
  2. If the configuration files exist in /etc/grid-security, the grid security directory is that directory.
  3. if the configuration files exist in $GLOBUS_LOCATION/etc, the grid security directory is that directory.

2.2. Environmental variables for WS Authentication & Authorization (Java)

Refer to Configuring for environment variables. Note that the above environment variables do not supersede any settings provided in security descriptors.

2.3. Environmental variables for the Delegation Service

Refer to the environment variable interface for details.

The environment variables described above only affect the selection of credentials if no credentials are specified in any of the applicable security descriptors.

2.4. Environmental variables for CAS

All CAS client programs use the following environment variables to determine the appropriate URL to connect to and server identity to expect. In all cases, the command line options takes precedence over the environment variables.

  • The URL is determined using this algorithm:

    • If the -c command line option was specified, the URL specified with that option is used.
    • Otherwise, the CAS_SERVER_URL environment variable must be set, and its value is used.

  • The server identity (i.e. the expected subject name of the CAS server certificate) is determined as follows:

    • If the -s command line option was specified, the value specified with that option is used as the identity
    • Otherwise, if the CAS_SERVER_IDENTITY environment variable is set, the value of that variable is used as the expected server identity. Ensure that the value is enclosed within double quotes if there are spaces in the DN. The double quotes are required by the CAS scripts when they are run from a Windows shell, although the shell does not require it even if the value has spaces.
    • If neither is set, host authorization is done and the expected server credential is cas/<fqdn>, where <fqdn> is the fully qualified domain name of the host on which the CAS service is up.

2.5. Environmental variables for MyProxy

Table B.4. Environment variables

MYPROXY_SERVER Specifies the hostname where the myproxy-server is running. This environment variable can be used in place of the -s option.
MYPROXY_SERVER_PORT Specifies the port where the myproxy-server is running. This environment variable can be used in place of the -p option.
MYPROXY_SERVER_DN Specifies the distinguished name (DN) of the myproxy-server. All MyProxy client programs authenticate the server's identity. By default, MyProxy servers run with host credentials, so the MyProxy client programs expect the server to have a distinguished name of the form "host/<fqhn>" or "myproxy/<fqhn>" (where <fqhn> is the fully-qualified hostname of the server). If the server is running with some other DN, you can set this environment variable to tell the MyProxy clients to accept the alternative DN.
X509_USER_CERT Specifies a non-standard location for the certificate from which the proxy credential is created by myproxy-init. It also specifies an alternative location for the server's certificate. By default, the server uses /etc/grid-security/hostcert.pem when running as root or ~/.globus/usercert.pem when running as non-root.
X509_USER_KEY Specifies a non-standard location for the private key from which the proxy credential is created by myproxy-init. It also specifies an alternative location for the server's private key. By default the server uses /etc/grid-security/hostkey.pem when running as root or ~/.globus/userkey.pem when running as non-root.
X509_USER_PROXY Specifies an alternative location for the server's certificate and private key (in the same file). Use when running the server with a proxy credential. Note that the proxy will need to be periodically renewed before expiration to allow the myproxy-server to keep functioning. When the myproxy-server runs with a non-host credential, clients must have the MYPROXY_SERVER_DN environment variable set to the distinguished name of the certificate being used by the server.
GLOBUS_LOCATION Specifies the root of the MyProxy installation, used to find the default location of the myproxy-server.config file and the credential storage directory.
LD_LIBRARY_PATH The MyProxy server is typically linked dynamically with Globus security libraries, which must be present in the dynamic linker's search path. This typically requires $GLOBUS_LOCATION/lib to be included in the list in the LD_LIBRARY_PATH environment variable, which is set by the $GLOBUS_LOCATION/libexec/globus-script-initializer script, which should be called from any myproxy-server startup script. Alternatively, to set LD_LIBRARY_PATH appropriately for the Globus libraries in an interactive shell, source $GLOBUS_LOCATION/etc/globus-user-env.sh (for sh shells) or $GLOBUS_LOCATION/etc/globus-user.env.csh (for csh shells).
GT_PROXY_MODE Set to "old" to use the "legacy globus proxy" format. By default, MyProxy uses the RFC 3820 compliant proxy (also known as "proxy draft compliant") format. If GT_PROXY_MODE is set to "old", then myproxy-init will store a legacy proxy and myproxy-logon will retrieve a legacy proxy (if possible). Note that if the repository contains a proxy certificate, rather than an end-entity certificate, the retrieved proxy will be of the same type as the stored proxy, regardless of the setting of this environment variable.

2.6. Environmental variables for GSI-OpenSSH

The GSI-enabled OpenSSHD needs to be able to find certain files and directories in order to properly function.

The items that OpenSSHD needs to be able to locate, their default location and the environment variable to override the default location are:

  • Host key

    Default location: /etc/grid-security/hostkey.pem

    Override with X509_USER_KEY environment variable

  • Host certificate

    Default location: /etc/grid-security/hostcert.pem

    Override with X509_USER_CERT environment variable

  • Grid map file

    Default location: /etc/grid-security/grid-mapfile

    Override with GRIDMAP environment variable

  • Certificate directory

    Default location: /etc/grid-security/certificates

    Override with X509_CERT_DIR environment variable

3. Data Management Environmental Variables

3.1. Environment variables for GridFTP

The GridFTP server or client libraries do not read any environment variable directly, but the security and networking related variables described below may be useful.

3.2. Environmental variables for RFT

The only environment variable that needs to be set for RFT is GLOBUS_LOCATION, in order to run the command line clients, which should be set to the location of the globus installation.

3.3. Environmental variables for DRS

  • GLOBUS_LOCATION=/path/to/globus/install

4. Execution Management Environmental Variables

4.1. Environment variables for GridWay

[Important]Important

You should include the following environment variables in your shell configuration file. (example $HOME/.bashrc)

In order to set the user environment, follow these steps:

  1. Set up Globus user environment: 

    $ source $GLOBUS_LOCATION/etc/globus-user-env.sh

    or 

    $ . $GLOBUS_LOCATION/etc/globus-user-env.csh

    depending on the shell you are using.

  2. Set up the GridWay user environment: 

    	$ export GW_LOCATION=<path_to_GridWay_installation>
	$ export PATH=$PATH:$GW_LOCATION/bin

    or 

    	$ setenv GW_LOCATION <path_to_GW_location>
	$ setenv PATH $PATH:$GW_LOCATION/bin

    depending on the shell you are using.

  3. Optionally, you can set up your environment to use the GridWay DRMAA library: 

    	$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$GW_LOCATION/lib

    or: 

    	$ setenv LD_LIBRARY_PATH $LD_LIBRARY_PATH:$GW_LOCATION/lib

  4. If GridWay has been compiled with accounting support, you may need to set up the DB library. For example, if DB library has been installed in /usr/local/BerkeleyDB.4.4: 

    $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/BerkeleyDB.4.4/lib

    [Note]Note

    This step is only needed if your environment has not been configured, ask your administrator.

  5. DRMAA extensions for all the languages use the dynamic drmaa libraries provided by GridWay. To use this libraries it is needed to tell the operating system where to look for them. Here are described the steps needed to do this in Linux and MacOS X.

    • 1. In linux we have two ways to do this, one is using environment variables and the other one is modifying systemwide library path configuration. You only need to use one of this methods. If you do not have root access to the machine you are using or you do not want to setup it for every user in your system you have to use the environment variable method.

      • 1.1 The environment variable you have to set so the extensions find the required DRMAA library is LD_LIBRARY_PATH with a line similar to: 

        export LD_LIBRARY_PATH=$GW_LOCATION/lib

        If you want to setup this systemwide you can put this line alongside GW_LOCATION setup into /etc/profile. If you do not have root access or you want to do it per user the best place to do it is in the user's .bashrc.

        You can also do this steps in the console before launching your scripts as it will have the same effect.

      • Systems that use GNU/libc (GNU/Linux is one of them) do have a systemwide configuration file with the paths where to look for dynamic libraries. You have to add this line to /etc/ld.so.conf: 

        <path_to_gridway_installation>/lib

        After doing this you have to rebuild the library cache issuing this command: 

        # ldconfig

    • In MacOS X you have to use the environment variable method described for Linux but this time the name of the variable is DYLD_LIBRARY_PATH.

Prev   Next
Appendix A. Packaging details Home Appendix C. Installing SimpleCA