Note

The Grid Community Toolkit documentation was taken from the Globus Toolkit 6.0 documentation. As a result, there may be inaccuracies and outdated information. Please report any problems to the Grid Community Forums as GitHub issues.

GCTAppendices → Grid Community Toolkit 6.2 Command-Line Tools

GSI Commands

GLOBUS-UPDATE-CERTIFICATE-DIR(8)

NAME

globus-update-certificate-dir - Update symlinks in the trusted CA directory

SYNOPSIS

globus-update-certificate-dir [-help ] [-d DIRECTORY]

Description

The globus-update-certificate-dir program creates symlinks between files (CA certificates, certificate revocation lists, signing policy, and certificate request configuration files) using the certificate hash the installed version of OpenSSL uses. OpenSSL 1.0.0 uses a different name hashing algorithm than previous versions, so CA distributions created with older versions of OpenSSL might not be able to locate trusted CAs and related files. Running globus-update-certificate-dir against a trusted CA directory will add symlinks to the files to the hash if needed.

The full set of command-line options to globus-update-certificate-dir consists of:

-help

Display a help message to standard output and exit

-d DIRECTORY

Create links in the trusted CA directory DIRECTORY instead of using the default search path.

Environment

If the following variables affect the execution of globus-update-certificate-dir

X509_CERT_DIR

Default trusted certificate directory.

HOME

Path to the current user’s home directory.

GLOBUS_LOCATION

Path to the GCT installation.

GRID-CERT-DIAGNOSTICS(1)

NAME

grid-cert-diagnostics - Print diagnostic information about certificates and keys

SYNOPSIS

grid-cert-diagnostics [-h ] | [-help ] [-p ] [-n ] [-c CERTIFICATE]

Description

The grid-cert-diagnostics program displays information about the current user’s security environment, including information about security-related environment variables, security directory search path, personal key and certificates, and trusted certificates. It is intended to provide information to help diagnose problems using GSIC.

By default, grid-cert-diagnostics prints out information regarding the environment and trusted certificate directory. If the -p command-line option is used, then additional information about the current user’s default certificate and key will be printed.

The full set of command-line options to grid-cert-diagnostics consists of:

-h, -help

Display a help message and exit.

-p

Display information about the personal certificate and key that is the current user’s default credential.

-n

Check time synchronization with the ntpdate command.

-c CERTIFICATE, -c -

Check the validity of the certificate in the file named by CERTIFICATE or standard input if the parameter to -c is -.

Examples

In this example, we see the default mode of checking the default security environment for the system, without processing the user’s key and certificate. Note the user receives a warning about a cog.properties and about an expired CA certificate. and about an expired CA certificate.

%  grid-cert-diagnostics

Checking Environment Variables
==============================
Checking if X509_CERT_DIR is set... no
Checking if X509_USER_CERT is set... no
Checking if X509_USER_KEY is set... no
Checking if X509_USER_PROXY is set... no

Checking Security Directories
=======================
Determining trusted cert path... /etc/grid-security/certificates
Checking for cog.properties... found
    WARNING: If the cog.properties file contains security properties,
             Java apps will ignore the security paths described in the GSI
             documentation

Checking trusted certificates...
================================
Getting trusted certificate list...
Checking CA file /etc/grid-security/certificates/1c4f4c48.0... ok
Verifying certificate chain for "/etc/grid-security/certificates/1c3f2ca8.0"... ok
Checking CA file /etc/grid-security/certificates/9d8788eb.0... ok
Verifying certificate chain for "/etc/grid-security/certificates/9d8753eb.0"... failed
    globus_credential: Error verifying credential: Failed to verify credential
    globus_gsi_callback_module: Could not verify credential
    globus_gsi_callback_module: The certificate has expired:
    Credential with subject: /DC=org/DC=example/OU=grid/CN=CA has expired.

In this example, we show a user with a mismatched private key and certificate:

%  grid-cert-diagnostics -p

Checking Environment Variables
==============================
Checking if X509_CERT_DIR is set... no
Checking if X509_USER_CERT is set... no
Checking if X509_USER_KEY is set... no
Checking if X509_USER_PROXY is set... no

Checking Security Directories
=======================
Determining trusted cert path... /etc/grid-security/certificates
Checking for cog.properties... not found

Checking Default Credentials
==============================
Determining certificate and key file names... ok
Certificate Path: "/home/juser/.globus/usercert.pem"
Key Path: "/home/juser/.globus/userkey.pem"
Reading certificate... ok
Reading private key...
ok
Checking Certificate Subject...
"/O=Grid/OU=Example/OU=User/CN=Joe User"
Checking cert... ok
Checking key... ok
Checking that certificate contains an RSA key... ok
Checking that private key is an RSA key... ok
Checking that public and private keys have the same modulus... failed
Private key modulus: D294849E37F048C3B5ACEEF2CCDF97D88B679C361E29D5CB5
219C3E948F3E530CFC609489759E1D751F0ACFF0515A614276A0F4C11A57D92D7165B8
FA64E3140155DE448D45C182F4657DA13EDA288423F5B9D169DFF3822EFD81EB2E6403
CE3CB4CCF96B65284D92592BB1673A18354DA241B9AFD7F494E54F63A93E15DCAE2
Public key modulus : C002C7B329B13BFA87BAF214EACE3DC3D490165ACEB791790
600708C544175D9193C9BAC5AED03B7CB49BB6AE6D29B7E635FAC751E9A6D1CEA98022
6F1B63002902D6623A319E4682E7BFB0968DCE962CF218AAD95FAAD6A0BA5C42AA9AAF
7FDD32B37C6E2B2FF0E311310AA55FFB9EAFDF5B995C7D9EEAD8D5D81F3531E0AE5
Certificate and and private key don't match

GRID-CERT-INFO(1)

NAME

grid-cert-info - Display information about a certificate

SYNOPSIS

grid-cert-info [-help ] [-usage ] [-version ] [-versions ]

Description

The grid-cert-info program displays information contained within a certificate file. By default it shows a text representation of the entire certificate. Specific facts about the certificate can be shown instead by using command-line options. If any of those options are used, then the default display is suppressed. This can be added to the output by using the -all command-line option.

If multiple display options are included on the command-line, the facts related to those will be displayed on separate lines in the order that they occur. If an option is specified multiple time, that fact will be displayed multiple times.

The full set of command-line options to grid-cert-info are:

-help, -usage

Display the command-line options to grid-cert-info and exit.

-version, -versions

Display the version number of the grid-cert-info command. The second form includes more details.

-file CERTIFICATE-FILE

Display information about the first certificate contained in the file named by CERTIFICATE-FILE instead of the default user certificate.

-rfc2253

Display X.509 distinguished names using the string representation defined in RFC 2253 instead of the default OpenSSL oneline format.

-all

Display the text representation of the entire certificate in addition to any other facts requested by command-line options. This is the default if no fact-specific command-line options are used.

-subject, -s

Display the subject name of the X.509 certificate.

-issuer, -i

Display the issuer name of the X.509 certificate.

-issuerhash, -ih

Display the default hash of the issuer name of the X.509 certificate. This can be used to locate which CA certificate in the trusted certificate directory issued the certifcate being inspected.

-startdate, -sd

Display a string representation of the date and time when the certificate is valid from. This is displayed in the format used by the OpenSSL x509 command.

-enddate, -dd

Display a string representation of the date and time when the certificate is valid until. This is displayed in the format used by the OpenSSL x509 command.

Examples

Display the validity times for the default certificate

%  grid-cert-info -sd -ed
Aug 31 12:33:47 2009 GMT
Aug 31 12:33:47 2010 GMT

Display the same information about a different certificate specified on the command-line

%  grid-cert-info -sd -ed -f /etc/grid-security/hostcert.pem
Jan 21 12:24:48 2003 GMT
Jul 15 11:30:57 2020 GMT

Display the subject of a certificate in both the default and the RFC 2253 forms.

%  grid-cert-info -subject
/DC=org/DC=example/DC=grid/CN=Joe User
%  grid-cert-info -subject -rfc2253
CN=Joe User,DC=grid,DC=example,DC=org

Environment Variables

The following environment variables affect the execution of grid-cert-info:

X509_USER_CERT

Path to the default certificate file to inspect.

GRID-CERT-REQUEST(1)

NAME

grid-cert-request - Generate a X.509 certificate request and corresponding private key

SYNOPSIS

grid-cert-request [-help ] [-h ] [-? ] [-usage ]

[-version ] [-versions ]

Description

The grid-cert-request program generates an X.509 Certificate Request and corresponding private key for the specified name, host, or service. It is intended to be used with a CA implemented using the globus_simple_ca package.

The default behavior of grid-cert-request is to generate a certificate request and private key for the user running the command. The subject name is derived from the gecos information in the local system’s password database, unless the -commonname, -cn, or -host command-line options are used.

By default, grid-cert-request writes user certificate requests and keys to the $HOME/.globus directory, and host and service certificate requests and keys to directory, and host and service certificate requests and keys to /etc/grid-security. This can be overridden by using the . This can be overridden by using the -dir command-line option.

The full set of command-line options to grid-cert-request are:

-help, -h, -?, -usage

Display the command-line options to grid-cert-request and exit.

-version, -versions

Display the version number of the grid-cert-request command. The second form includes more details.

-cn NAME, -commonname NAME

Create a certificate request with the common name component of the subject set to NAME. This is used to create user identity certificates.

-dir DIRECTORY

Write the certificate request and key to files in the directory specified by DIRECTORY.

-prefix PREFIX

Use the string PREFIX as the base name of the certificate, certificate_request, and key files instead of the default. For a user certificate request, this would mean creating files $HOME/.globus/PREFIXcert_request.pem, , $HOME/.globus/PREFIXcert.pem, and , and $HOME/.globus/PREFIXkey.pem..

-ca CA-HASH

Use the certificate request configuration for the CA with the name hash CA-HASH instead of the default CA chosen by running grid-default-ca.

-verbose

Keep the output from the OpenSSL certificate request command visible after it completes, instead of clearing the screen..

-interactive, -int

Prompt for each component of the subject name of the request, instead of generating the common name from other command-line options. Note that CAs may not sign certificates for subject names that don’t match their signing policies.

-force

Overwrite any existing certificate request and private key with a new one.

-nopw, -nodes, -nopassphrase

Create an unencrypted private key for the certificate instead of prompting for a passphrase. This is the default behavior for host or service certificates, but not recommended for user certificates.

-host FQDN

Create a certificate request for use on a particular host. This option also causes the private key assoicated with the certificate request to be unencrypted. The FQDN argument to this option should be the fully qualified domain name of the host that will use this certificate. The subject name of the certificate will be derived from the FQDN and the service option if specified by the -service command-line option. If the host for the certificate has multiple names, then use either the -dns or -ip command-line options to add alternate names or addresses to the certificates.

-service SERVICE

Create a certificate request for a particular service on a host. The subject name of the certificate will be derived from the FQDN passed as the argument to the -host command-line option and the SERVICE string.

-dns FQDN,…​

Create a certificate request containing a subjectAltName extension containing one or more host names. This is used when a certificate may be used by multiple virtual servers or if a host has different names when contacted within or outside a private network. Multiple DNS names can be included in the extension by separating then with a comma.

-ip IP-ADDRESS,…​

Create a certificate request containing a subjectAltName extension containing the IP addresses named by the IP-ADDRESS strings. This is used when a certificate may be used by services listening on multiple networks. Multiple IP addresses can be included in the extension by separating then with a comma.

Examples

Create a user certificate request:

%  grid-cert-request
A certificate request and private key is being created.
You will be asked to enter a PEM pass phrase.
This pass phrase is akin to your account password,
and is used to protect your key file.
If you forget your pass phrase, you will need to
obtain a new certificate.
A private key and a certificate request has been generated with the subject:

/O=org/OU=example/OU=grid/CN=Joe User

If the CN=Joe User is not appropriate, rerun this
script with the -force -cn "Common Name" options.

Your private key is stored in /home/juser/.globus/userkey.pem
Your request is stored in /home/juser/.globus/usercert_request.pem

Please e-mail the request to the Example CA [email protected]
You may use a command similar to the following:

  cat /home/juser/.globus/usercert_request.pem | mail [email protected]

Only use the above if this machine can send AND receive e-mail. if not, please
mail using some other method.

Your certificate will be mailed to you within two working days.
If you receive no response, contact Example CA at [email protected]

Create a host certificate for a host with two names.

%  grid-cert-request -host grid.example.org -dns grid.example.org,grid-internal.example.org

A private host key and a certificate request has been generated
with the subject:

/O=org/OU=example/OU=grid/CN=host/grid.example.org

 ----------------------------------------------------------

The private key is stored in /etc/grid-security/hostkey.pem
The request is stored in /etc/grid-security/hostcert_request.pem

Please e-mail the request to the Example CA [email protected]
You may use a command similar to the following:

 cat /etc/grid-security/hostcert_request.pem | mail [email protected]

Only use the above if this machine can send AND receive e-mail. if not, please
mail using some other method.

Your certificate will be mailed to you within two working days.
If you receive no response, contact Example CA at
[email protected]

Environment Variables

The following environment variables affect the execution of grid-cert-request:

X509_CERT_DIR

Path to the directory containing SSL configuration files for generating certificate requests.

GRID_SECURITY_DIR

Path to the directory containing SSL configuration files for generating certificate requests. This value is used if X509_CERT_DIR is not set.

GLOBUS_LOCATION

Path to the directory containing the Grid Community Toolkit. This is searched if neither the X509_CERT_DIR nor the GRID_SECURITY_DIR environment variables are set.

Files

$HOME/.globus/usercert_request.pem

Default path to write a user certificate request.

$HOME/.globus/usercert.pem

Default path to write a user certificate.

$HOME/.globus/userkey.pem

Default path to write a user private key.

/etc/grid-security/hostcert_request.pem

Default path to write a host certificate request.

/etc/grid-security/hostcert.pem

Default path to write a host certificate.

/etc/grid-security/hostkey.pem

Default path to write a host private key.

TRUSTED-CERT-DIR/globus-user-ssl.conf, TRUSTED-CERT-DIR/globus-user-ssl.conf.CA-HASH

SSL configuration file for requesting a user certificate. The first form is the default location, the second form is used when the -ca command-line option is specified.

TRUSTED-CERT-DIR/globus-host-ssl.conf, TRUSTED-CERT-DIR/globus-host-ssl.conf.CA-HASH

SSL configuration file for requesting a host or service certificate. The first form is the default location, the second form is used when the -ca command-line option is specified.

GRID-DEFAULT-CA(8)

NAME

grid-default-ca - Select default CA for certificate requests

SYNOPSIS

grid-default-ca [-help ] [-h ] [-usage ] [-u ] [-version ] [-versions ]

Description

The grid-default-ca program sets the default certificate authority to use when the grid-cert-request script is run. The CA’s certificate, configuration, and signing policy must be installed in the trusted certificate directory to be able to request certificates from that CA. Note that some CAs have different policies and use other tools to handle certificate requests. Please consult your CA’s support staff if you unsure. The grid-default-ca is designed to work with CAs implemented using the globus_simple_ca package.

By default, the grid-default-ca program displays a list of installed CA certificates and the prompts the user for which one to set as the default. If invoked with the -list command-line option, grid-default-ca will print the list and not prompt nor set the default CA. If invoked with the -ca option, it will not list or prompt, but set the default CA to the one with the hash that matches the CA-HASH argument to that option. If grid-default-ca is used to set the default CA, the caller of this program must have write permissions to the trusted certificate directory.

The grid-default-ca program sets the CA in the one of the grid security directories. It looks in the directory named by the GRID_SECURITY_DIR environment, the X509_CERT_DIR, /etc/grid-security, and , and $GLOBUS_LOCATION/share/certificates. .

The full set of command-line options to grid-default-ca are:

-help, -h, -usage, -u

Display the command-line options to grid-default-ca and exit.

-version, -versions

Display the version number of the grid-default-ca command. The second form includes more details.

-dir CA-DIRECTORY

Use the trusted certificate directory named by CA-DIRECTORY instead of the default.

-list

Instead of changing the default CA, print out a list of all available CA certificates in the trusted certificate directory

-ca CA-HASH

Set the default CA without displaying the list of choices or prompting. The CA file named by CA-HASH must exist.

Examples

List the contents of the trusted certificate directory that contain the string Example:

%  grid-default-ca | grep Example
15) cd1186ff -  /DC=org/DC=Example/DC=Grid/CN=Example CA

Choose that CA as the default:

%  grid-default-ca -ca cd1186ff

setting the default CA to: /DC=org/DC=Example/DC=Grid/CN=Example CA

linking /etc/grid-security/certificates/grid-security.conf.cd1186ff to
        /etc/grid-security/certificates/grid-security.conf

linking /etc/grid-security/certificates/grid-host-ssl.conf.cd1186ff  to
        /etc/grid-security/certificates/grid-host-ssl.conf

linking /etc/grid-security/certificates/grid-user-ssl.conf.cd1186ff  to
        /etc/grid-security/certificates/grid-user-ssl.conf

...done.

Environment Variables

The following environment variables affect the execution of grid-default-ca:

GRID_SECURITY_DIRECTORY

Path to the default trusted certificate directory.

X509_CERT_DIR

Path to the default trusted certificate directory.

GLOBUS_LOCATION

Path to the Grid Community Toolkit installation directory.

Bugs

The grid-default-ca program displays CAs from all of the directories in its search list; however, grid-cert-request only uses the first which contains a grid security configuration.

The grid-default-ca program may display the same CA multiple times if it is located in multiple directories in its search path. However, it does not provide any information about which one would actually be used by the grid-cert-request command.

See Also

grid-cert-request(1)

GRID-CHANGE-PASS-PHRASE(1)

NAME

grid-change-pass-phrase - Change the passphrase of a private key

SYNOPSIS

grid-change-pass-phrase [-help ] [-usage ] [-version ] [-versions ]

Description

The grid-change-pass-phrase program changes the passphrase protecting a private key or PKCS12 bundle containing a private key and certificate. By default, grid-change-pass-phrase uses the X509_USER_KEY environment variable to locate the private key. If that is not set, then it looks for $HOME/.globus/userkey.pem and and $HOME/.globus/usercred.p12 in succession. The path to a key can be specified by using the in succession. The path to a key can be specified by using the -file command-line option.

The full set of command-line options to grid-change-pass-phrase are:

-help, -usage

Display the command-line options to grid-change-pass-phrase and exit.

-version, -versions

Display the version number of the grid-change-pass-phrase command. The second form includes more details.

-file PRIVATE-KEY

Change the passphrase of the private key named by PRIVATE-KEY instead of the default.

Examples

Change the passphrase of the default private key:

%  grid-change-pass-phrase

Enter pass phrase for /home/juser/.globus/userkey.pem:
writing RSA key
Enter PEM pass phrase:
Verifying - Enter PEM pass phrase:

Environment Variables

The following environment variables affect the execution of grid-change-pass-phrase:

X509_USER_KEY

Path to the default private key file.

GRID-PROXY-INIT(1)

NAME

grid-proxy-init - Generate a new proxy certificate

SYNOPSIS

grid-proxy-init [-help ] [-usage ] [-version ]

Description

The grid-proxy-init program generates X.509 proxy certificates derived from the currently available certificate files. By default, this command generates a RFC 3820 Proxy Certificate with a 512 bit key valid for 12 hours in a file named /tmp/x509up_uUID. Command-line options and variables can modify the format, strength, lifetime, and location of the generated proxy certificate. . Command-line options and variables can modify the format, strength, lifetime, and location of the generated proxy certificate.

X.509 proxy certificates are short-lived certificates, signed usually by a user’s identity certificate or another proxy certificate. The key associated with a proxy certificate is unencrypted, so applications can authenticate using a proxy identity without providing a passphrase.

Proxy certificates provide a convenient alternative to constantly entering passwords, but are also less secure than the user’s normal security credential. Therefore, they should always be user-readable only (this is enforced by the GSI libraries), and should be deleted after they are no longer needed.

This version of grid-proxy-init supports three different proxy formats: the old proxy format used in early releases of the Globus Toolkit up to version 2.4.x, an IETF draft version of X.509 Proxy Certificate profile used in Globus Toolkit 3.0.x and 3.2.x, and the RFC 3820 profile used in Globus Toolkit Version 4.0.x and 4.2.x. By default, this version of grid-proxy-init creates an RFC 3820 compliant proxy. To create a proxy compatible with older versions of the Globus Toolkit, use the -old or -draft command-line options.

The full set of command-line options to grid-proxy-init are:

-help, -usage

Display the command-line options to grid-proxy-init.

-version

Display the version number of the grid-proxy-init command

-debug

Display information about the path to the certificate and key used to generate the proxy certificate, the path to the trusted certificate directory, and verbose error messages

-q

Suppress all output from grid-proxy-init except for passphrase prompts.

-verify

Perform certificate chain validity checks on the generated proxy.

-valid HOURS:'MINUTES', -hours HOURS

Create a certificate that is valid for HOURS hours and MINUTES minutes. If not specified, the default of twelve hours and no minutes is used.

-cert CERTFILE, -key KEYFILE

Create a proxy certificate signed by the certificate located in CERTFILE using the key located in using the key located in KEYFILE. If not specified the default certificate and key will be used. This overrides the values of environment variables described below.. If not specified the default certificate and key will be used. This overrides the values of environment variables described below.

-certdir CERTDIR

Search CERTDIR for trusted certificates if verifying the proxy certificate. If not specified, the default trusted certificate search path is used. This overrides the value of the X509_CERT_DIR environment variable

-out PROXYPATH

Write the generated proxy certificate file to PROXYPATH instead of the default path of /tmp/x509up_uUID..

-bits BITS

When creating the proxy certificate, use a BITS bit key instead of the default 512 bit keys.

-policy POLICYFILE

Add the certificate policy data described in POLICYFILE as the ProxyCertInfo X.509 extension to the generated proxy certificate.

-pl POLICY-OID, -policy-language POLICY-OID

Set the policy language identifier of the policy data specified by the -policy command-line option to the oid specified by the POLICY-OID string.

-path-length MAXIMUM

Set the maximum length of the chain of proxies that can be created by the generated proxy to MAXIMUM. If not set, the default of an unlimited proxy chain length is used.

-pwstdin

Read the private key’s passphrase from stdin instead of reading input from the controlling tty. This is useful when scripting grid-proxy-init.

-limited

Create a limited proxy. Limited proxies are generally refused by process-creating services, but may be used to authorize with other services.

-independent

Create an independent proxy. An independent proxy is not treated as an impersonation proxy but as a separate identity for authorization purposes.

-draft

Create a IETF draft proxy instead of the default RFC 3280-compliant proxy. This type of proxy uses a non-standard proxy policy identifier. This might be useful for authenticating with older versions of the Globus Toolkit.

-old

Create a legacy proxy instead of the default RFC 3280-compliant proxy. This type of proxy uses a non-standard method of indicating that the certificate is a proxy and whether it is limited. This might be useful for authenticating with older versions of the Globus Toolkit.

-rfc

Create an RFC 3820-compliant proxy certificate. This is the default for this version of grid-proxy-init.

Examples

To create a proxy with the default lifetime and format, run the grid-proxy-init program with no arguments. For example:

%  grid-proxy-init
Your identity: /DC=org/DC=example/CN=Joe User
Enter GRID pass phrase for this identity: Creating proxy .................................. Done
Your proxy is valid until: Thu Mar 18 03:48:05 2010

To create a stronger proxy that lasts for only 8 hours, use the -hours and -bits command-line options to grid-proxy-init. For example:

%  grid-proxy-init -hours 8 -bits 1024
Your identity: /DC=org/DC=example/CN=Joe User
Enter GRID pass phrase for this identity: Creating proxy .................................. Done
Your proxy is valid until: Thu Mar 17 23:48:05 2010

Environment Variables

The following environment variables affect the execution of grid-proxy-init:

X509_USER_CERT

Path to the certificate to use as issuer of the new proxy.

X509_USER_KEY

Path to the key to use to sign the new proxy.

X509_CERT_DIR

Path to the directory containing trusted certifiate certificates and signing policies.

Files

The following files affect the execution of grid-proxy-init:

$HOME/.globus/usercert.pem

Default path to the certificate to use as issuer of the new proxy.

$HOME/.globus/userkey.pem

Default path to the key to use to sign the new proxy.

Compatibility

For more information about proxy certificate types and their compatibility in GT and GCT, see http://dev.globus.org/wiki/Security/ProxyCertTypes.

See Also

grid-proxy-destroy(1), grid-proxy-info(1)

GRID-PROXY-DESTROY(1)

NAME

grid-proxy-destroy - Destroy the default proxy certificate

SYNOPSIS

grid-proxy-destroy [-help ] [-usage ] [-version ]

Description

The grid-proxy-destroy program removes X.509 proxy files from the local filesystem. It overwrites the data in the files and removes the files from the filesystem. By default, it removes the current user’s default proxy (either /tmp/x509up_uUID where where UID is the current POSIX user id, or the file pointed to by the X509_USER_PROXY environment variable) unless a list of proxy file paths are included as part of the command line.

Use the -- command-line option to separate a list of proxy paths from command line options if the proxy file begins with the - character.

The full list of command-line options to grid-proxy-destroy are:

-help, -usage

Display the command-line options to grid-proxy-destroy.

-version

Display the version number of the grid-proxy-destroy command

-debug

Display verbose error messages.

-dryrun

Do not remove the proxy, but display the path of the files that would have been removed, or the directory where they would have been removed from if the -all command-line option is used.

-default

Remove the default proxy in addition to the files included on the command-line. Only needed if other paths are included on the command-line.

-all

Remove the default proxy and all delegated proxies in the temporary file directory.

Environment Variables

The following environment variables affect the execution of grid-proxy-destroy:

X509_USER_PROXY

Path to the default user proxy.

See Also

grid-proxy-init(1), grid-proxy-info(1)

GRID-PROXY-INFO(1)

NAME

grid-proxy-info - Display information about a proxy certificate

SYNOPSIS

grid-proxy-info [-help ] [-usage ] [-version ]

Description

The grid-proxy-info program extracts information from an X.509 proxy certificates, and optionally displays or returns an exit code based on that information.

The default mode of operation is to print the following facts about the current user’s default proxy: subject, issuer, identity, type, strength, path, and time left. If the command-line option -exists or -e is included in the command-line, nothing is printed unless one of the print options is specified. Instead, grid-proxy-info determines if a valid proxy exists and, if so, exits with the exit code 0; if a proxy does not exist or is not valid, grid-proxy-info exits with the exit code 1. Additional validity criteria can be added by using the -valid, -v, -hours, -h, -bits, or -b command-line options. If used, these options must occur after the -e or -exists command-line options. Those options are only valid if one of the -e or -exists command-line options is used.

The complete set of command-line options to grid-proxy-info are:

-help, -usage

Display the command-line options to grid-proxy-info.

-version

Display the version number of the grid-proxy-info command

-debug

Display verbose error messages.

-file PROXYFILE, -f PROXYFILE

Read the proxy located in the file PROXYFILE instead of using the default proxy.

-subject, -s

Display the proxy certificate’s subject distinguished name.

-issuer, -i

Display the proxy certificate issuer’s distinguished name.

-identity

Display the proxy certificate’s identity. For non-independent proxies, the identity is the subject of the certificate which issued the first proxy in the proxy chain.

-type

Display the type of proxy certificate. The type string includes the format ("legacy", "draft", or RFC 3280 compliant), identity type ("impersonation" or "independent"), and policy ("limited" or "full"). See grid-proxy-init(1) for information about how to create different types of proxies.

-timeleft

Display the number of seconds remaining until the proxy certificate expires.

-strength

Display the strength (in bits) of the key associated with the proxy certificate.

-all

Display the default information for the proxy when also using the -e or -exists command-line option.

-text

Display the proxy certificate contents to standard output, including policy information, issuer, public key, and modulus.

-path

Display the path to the file containing the default proxy certificate.

-rfc2253

Display distinguished names for the subject, issuer, and identity using the string representation described in RFC 2253, instead of the legacy format.

-exists, -e

Perform an existence and validity check for the proxy. If a valid proxy exists and matches the criteria described by other command-line options (if any), exit with 0; otherwise, exit with 1. This option must be before other validity check predicate in the command-line options. If this option is specified, the output of the default facts about the proxy is disabled. Use the -all option to have the information displayed as well as the exit code set.

-valid HOURS:'MINUTES', -v HOURS:'MINUTES', -hours HOURS, -h HOURS

Check that the proxy certificate is valid for at least HOURS hours and MINUTES minutes. If it is not, grid-proxy-info will exit with exit code 1.

-bits BITS, -b BITS

Check that the proxy certificate key strength is at least BITS bits.

Environment Variables

The following environment variables affect the execution of grid-proxy-info:

X509_USER_PROXY

Path to the default user proxy.

See Also

grid-proxy-init(1), grid-proxy-destroy(1)

GRID-MAPFILE-ADD-ENTRY(8)

NAME

grid-mapfile-add-entry - Add an entry to a gridmap file

SYNOPSIS

grid-mapfile-add-entry [-help ] [-usage ] [-version ] [-versions ]

Description

The grid-mapfile-add-entry program adds a new mapping from an X.509 distinguished name to a local POSIX user name to a gridmap file. Gridmap files are used as a simple authorization method for services such as GRAM5 or GridFTP.

The grid-mapfile-add-entry program verifies that the LOCAL-NAME is a valid user name on the system on which it was run, and that the mapping between DISTINGUISHED-NAME and LOCAL-NAME does not already exist in the gridmap file.

By default, grid-mapfile-add-entry will modify the gridmap file named by the GRIDMAP environment variable if present, or the file /etc/grid-security/grid-mapfile if not. This can be changed by the use of the if not. This can be changed by the use of the -mapfile or -f command-line options.

If the gridmap file does not exist, grid-mapfile-add-entry will create it. If it already exists, grid-mapfile-add-entry will save the current contents of the file to a new file with the string .old appended to the file name.

The full set of command-line options to grid-mapfile-add-entry are:

-help, -usage

Display the command-line options to grid-mapfile-add-entry.

-version, -versions

Display the version number of the grid-mapfile-add-entry command. The second form includes more details.

-dn DISTINGUISHED-NAME

The X.509 distinguished name to add a mapping for. The name should be in OpenSSL’s oneline format.

-ln LOCAL-NAME…​

The POSIX user name to map the distinguished name to. This name must be a valid username. Add multiple LOCAL-NAME strings after the -ln command-line option. If any of the local names are invalid, no changes will be made to the gridmap file. Note that if multiple occurances of the -ln command-line option are present, only the the last one will be added.

-d, -dryrun

Verify local names and display diagnostics about what would be added to the gridmap file, but don’t actually modify the file.

-mapfile MAPFILE, -f MAPFILE

Modify the gridmap file named by MAPFILE instead of the default.

Examples

Add a mapping between the current user’s certificate to the current user id to a gridmap file in $HOME/.gridmap: :

%  grid-mapfile-add-entry -f $HOME/.gridmap -dn "`grid-cert-info -subject`" -ln "`id -un`"
Modifying /home/juser/.gridmap ...
/home/juser/.gridmap does not exist... Attempting to create /home/juser/.gridmap
New entry:
"/DC=org/DC=example/DC=grid/CN=Joe User" juser
(1) entry added

Add a mapping between the a distinguished name and multiple local names:

%  grid-mapfile-add-entry -dn "/DC=org/DC=example/DC=grid/CN=Joe User" juser" local1 local2
Modifying /home/juser/.gridmap ...
/home/juser/.gridmap does not exist... Attempting to create /home/juser/.gridmap
New entry:
"/DC=org/DC=example/DC=grid/CN=Joe User" local1,local2
(1) entry added

Environment Variables

The following environment variables affect the execution of grid-mapfile-add-entry:

GRIDMAP

Path to the default gridmap to modify.

Files

The following files affect the execution of grid-mapfile-add-entry:

/etc/grid-security/grid-mapfile

Path to the default gridmap to modify if GRIDMAP environment variable is not set.

See Also

grid-mapfile-check-consistency(8), grid-mapfile-delete-entry(8)

GRID-MAPFILE-CHECK-CONSISTENCY(8)

NAME

grid-mapfile-check-consistency - Add an entry to a grid map file

SYNOPSIS

grid-mapfile-check-consistency [-h ] [-help ] [-usage ] [-version ]

Description

The grid-mapfile-check-consistency program performs basic checks for validity of a gridmap file. These checks include checks for existence, duplication of entries, and valid local user names. If the gridmap file is valid, grid-mapfile-check-consistency exits with a zero exit code, otherwise it exits with a non-zero exit code. In either case, it displays information about its progress as it parses and validates the gridmap file.

By default, grid-mapfile-check-consistency will check the gridmap file named by the GRIDMAP environment variable if present. If that variable is not set, it will check the file $HOME/.gridmap for non-root users if present. If that doesn’t exist or for non-root users if present. If that doesn’t exist or grid-mapfile-check-consistency is run as root, it will then check /etc/grid-security/grid-mapfile. This can be changed by the use of the . This can be changed by the use of the -mapfile or -f command-line options.

The full set of command-line options to grid-mapfile-check-consistency are:

-help, -h, -usage

Display the command-line options to grid-mapfile-check-consistency.

-version

Display the version number of the grid-mapfile-check-consistency command.

-mapfile MAPFILE, -f MAPFILE

Check the gridmap file named by MAPFILE instead of the default.

Examples

Check that the gridmap file in /etc/grid-security is valid: is valid:

%  grid-mapfile-check-consistency -f /etc/grid-security/grid-mapfile
Checking /etc/grid-security/grid-mapfile
Verifying grid mapfile existence...OK
Checking for duplicate entries...OK
Checking for valid user names...OK

Check a gridmap file that has an invalid local user name:

%  grid-mapfile-check-consistency -f /etc/grid-security/grid-mapfile
Checking /etc/grid-security/grid-mapfile
Verifying grid mapfile existence...OK
Checking for duplicate entries...OK
ERROR: baduser is not a valid local username
ERROR: Found 1 invalid username(s)

Environment Variables

The following environment variables affect the execution of grid-mapfile-check-consistency:

GRIDMAP

Path to the default gridmap to check.

Files

The following files affect the execution of grid-mapfile-check-consistency:

$HOME/.gridmap

Path to the default gridmap to check if the GRIDMAP environment variable is not set for non-root users.

/etc/grid-security/grid-mapfile

Path to the default gridmap to check if GRIDMAP environment variable is not set and the above file does not exist.

See Also

grid-mapfile-add-entry(8), grid-mapfile-delete-entry(8)

GRID-MAPFILE-DELETE-ENTRY(8)

NAME

grid-mapfile-delete-entry - Remove entries from a gridmap file

SYNOPSIS

grid-mapfile-delete-entry [-help ] [-usage ] [-version ] [-versions ]

Description

The grid-mapfile-delete-entry program deletes mappings from a gridmap file. If both the -dn and -ln> options are specified, grid-mapfile-delete-entry removes entries which meet both criteria (remove entries mapping DISTINGUISHED-NAME to LOCAL-NAME for each LOCAL-NAME specified). If only -dn or -ln is specified all entries for that DISTINGUISHED-NAME or LOCAL-NAME are removed.

By default, grid-mapfile-delete-entry will modify the gridmap file named by the GRIDMAP environment variable if present, or the file /etc/grid-security/grid-mapfile if not. This can be changed by the use of the if not. This can be changed by the use of the -mapfile or -f command-line options.

Prior to modifying a gridmap file, grid-mapfile-delete-entry saves its current contents to a file with the string .old appended to the original file name.

The full set of command-line options to grid-mapfile-delete-entry are:

-help, -usage

Display the command-line options to grid-mapfile-delete-entry.

-version, -versions

Display the version number of the grid-mapfile-delete-entry command. The second form includes more details.

-dn DISTINGUISHED-NAME

The X.509 distinguished name to remove from the gridmap file. If the -ln option is not specified, remove all entries for this name; otherwise, remove entries that match both this name and the local name. The name should be in OpenSSL’s oneline format.

-ln LOCAL-NAME…​

The POSIX user name to remove from the gridmap file. Include multiple LOCAL-NAME strings after the -ln command-line option to remove multiple names from the gridmap. If the -dn option is not specifeid, remove all entries for these names; otherwise, remove entries that match the DISTINGUISHED-NAME and any of the LOCAL-NAME values.

-d, -dryrun

Display diagnostics about what would be removed from the gridmap file, but don’t actually modify the file.

-mapfile MAPFILE, -f MAPFILE

Modify the gridmap file named by MAPFILE instead of the default.

Examples

Remove all mappings for a distinguished name:

%  grid-mapfile-delete-entry "/DC=org/DC=example/DC=grid/CN=Joe User"
Modifying /etc/grid-security/grid-mapfile ...
Deleting entry: "/DC=org/DC=example/DC=grid/CN=Joe User" juser,juser2
(1) entry deleted

Remove the mapping between a distinguished name and a single local username:

%  grid-mapfile-delete-entry "/DC=org/DC=example/DC=grid/CN=Joe User" -ln juser2
Modifying /etc/grid-security/grid-mapfile ...
Current entry: "/DC=org/DC=example/DC=grid/CN=Joe User" juser
(1) mapping removed: (juser2), (0) not present and ignored
(0) entries deleted

Environment Variables

The following environment variables affect the execution of grid-mapfile-delete-entry:

GRIDMAP

Path to the default gridmap to modify.

Files

The following files affect the execution of grid-mapfile-delete-entry:

/etc/grid-security/grid-mapfile

Path to the default gridmap to modify if GRIDMAP environment variable is not set.

See Also

grid-mapfile-add-entry(8), grid-mapfile-check-consistency(8)

GridFTP Commands

GLOBUS-URL-COPY(1)

NAME

globus-url-copy - globus-url-copy

SYNOPSIS

globus-url-copy [options] SOURCE-URL DESTINATION-URL

DESCRIPTION

The globus-url-copy program is a command line tool for multi-protocol data movement. It supports gsiftp:// (GridFTP), ftp://, http://, https://, sshftp:// and file:/// protocol specifiers in the URL.

OPTIONS

-help, -usage

Print help.

-versions

Print the versions of all modules that this program uses

-c, -continue-on-error

Do not die after any errors. By default, program will exit after most errors.

-a, -ascii

Convert the file to/from ASCII format to/from local file format

-b, -binary

Do not apply any conversion to the files. default

-f FILENAME

Read a list of URL pairs from filename. Each line should contain sourceURL destURL. Enclose URLs with spaces in double qoutes ("). Blank lines and lines beginning with # will be ignored.

-cd, -create-dest

Create destination directory if needed.

-r

Copy files in subdirectories

-fast

Recommended when using GridFTP servers. Use MODE E for all data transfers, including reusing data channels between list and transfer operations.

-t SECONDS

Run the transfer for this number of seconds and then end. Useful for performance testing or forced restart loops.

-q, -quiet

Suppress all output for successful operation.

-v, -verbose

Display URLs being transferred

-vb, -verbose-perf

During the transfer, display the number of bytes transferred and the transfer rate per second. Show URLs being transferred

-dbg, -debugftp

Debug ftp connections. Prints control channel communication to stderr

-rst, -restart

Restart failed ftp operations.

-rst-retries RETRIES

The maximum number of times to retry the operation before giving up on the transfer. Use 0 for infinite. Default is 5.

-rst-interval SECONDS

The interval in seconds to wait after a failure before retrying the transfer. Use 0 for an exponential backoff. Default is 0.

-rst-timeout SECONDS

Maximum time after a failure to keep retrying. Use 0 for no timeout. Default is 0.

-stall-timeout SECONDS, -st SECONDS

How long before cancelling/restarting a transfer with no data movement. Set to 0 to disable. Default is 600 seconds.

-df FILENAME, -dumpfile FILENAME

Path to a file where untransferred URLs will be saved for later restarting. Resulting file is the same format as the -f input file. If file exists, it will be read and all other URL input will be ignored.

-do FILENAME, -dump-only FILENAME

Perform no write operations on the destination. Instead, all files that would be transferred are enumerated and dumped to the specified file. Resulting file is the same format as the -f input file. Note: if you intend to use this file as input for a future transfer, the -create-dest option will be required if any destination directories do not already exist.

-rp, -relative-paths

The path portion of ftp URLs will be interpreted as relative to the user’s starting directory on the server. By default, all paths are root-relative. When this flag is set, the path portion of the ftp URL must start with %2F if it designates a root-relative path.

-s SUBJECT, -subject SUBJECT

Use this subject to match with both the source and dest servers.

-ss SUBJECT, -source-subject SUBJECT

Use this subject to match with the source server

-ds SUBJECT, -dest-subject SUBJECT

Use this subject to match with the destination server.

-tcp-bs SIZE, -tcp-buffer-size SIZE

Specify the size (in bytes) of the buffer to be used by the underlying ftp data channels.

-bs block SIZE, -block-size block SIZE

Specify the size (in bytes) of the buffer to be used by the underlying transfer methods.

-p PARALLELISM, -parallel PARALLELISM

Specify the number of parallel data connections should be used.

-notpt, -no-third-party-transfers

Turn third-party transfers off (on by default).

-nodcau, -no-data-channel-authentication

Turn off data channel authentication for ftp transfers.

-dcsafe, -data-channel-safe

Set data channel protection mode to SAFE

-dcpriv, -data-channel-private

Set data channel protection mode to PRIVATE

Warning
Despite having -dcpriv in its command line globus-url-copy will silently fall back to an unencryted data channel when connected to a server that does not support data channel encryption (e.g. dCache)!
-off, -partial-offset

Offset for partial ftp file transfers, defaults to 0.

-len, -partial-length

Length for partial ftp file transfers, used only for the source url, defaults the full file.

-list URL

List the files located at URL.

-stripe

Enable striped transfers on supported servers.

-striped-block-size, -sbs

Set layout mode and block size for striped transfers. If not set, server defaults will be used. If set to 0, Partitioned mode will be used. If set to > 0, Blocked mode will be used, with this as the block size.

-ipv6

Use ipv6 when available (EXPERIMENTAL)

-udt

Use UDT, a reliable udp based transport protocol, for data transfers

-g2, -gridftp2

Use GridFTP v2 protocol enhancements when possible.

-dp, -delayed-pasv

Enable delayed passive.

-mn NAME, -module-name NAME

Set the back-end storage module to use for both the source and destination in a GridFTP transfer.

-mp PARAMETERS, -module-parameters PARAMETERS

Set the back-end storage module arguments to use for both the source and destination in a GridFTP transfer.

-smn NAME, -src-module-name NAME

Set the back-end storage module to use for the source in a GridFTP transfer.

-smp PARAMETERS, -src-module-parameters PARAMETERS

Set the back-end storage module arguments to use for the source in a GridFTP transfer.

-dmn NAME, -dst-module-name NAME

Set the back-end storage module to use for the destination in a GridFTP transfer.

-dmp PARAMETERS, -dst-module-parameters PARAMETERS

Set the back-end storage module arguments to use for the destination in a GridFTP transfer.

-aa FILE, -authz-assert FILE

Use the assertions in FILE to authorize the access with both source and destination servers.

-saa FILE, -src-authz-assert FILE

Use the assertions in this file to authorize the access with source server.

-daa FILE, -dst-authz-assert FILE

Use the assertions in this file to authorize the access with dest server.

-cache-aa, -cache-authz-assert

Cache the authz assertion for subsequent transfers.

-cache-saa, -cache-src-authz-assert

Cache the src authz assertion for subsequent transfers.

-cache-daa, -cache-dst-authz-assert

Cache the dst authz assertion for subsequent transfers.

-pipeline, -pp

Enable pipelining support for multi-file ftp transfers. Currently third-party transfers benefit from this. EXPERIMENTAL

-concurrency, -cc

Number of concurrent ftp connections to use for multiple transfers.

-nl-bottleneck, -nlb

Use NetLogger to estimate speeds of disk and network read/write system calls, and attempt to determine the bottleneck component.

-sp COMMANDS, -src-pipe COMMANDS

Set the source end of a remote transfer to use piped in input with the given command line. Do not use with -fsstack.

-DP COMMANDS, -dst-pipe COMMANDS

Set the destination end of a remote transfer to write data to then standard input of the program run via the given command line. Do not use with -fsstack.

-pipe COMMANDS

Sets both -src-pipe and -dst-pipe to the same thing.

-dcstack STACK, -data-channel-stack STACK

Set the XIO driver stack for the network on both the source and the destination. Both must be GridFTP servers. The stack should contain all network drivers to use, in the order specified from bottom to top (e.g. -dcstack tcp,gsi). If the gsi driver is not included in the stack and data channel authentication is enabled, it will be inserted above the transport driver in the stack.

-fsstack STACK, -file-system-stack STACK

Set the XIO driver stack for the disk on both the source and the destination. Both must be GridFTP servers. The stack should contain all file system drivers to use, in the order specified from bottom to top.

-src-dcstack STACK, -source-data-channel-stack STACK

Set the XIO driver stack for the network on the source GridFTP server. See -dcstack above for description of the STACK string.

-src-fsstack STACK, -source-file-system-stack STACK

Set the XIO driver stack for the disk on the source GridFTP server. See -fsstack above for description of the STACK string.

-dst-dcstack STACK, -dest-data-channel-stack STACK

Set the XIO driver stack for the network on the destination GridFTP server. See -dcstack above for description of the STACK string.

-dst-fsstack STACK, -dest-file-system-stack STACK

Set the XIO driver stack for the disk on the destination GridFTP server. See -fsstack above for description of the STACK string.

-cred PATH

Set the credentials to use for both ftp connections.

-src-cred CRED-FILE, -sc CRED-FILE

Set the credentials to use for source ftp connections.

-dst-cred CRED-FILE, -dc CRED-FILE

Set the credentials to use for destination ftp connections.

-af FILENAME, -alias-file FILENAME

File with mapping of logical host aliases to lists of physical hosts. When used with multiple concurrent connections, each connection uses the next host in the list. Each line should either be an alias, noted with the @ symbol, or a hostname[:port]. Currently, only the aliases @source and @destination are valid, and they are used for every source or destination URL.

-sync

Only transfer files where the destination does not exist or differs from the source. -sync-level controls how to determine if files differ.

-sync-level number

Criteria for determining if files differ when performing a sync transfer. The default sync level is 2. The available levels are:

  • Level 0 will only transfer if the destination does not exist.

  • Level 1 will transfer if the size of the destination does not match the size of the source.

  • Level 2 will transfer if the time stamp of the destination is older than the time stamp of the source.

  • Level 3 will perform a checksum of the source and destination and transfer if the checksums do not match.

AUTHOR

Copyright © 1999-2014 University of Chicago

Interactive clients for GridFTP

The Grid Community Toolkit does not include an interactive client for GridFTP. Any normal FTP client will work with a GridFTP server, but it cannot take advantage of the advanced features of GridFTP. The interactive clients listed below take advantage of the advanced features of GridFTP.

There is no endorsement implied by their presence here. We make no assertion as to the quality or appropriateness of these tools, we simply provide this for your convenience. We will not answer questions, accept bugs, or in any way shape or form be responsible for these tools, although they should have mechanisms of their own for such things.

UberFTP was developed at the NCSA under the auspices of NMI and TeraGrid:

GLOBUS-GRIDFTP-SERVER(8)

NAME

globus-gridftp-server - The Globus GridFTP server daemon

SYNOPSIS

globus-gridftp-server OPTIONS

DESCRIPTION

The globus-gridftp-server program is a ftp server with support for GridFTP protocol extensions, including strong authentication, parallel data transfers, and parallel data layouts.

OPTIONS

The list below contains the command-line options for the server, and also the name of the configuration file entry that implements that option. Note that any boolean option can be negated on the command line by preceding the specified option with -no- or -n. example: -no-cas or -nf.

Informational Options

-h,-help

Show usage information and exit.

This option can also be set in the configuration file as help. The default value of this option is FALSE.

-hh,-longhelp

Show more usage information and exit.

This option can also be set in the configuration file as longhelp. The default value of this option is FALSE.

-v,-version

Show version information for the server and exit.

This option can also be set in the configuration file as version. The default value of this option is FALSE.

-V,-versions

Show version information for all loaded globus libraries and exit.

This option can also be set in the configuration file as versions. The default value of this option is FALSE.

Modes of Operation

-i,-inetd

Run under an inetd service.

This option can also be set in the configuration file as inetd. The default value of this option is FALSE.

-s,-daemon

Run as a daemon. All connections will fork off a new process and setuid if allowed.

This option can also be set in the configuration file as daemon. The default value of this option is TRUE.

-S,-detach

Run as a background daemon detached from any controlling terminals.

This option can also be set in the configuration file as detach. The default value of this option is FALSE.

-ssh

Run over a connected ssh session.

This option can also be set in the configuration file as ssh. The default value of this option is FALSE.

-exec string

For statically compiled or non-GLOBUS_LOCATION standard binary locations, specify the full path of the server binary here. Only needed when run in daemon mode.

This option can also be set in the configuration file as exec.

-chdir

Change directory when the server starts. This will change directory to the dir specified by the chdir_to option.

This option can also be set in the configuration file as chdir. The default value of this option is TRUE.

-chdir-to string

Directory to chdir to after starting. Will use / if not set. Note that this is the directory of the process, not the client’s home directory.

This option can also be set in the configuration file as chdir_to.

-threads number

Enable threaded operation and set the number of threads. The default is 0, which is non-threaded. When threading is required, a thread count of 1 or 2 should be sufficient.

This option can also be set in the configuration file as threads.

-f,-fork

Server will fork for each new connection. Disabling this option is only recommended when debugging. Note that non-forked servers running as root will only accept a single connection, and then exit.

This option can also be set in the configuration file as fork. The default value of this option is TRUE.

-1,-single

Exit after a single connection.

This option can also be set in the configuration file as single. The default value of this option is FALSE.

-chroot-path string

Path to become the new root after authentication. This path must contain a valid certificate structure, /etc/passwd, and /etc/group. The command globus-gridftp-server-setup-chroot can help create a suitable directory structure.

This option can also be set in the configuration file as chroot_path.

Authentication, Authorization, and Security Options

-auth-level number

Add levels together to use more than one.

  • 0 = Disables all authorization checks.

  • 1 = Authorize identity.

  • 2 = Authorize all file/resource accesses.

  • 4 = Disable changing process uid to authenticated user (no setuid) — DO NOT use this when process is started as root.

    If not set uses level 2 for front ends and level 1 for data nodes. Note that levels 2 and 4 imply level 1 as well.

    This option can also be set in the configuration file as auth_level.

-ipc-allow-from string

Only allow connections from these source ip addresses. Specify a comma separated list of ip address fragments. A match is any ip address that starts with the specified fragment. Example: 192.168.1. will match and allow a connection from 192.168.1.45. Note that if this option is used any address not specifically allowed will be denied.

This option can also be set in the configuration file as ipc_allow_from.

-ipc-deny-from string

Deny connections from these source ip addresses. Specify a comma separated list of ip address fragments. A match is any ip address that starts with the specified fragment. Example: 192.168.2. will match and deny a connection from 192.168.2.45.

This option can also be set in the configuration file as ipc_deny_from.

-allow-from string

Only allow connections from these source ip addresses. Specify a comma separated list of ip address fragments. A match is any ip address that starts with the specified fragment. Example: 192.168.1. will match and allow a connection from 192.168.1.45. Note that if this option is used any address not specifically allowed will be denied.

This option can also be set in the configuration file as allow_from.

-deny-from string

Deny connections from these source ip addresses. Specify a comma separated list of ip address fragments. A match is any ip address that starts with the specified fragment. Example: 192.168.2. will match and deny a connection from 192.168.2.45.

This option can also be set in the configuration file as deny_from.

-si,-secure-ipc

Use GSI security on ipc channel.

This option can also be set in the configuration file as secure_ipc. The default value of this option is TRUE.

-ia string,-ipc-auth-mode string

Set GSI authorization mode for the ipc connection. Options are: none, host, self or subject:[subject].

This option can also be set in the configuration file as ipc_auth_mode. The default value of this option is host.

-aa,-allow-anonymous

Allow clear text anonymous access. If server is running as root anonymous_user must also be set. Disables ipc security.

This option can also be set in the configuration file as allow_anonymous. The default value of this option is FALSE.

-anonymous-names-allowed string

Comma separated list of names to treat as anonymous users when allowing anonymous access. If not set, the default names of anonymous and ftp will be allowed. Use * to allow any username.

This option can also be set in the configuration file as anonymous_names_allowed.

-anonymous-user string

User to setuid to for an anonymous connection. Only applies when running as root.

This option can also be set in the configuration file as anonymous_user.

-anonymous-group string

Group to setgid to for an anonymous connection. If unset, the default group of anonymous_user will be used.

This option can also be set in the configuration file as anonymous_group.

-sharing-dn string

Allow sharing when using the supplied DN. A client connected with these credentials will be able to access any user for which sharing is enabled.

This option can also be set in the configuration file as sharing_dn.

-sharing-state-dir string

Full path to a directory that will contain files used by GridFTP to control sharing access for individual local accounts. The special variables $HOME and $USER can be used to create a dynamic path that is unique to each local account. This pathmust be writable by the associated account. The default path is $HOME/.globus/sharing/. This must refer to a path on the filesystem, not a path that is only accessible via a DSI plugin.

This option can also be set in the configuration file as sharing_state_dir.

-sharing-control

Allow a local user account to control its own sharing access via special GridFTP client commands. The user account must have filesystem write access to the sharing state dir.

This option can also be set in the configuration file as sharing_control. The default value of this option is TRUE.

-sharing-rp string

Sharing specific path restrictions. This completely replaces the normal path restrictions (-rp) when an account is being shared by a sharing-dn login.Follows normal path restriction semantics.

This option can also be set in the configuration file as sharing_rp.

-sharing-users-allow string

Comma separated list of usernames that are allowed to share unless matched in the user deny lists. If this list is set, users that are not included will be denied unless matched in the group allow list.

This option can also be set in the configuration file as sharing_users_allow.

-sharing-users-deny string

Comma separated list of usernames that are denied sharing even if matched in the user or group allow lists.

This option can also be set in the configuration file as sharing_users_deny.

-sharing-groups-allow string

Comma separated list of groups whose members are allowed to share unless matched in the user or group deny lists. If this list is set, groups that are not included will be denied unless matched in the user allow list.

This option can also be set in the configuration file as sharing_groups_allow.

-sharing-groups-deny string

Comma separated list of groups whose members will be denied sharing unless matched in the user allow list.

This option can also be set in the configuration file as sharing_groups_deny.

-allow-root

Allow clients to be mapped to the root account.

This option can also be set in the configuration file as allow_root. The default value of this option is FALSE.

-allow-disabled-login

Do not check if a user’s system account is disabled before allowing login.

This option can also be set in the configuration file as allow_disabled_login. The default value of this option is FALSE.

-password-file string

Enable clear text access and authenticate users against this /etc/passwd formatted file.

This option can also be set in the configuration file as pw_file.

-connections-max number

Maximum concurrent connections allowed. Only applies when running in daemon mode. Unlimited if not set.

This option can also be set in the configuration file as connections_max.

-connections-disabled

Disable all new connections. For daemon mode, issue a SIGHUP to the server process after changing the config file in order to not affect ongoing connections.

This option can also be set in the configuration file as connections_disabled. The default value of this option is FALSE.

-offline-msg string

Custom message to be displayed to clients when the server is offline via the connections_disabled or connections_max = 0 options.

This option can also be set in the configuration file as offline_msg.

-disable-command-list string

A comma separated list of client commands that will be disabled.

This option can also be set in the configuration file as disable_command_list.

-authz-callouts,-cas

Enable the GSI authorization callout framework, for callouts such as CAS.

This option can also be set in the configuration file as cas. The default value of this option is TRUE.

-use-home-dirs

Set the starting directory to the authenticated users home dir. Disabling this is the same as setting -home-dir /.

This option can also be set in the configuration file as use_home_dirs. The default value of this option is TRUE.

-home-dir string

Set a path to override the system defined home/starting directory for authenticated users. The special variable strings $USER and $HOME may be used. The authenticated username will be substituted for $USER, and the user’s real home dir will be substituted for $HOME. Be sure to escape the $ character if using these on the command line.

This option can also be set in the configuration file as home_dir.

-rp string,-restrict-paths string

A comma separated list of full paths that clients may access. Each path may be prefixed by R and/or W, denoting read or write access, otherwise full access is granted. If a given path is a directory, all contents and subdirectories will be given the same access. Order of paths does not matter — the permissions on the longest matching path will apply. The special character \~ will be replaced by the authenticated user’s home directory, or the -home-dir option, if used. Note that if the home directory is not accessible, \~ will be set to /. By default all paths are allowed, and access control is handled by the OS. In a striped or split process configuration, this should be set on both the frontend and data nodes.

This option can also be set in the configuration file as restrict_paths.

-rp-follow-symlinks

Do not verify that a symlink points to an allowed path before following. By default, symlinks are followed only when they point to an allowed path. By enabling this option, symlinks will be followed even if they point to a path that is otherwise restricted.

This option can also be set in the configuration file as rp_follow_symlinks. The default value of this option is FALSE.

-em string,-acl string

A comma separated list of ACL or event modules to load.

This option can also be set in the configuration file as acl.

Logging Options

-d string,-log-level string

Log level. A comma separated list of levels from: ERROR, WARN, INFO, TRANSFER, DUMP, ALL. TRANSFER includes the same statistics that are sent to the separate transfer log when -log-transfer is used. Example: error,warn,info. You may also specify a numeric level of 1-255. The default level is ERROR.

This option can also be set in the configuration file as log_level. The default value of this option is ERROR.

-log-module string

globus_logging module that will be loaded. If not set, the default stdio module will be used, and the logfile options apply. Built in modules are stdio and syslog. Log module options may be set by specifying module:opt1=val1:opt2=val2. Available options for the built in modules are interval and buffer, for buffer flush interval and buffer size, respectively. The default options are a 64k buffer size and a 5 second flush interval. A 0 second flush interval will disable periodic flushing, and the buffer will only flush when it is full. A value of 0 for buffer will disable buffering and all messages will be written immediately. Example: -log-module stdio:buffer=4096:interval=10

This option can also be set in the configuration file as log_module.

-l string,-logfile string

Path of a single file to log all activity to. If neither this option or log_unique is set, logs will be written to stderr unless the execution mode is detached or inetd, in which case logging will be disabled.

This option can also be set in the configuration file as log_single.

-L string,-logdir string

Partial path to which gridftp.(pid).log will be appended to construct the log filename. Example: -L /var/log/gridftp/ will create a separate log ( /var/log/gridftp/gridftp.xxxx.log ) for each process (which is normally each new client session). If neither this option or log_single is set, logs will be written to stderr unless the execution mode is detached or inetd, in which case logging will be disabled.

This option can also be set in the configuration file as log_unique.

-Z string,-log-transfer string

Log netlogger style info for each transfer into this file. You may also use the log-level of TRANSFER to include this info in the standard log.

This option can also be set in the configuration file as log_transfer.

-log-filemode string

File access permissions of log files. Should be an octal number such as 0644.

This option can also be set in the configuration file as log_filemode.

-disable-usage-stats

Disable transmission of per-transfer usage statistics. See the Usage Statistics section in the online documentation for more information.

This option can also be set in the configuration file as disable_usage_stats. The default value of this option is FALSE.

-usage-stats-target string

Comma separated list of contact strings (host:port) for usage statistics receivers. The usage stats sent to a particular receiver may be customized by configuring it with a taglist (host:port!taglist) The taglist is a list of characters that each correspond to a usage stats tag. When this option is unset, stats are reported to usage-stats.globus.org:4810. If you set your own receiver, and wish to continue reporting to the Globus receiver, you will need to add it manually. The list of available tags follow. Tags marked * are reported by default.

*(e) START - start time of transfer
*(E) END - end time of transfer
*(v) VER - version string of GridFTP server
*(b) BUFFER - tcp buffer size used for transfer
*(B) BLOCK - disk blocksize used for transfer
*(N) NBYTES - number of bytes transferred
*(s) STREAMS - number of parallel streams used
*(S) STRIPES - number of stripes used
*(t) TYPE - transfer command: RETR, STOR, LIST, etc
*(c) CODE - ftp result code (226 = success, 5xx = fail)
*(D) DSI - DSI module in use
*(A) EM - event modules in use
*(T) SCHEME - ftp, gsiftp, sshftp, etc. (client supplied)
*(a) APP - guc, rft, generic library app, etc. (client supplied)
*(V) APPVER - version string of above. (client supplied)
(f) FILE - name of file/data transferred
(i) CLIENTIP - ip address of host running client (control channel)
(I) DATAIP - ip address of source/dest host of data (data channel)
(u) USER - local user name the transfer was performed as
(d) USERDN - DN that was mapped to user id
(C) CONFID - ID defined by -usage-stats-id config option
(U) SESSID - unique id that can be used to match transfers in a session and
    transfers across source/dest of a third party transfer. (client supplied)

This option can also be set in the configuration file as usage_stats_target.

-usage-stats-id string

Identifying tag to include in usage statistics data. If this is set and usage-stats-target is unset, CONFID will be added to the default usage stats data.

This option can also be set in the configuration file as usage_stats_id.

Single and Striped Remote Data Node Options

-r string,-remote-nodes string

Comma separated list of remote node contact strings.

This option can also be set in the configuration file as remote_nodes.

-hybrid

When a server is configured for striped operation with the remote_nodes option, both a frontend and backend process are started even if the client does not request multiple stripes. This option will start backend processes only when striped operation is requested by the client, while servicing non-striped requests with a single frontend process.

This option can also be set in the configuration file as hybrid. The default value of this option is FALSE.

-dn,-data-node

This server is a backend data node.

This option can also be set in the configuration file as data_node. The default value of this option is FALSE.

-sbs number,-stripe-blocksize number

Size in bytes of sequential data that each stripe will transfer.

This option can also be set in the configuration file as stripe_blocksize. The default value of this option is 1048576.

-stripe-count number

Number of number stripes to use per transfer when this server controls that number. If remote nodes are statically configured (via -r or remote_nodes), this will be set to that number of nodes, otherwise the default is 1.

This option can also be set in the configuration file as stripe_count.

-sl number,-stripe-layout number

Stripe layout. 1 = Partitioned 2 = Blocked.

This option can also be set in the configuration file as stripe_layout. The default value of this option is 2.

-stripe-blocksize-locked

Do not allow client to override stripe blocksize with the OPTS RETR command

This option can also be set in the configuration file as stripe_blocksize_locked. The default value of this option is FALSE.

-stripe-layout-locked

Do not allow client to override stripe layout with the OPTS RETR command

This option can also be set in the configuration file as stripe_layout_locked. The default value of this option is FALSE.

Disk Options

-bs number,-blocksize number

Size in bytes of data blocks to read from disk before posting to the network.

This option can also be set in the configuration file as blocksize. The default value of this option is 262144.

-sync-writes

Flush disk writes before sending a restart marker. This attempts to ensure that the range specified in the restart marker has actually been committed to disk. This option will probably impact performance, and may result in different behavior on different storage systems. See the manpage for sync() for more information.

This option can also be set in the configuration file as sync_writes. The default value of this option is FALSE.

-perms string

Set the default permissions for created files. Should be an octal number such as 0644. The default is 0644. Note: If umask is set it will affect this setting — i.e. if the umask is 0002 and this setting is 0666, the resulting files will be created with permissions of 0664.

This option can also be set in the configuration file as perms.

-file-timeout number

Timeout in seconds for all disk accesses. A value of 0 disables the timeout.

This option can also be set in the configuration file as file_timeout.

Network Options

-p number,-port number

Port on which a frontend will listen for client control channel connections, or on which a data node will listen for connections from a frontend. If not set a random port will be chosen and printed via the logging mechanism.

This option can also be set in the configuration file as port.

-control-interface string

Hostname or IP address of the interface to listen for control connections on. If not set will listen on all interfaces.

This option can also be set in the configuration file as control_interface.

-data-interface string

Hostname or IP address of the interface to use for data connections. If not set will use the current control interface.

This option can also be set in the configuration file as data_interface.

-ipc-interface string

Hostname or IP address of the interface to use for ipc connections. If not set will listen on all interfaces.

This option can also be set in the configuration file as ipc_interface.

-hostname string

Effectively sets the above control_interface, data_interface and ipc_interface options.

This option can also be set in the configuration file as hostname.

-ipc-port number

Port on which the frontend will listen for data node connections.

This option can also be set in the configuration file as ipc_port.

-control-preauth-timeout number

Time in seconds to allow a client to remain connected to the control channel without activity before authenticating.

This option can also be set in the configuration file as control_preauth_timeout. The default value of this option is 120.

-control-idle-timeout number

Time in seconds to allow a client to remain connected to the control channel without activity.

This option can also be set in the configuration file as control_idle_timeout. The default value of this option is 600.

-ipc-idle-timeout number

Idle time in seconds before an unused ipc connection will close.

This option can also be set in the configuration file as ipc_idle_timeout. The default value of this option is 900.

-ipc-connect-timeout number

Time in seconds before canceling an attempted ipc connection.

This option can also be set in the configuration file as ipc_connect_timeout. The default value of this option is 60.

-allow-udt

Enable protocol support for UDT with NAT traversal if the udt driver is available. Requires threads.

This option can also be set in the configuration file as allow_udt. The default value of this option is FALSE.

-port-range string

Port range to use for incoming connections. The format is "startport,endport". This, along with -data-interface, can be used to enable operation behind a firewall and/or when NAT is involved. This is the same as setting the environment variable GLOBUS_TCP_PORT_RANGE.

This option can also be set in the configuration file as port_range.

User Messages

-banner string

Message to display to the client before authentication.

This option can also be set in the configuration file as banner.

-banner-file string

File to read banner message from.

This option can also be set in the configuration file as banner_file.

-banner-terse

When this is set, the minimum allowed banner message will be displayed to unauthenticated clients.

This option can also be set in the configuration file as banner_terse. The default value of this option is FALSE.

-banner-append

When this is set, the message set in the banner or banner_file option will be appended to the default banner message rather than replacing it.

This option can also be set in the configuration file as banner_append. The default value of this option is FALSE.

-version-tag string

Add an identifying string to the existing toolkit version. This is displayed in the default banner message, the SITE VERSION command, and usage stats.

This option can also be set in the configuration file as version_tag.

-login-msg string

Message to display to the client after authentication.

This option can also be set in the configuration file as login_msg.

-login-msg-file string

File to read login message from.

This option can also be set in the configuration file as login_msg_file.

Module Options

-dsi string

Data Storage Interface module to load. File and remote modules are defined by the server. If not set, the file module is loaded, unless the remote option is specified, in which case the remote module is loaded. An additional configuration string can be passed to the DSI using the format [module name]:[configuration string] to this option. The format of the configuration string is defined by the DSI being loaded.

This option can also be set in the configuration file as load_dsi_module.

-allowed-modules string

Comma separated list of ERET/ESTO modules to allow, and optionally specify an alias for. Example: module1,alias2:module2,module3 (module2 will be loaded when a client asks for alias2).

This option can also be set in the configuration file as allowed_modules.

-dc-whitelist string

A comma separated list of drivers allowed on the network stack.

This option can also be set in the configuration file as dc_whitelist.

-fs-whitelist string

A comma separated list of drivers allowed on the disk stack.

This option can also be set in the configuration file as fs_whitelist.

-popen-whitelist string

A comma separated list of programs that the popen driver is allowed to execute, when used on the network or disk stack. An alias may also be specified, so that a client does not need to specify the full path. Format is [alias:]prog,[alias:]prog. example: /bin/gzip,tar:/bin/tar

This option can also be set in the configuration file as popen_whitelist.

-xnetmgr string

An option string to pass to the XIO Network Manager Driver, which will then be loaded for all data channel connections. This must be in the form "manager=module;option1=value;option2=value;". See the Network Manager documentation for more info.

This option can also be set in the configuration file as xnetmgr.

-dc-default string

A comma separated list of XIO drivers and options representing the default network stack. Format is of each driver entry is driver1[:opt1=val1;opt2=val2;…​]. The bottom of the stack, the transport driver, is always first.

This option can also be set in the configuration file as dc_default.

-fs-default string

A comma separated list of XIO drivers and options representing the default disk stack. Format is of each driver entry is driver1[:opt1=val1;opt2=val2;…​]. The bottom of the stack, the transport driver, is always first.

This option can also be set in the configuration file as fs_default.

Other

-c string

Path to main configuration file that should be loaded. Otherwise will attempt to load $GLOBUS_LOCATION/etc/gridftp.conf and /etc/grid-security/gridftp.conf.

-C string

Path to directory holding configuration files that should be loaded. Files will be loaded in alphabetical order, and in the event of duplicate parameters the last loaded file will take precedence. Files with a . in the name (file.bak, file.rpmsave, etc.) will be ignored. Note that the main configuration file, if one exists, will always be loaded last.

This option can also be set in the configuration file as config_dir.

-config-base-path string

Base path to use when config and log path options are not full paths. By default this is the current directory when the process is started.

This option can also be set in the configuration file as config_base_path.

-debug

Sets options that make server easier to debug. Forces no-fork, no-chdir, and allows core dumps on bad signals instead of exiting cleanly. Not recommended for production servers. Note that non-forked servers running as root will only accept a single connection, and then exit.

This option can also be set in the configuration file as debug. The default value of this option is FALSE.

-pidfile string

Write PID of the GridFTP server to this path. May contain variable references to ${localstatedir}

This option can also be set in the configuration file as pidfile.

EXIT STATUS

0

Successful program execution.

GLOBUS-GRIDFTP-SERVER-SETUP-CHROOT(8)

NAME

globus-gridftp-server-setup-chroot - Set up a chroot for the Globus GridFTP server

SYNOPSIS

globus-gridftp-server-setup-chroot [-h] [-c CERT-DIR] -r NEW-CHROOT

DESCRIPTION

The globus-gridftp-server-setup-chroot program creates a chroot directory tree that can be used for the globus-gridftp-server(8). This chroot contains a copy of essential POSIX devices in dev; hosts, group, passwd, and grid-security configuration files in etc; and a temporary file directory in tmp.

The -c CERT-DIR option copies certificate files from a different directory than the default [/etc/grid-security/certificates].

OPTIONS

-h

Print short usage and exit

-r NEW-CHROOT

Specify the new chroot directory to create.

-c CERT-DIR

Specify the trusted certificate dir source.

EXIT STATUS

0

Successful program execution.

1

Error

AUTHOR

Copyright © 1999-2015 University of Chicago

SEE ALSO

globus-gridftp-server(8)

GRAM5 Commands

GLOBUS-FORK-STARTER(8)

NAME

globus-fork-starter - Start and monitor a fork job

SYNOPSIS

globus-fork-starter

Description

The globus-fork-starter program is executes jobs specified on its standard input stream, recording the job state changes to a file defined in the $GLOBUS_LOCATION/etc/globus-fork.conf configuration file. It runs until its standard input stream is closed and all jobs it is managing have terminated. The log generated by this program can be used by the SEG to provide job state changes and exit codes to the GRAM service. The configuration file. It runs until its standard input stream is closed and all jobs it is managing have terminated. The log generated by this program can be used by the SEG to provide job state changes and exit codes to the GRAM service. The globus-fork-starter program is typically started by the fork GRAM module.

The globus-fork-starter program expects its input to be a series of task definitions, separated by the newline character, each representing a separate job. Each task definition contains a number of fields, separated by the colon character. The first field is always the literal string 100 indicating the message format, the second field is a unique job tag that will be distinguish the reply from this program when multiple jobs are submitted. The rest of fields contain attribute bindings. The supported attributes are:

directory

Working directory of the job

environment

Comma-separated list of strings defining environment variables. The form of these strings is var=value

count

Number of processes to start

executable

Full path to the executable to run

arguments

Comma-separated list of command-line arguments for the job

stdin

Full path to a file containing the input of the job

stdout

Full path to a file to write the output of the job to

stderr

Full path to a file to write the error stream of the job

Within each field, the following characters may be escaped by preceding them with the backslash character:

  • backslash (\)

  • semicolor (;)

  • comma (,)

  • equal (=)

Additionally, newline can be represented within a field by using the escape sequence \n.

For each job the globus-fork-starter processes, it replies by writing a single line to standard output. The replies again consist of a number of fields separated by the semicolon character.

For a successful job start, the first field of the reply is the literal 101, the second field is the tag from the input, and the third field is a comma-separated list of SEG job identifiers which consist the concatenation of a UUID and a process id. The globus-fork-starter program will write state changes to the SEG log using these job identifiers.

For a failure, the first field of the reply is the literal 102, the second field is the tag from the input, the third field is the integer representation of a GRAM erorr code, and the fourth field is an string explaining the error.

ENVIRONMENT

If the following variables affect the execution of globus-fork-starter

GLOBUS_LOCATION

Path to Grid Community Toolkit installation. This is used to locate the globus-fork.conf configuration file. configuration file.

Files

$GLOBUS_LOCATION/etc/globus-fork.conf

Path to fork SEG configuration file.

GLOBUS-GATEKEEPER-ADMIN(8)

NAME

globus-gatekeeper-admin - Manage globus-gatekeeper services

SYNOPSIS

globus-gatekeeper-admin [-h ]

Description

The globus-gatekeeper-admin program manages service entries which are used by the globus-gatekeeper to execute services. Service entries are located in the /etc/grid-services directory. The directory. The globus-gatekeeper-admin can list, enable, or disable specific services, or set a service as the default. The -h command-line option shows a brief usage message.

Listing services

The -l command-line option to globus-gatekeeper-admin will cause it to list all of the services which are available to be run by the globus-gatekeeper. In the output, the service name will be followed by its status in brackets. Possible status strings are ENABLED, DISABLED, and ALIAS to , where NAME is another service name.

If the -n ' is used, then only information about the service named 'NAME is printed.

Enabling services

The '-e ' command-line option to globus-gatekeeper-admin will cause it to enable a service so that it may be run by the globus-gatekeeper.

If the -n ' option is used as well, then the service will be enabled with the alias 'NAME.

Enabling a default service

The -E command-line option to globus-gatekeeper-admin will cause it to enable a service alias with the name jobmanager. The globus-gatekeeper-admin program will choose the first service it finds as the default. To enable a particular service as the default, use the -e parameter described above with the -n parameter.

Disabling services

The '-d ' command-line option to globus-gatekeeper-admin will cause it to disable a service so that it may not be run by the globus-gatekeeper. All aliases to a disabled service are also disabled.

Files

/etc/grid-services

Default location of enabled gatekeeper service descriptions.

GLOBUS-GATEKEEPER(8)

NAME

globus-gatekeeper - Authorize and execute a grid service on behalf of a user

SYNOPSIS

globus-gatekeeper [-help ]

[-conf PARAMETER_FILE]

[-test ] -d | -debug

-inetd | -f

-p PORT | -port PORT

[-home PATH] -l LOGFILE | -logfile LOGFILE [-lf LOG_FACILITY]

[-acctfile ACCTFILE]

[-e LIBEXECDIR]

[-launch_method fork_and_exit | fork_and_wait | dont_fork ]

[-grid_services SERVICEDIR]

[-globusid GLOBUSID]

[-gridmap GRIDMAP]

[-x509_cert_dir TRUSTED_CERT_DIR]

[-x509_cert_file TRUSTED_CERT_FILE]

[-x509_user_cert CERT_PATH]

[-x509_user_key KEY_PATH]

[-x509_user_proxy PROXY_PATH]

[-k ]

[-globuskmap KMAP]

[-pidfile PIDFILE]

Description

The globus-gatekeeper program is a meta-server similar to inetd or xinetd that starts other services after authenticating a TCP connection using GSSAPI and mapping the client’s credential to a local account.

The most common use for the globus-gatekeeper program is to start instances of the globus-job-manager(8) service. A single globus-gatekeeper deployment can handle multiple different service configurations by having entries in the /etc/grid-services directory. directory.

Typically, users interact with the globus-gatekeeper program via client applications such as globusrun(1), globus-job-submit, or tools such as CoG jglobus or Condor-G.

The full set of command-line options to globus-gatekeeper consists of:

-help

Display a help message to standard error and exit

-conf PARAMETER_FILE

Load configuration parameters from PARAMETER_FILE. The parameters in that file are treated as additional command-line options.

-test

Parse the configuration file and print out the POSIX user id of the globus-gatekeeper process, service home directory, service execution directory, and X.509 subject name and then exits.

-d, -debug

Run the globus-gatekeeper process in the foreground.

-inetd

Flag to indicate that the globus-gatekeeper process was started via inetd or a similar super-server. If this flag is set and the globus-gatekeeper was not started via inetd, a warning will be printed in the gatekeeper log.

-f

Flag to indicate that the globus-gatekeeper process should run in the foreground. This flag has no effect when the globus-gatekeeper is started via inetd.

-p PORT, -port PORT

Listen for connections on the TCP/IP port PORT. This option has no effect if the globus-gatekeeper is started via inetd or a similar service. If not specified and the gatekeeper is running as root, the default of 2119 is used. Otherwise, the gatekeeper defaults to an ephemeral port.

-home PATH

Sets the gatekeeper deployment directory to PATH. This is used to interpret relative paths for accounting files, libexecdir, certificate paths, and also to set the GLOBUS_LOCATION environment variable in the service environment. If not specified, the gatekeeper looks for service executables in /usr/sbin, configuration in , configuration in /etc, and writes logs and accounting files to , and writes logs and accounting files to /var/log..

-l LOGFILE, -logfile LOGFILE

Write log entries to LOGFILE. If LOGFILE is equal to logoff or LOGOFF, then logging will be disabled, both to file and to syslog.

-lf LOG_FACILITY

Open syslog using the LOG_FACILITY. If not specified, LOG_DAEMON will be used as the default when using syslog.

-acctfile ACCTFILE

Set the path to write accounting records to ACCTFILE. If not set, records will be written to the log file.

-e LIBEXECDIR

Look for service executables in LIBEXECDIR. If not specified, the sbin subdirectory of the parameter to subdirectory of the parameter to -home is used, or /usr/sbin if that is not set. if that is not set.

-launch_method fork_and_exit|fork_and_wait|dont_fork

Determine how to launch services. The method may be either fork_and_exit (the service runs completely independently of the gatekeeper, which exits after creating the new service process), fork_and_wait (the service is run in a separate process from the gatekeeper but the gatekeeper does not exit until the service terminates), or dont_fork, where the gatekeeper process becomes the service process via the exec() system call.

-grid_services SERVICEDIR

Look for service descriptions in SERVICEDIR.

-globusid GLOBUSID

Sets the GLOBUSID environment variable to GLOBUSID. This variable is used to construct the gatekeeper contact string if it can not be parsed from the service credential.

-gridmap GRIDMAP

Use the file at GRIDMAP to map GSSAPI names to POSIX user names.

-x509_cert_dir TRUSTED_CERT_DIR

Use the directory TRUSTED_CERT_DIR to locate trusted CA X.509 certificates. The gatekeeper sets the environment variable X509_CERT_DIR to this value.

-x509_user_cert CERT_PATH

Read the service X.509 certificate from CERT_PATH. The gatekeeper sets the X509_USER_CERT environment variable to this value.

-x509_user_key KEY_PATH

Read the private key for the service from KEY_PATH. The gatekeeper sets the X509_USER_KEY environment variable to this value.

-x509_user_proxy PROXY_PATH

Read the X.509 proxy certificate from PROXY_PATH. The gatekeeper sets the X509_USER_PROXY environment variable to this value.

-k

Use the globus-k5 command to acquire Kerberos 5 credentials before starting the service.

-globuskmap KMAP

Use KMAP as the path to the Grid credential to kerberos initialization mapping file.

-pidfile PIDFILE

Write the process id of the globus-gatekeeper to the file named by PIDFILE.

ENVIRONMENT

If the following variables affect the execution of globus-gatekeeper:

X509_CERT_DIR

Directory containing X.509 trust anchors and signing policy files.

X509_USER_PROXY

Path to file containing an X.509 proxy.

X509_USER_CERT

Path to file containing an X.509 user certificate.

X509_USER_KEY

Path to file containing an X.509 user key.

GLOBUS_LOCATION

Default path to gatekeeper service files.

Files

/etc/grid-services/SERVICENAME

Service configuration for SERVICENAME.

/etc/grid-security/grid-mapfile

Default file mapping Grid identities to POSIX identities.

/etc/globuskmap

Default file mapping Grid identities to Kerberos 5 principals.

/etc/globus-nologin

File to disable the globus-gatekeeper program.

/var/log/globus-gatekeeper.log

Default gatekeeper log.

See also

globus-k5(8), globusrun(1), globus-job-manager(8)

GLOBUS-GRAM-AUDIT(8)

NAME

globus-gram-audit - Load GRAM4 and GRAM5 audit records into a database

SYNOPSIS

globus-gram-audit [--conf CONFIG_FILE] [--create ] | [--update= OLD-VERSION] [--check ] [--delete ] [--audit-directory AUDITDIR] [--quiet ]

Description

The globus-gram-audit program loads audit records to an SQL-based database. It reads $GLOBUS_LOCATION/etc/globus-job-manager.conf by default to determine the audit directory and then uploads all files in that directory that contain valid audit records to the database configured by the by default to determine the audit directory and then uploads all files in that directory that contain valid audit records to the database configured by the globus_gram_job_manager_auditing_setup_scripts package. If the upload completes successfully, the audit files will be removed.

The full set of command-line options to globus-gram-audit consist of:

--conf CONFIG_FILE

Use CONFIG_FILE instead of the default from the configuration file for audit database configuration.

--check

Check whether the insertion of a record was successful by querying the database after inserting the records. This is used in tests.

--delete

Delete audit records from the database right after inserting them. This is used in tests to avoid filling the databse with test records.

--audit-directory DIR

Look for audit records in DIR, instead of looking in the directory specified in the job manager configuration. This is used in tests to control which records are loaded to the database and then deleted.

--query SQL

Perform the given SQL query on the audit database. This uses the database information from the configuration file to determine how to contact the database.

--quiet

Reduce the amount of output for common operations.

FILES

The globus-gram-audit uses the following files (paths relative to $GLOBUS_LOCATION).

etc/globus-gram-job-manager.conf

GRAM5 job manager configuration. It includes the default path to the audit directory

etc/globus-gram-audit.conf

Audit configuration. It includes the information needed to contact the audit database.

GLOBUS-JOB-CANCEL(1)

NAME

globus-job-cancel - Cancel a GRAM batch job

SYNOPSIS

globus-job-cancel -f | -force -q | -quiet JOBID

Description

The globus-job-cancel program cancels the job named by JOBID. Any cached files associated with the job will remain until globus-job-clean is executed for the job.

By default, globus-job-cancel prompts the user prior to canceling the job. This behavior can be overridden by specifying the -f or -force command-line options.

Options

The full set of options to globus-job-cancel are:

-help, -usage

Display a help message to standard error and exit.

-version

Display the software version of the globus-job-cancel program to standard output.

-version

Display the software version of the globus-job-cancel program including DiRT information to standard output.

-force, -f

Do not prompt to confirm job cancel and clean-up.

-quiet, -q

Do not print diagnostics for succesful cancel. Implies -f

ENVIRONMENT

If the following variables affect the execution of globus-job-cancel.

X509_USER_PROXY

Path to proxy credential.

X509_CERT_DIR

Path to trusted certificate directory.

GLOBUS-JOB-CLEAN(1)

NAME

globus-job-clean - Cancel and clean up a GRAM batch job

SYNOPSIS

globus-job-clean -r RESOURCE | -resource RESOURCE

-f | -force -q | -quiet JOBID

Description

The globus-job-clean program cancels the job named by JOBID if it is still running, and then removes any cached files on the GRAM service node related to that job. In order to do the file clean up, it submits a job which removes the cache files. By default this cleanup job is submitted to the default GRAM resource running on the same host as the job. This behavior can be controlled by specifying a resource manager contact string as the parameter to the -r or -resource option.

By default, globus-job-clean prompts the user prior to canceling the job. This behavior can be overridden by specifying the -f or -force command-line options.

Options

The full set of options to globus-job-clean are:

-help, -usage

Display a help message to standard error and exit.

-version

Display the software version of the globus-job-clean program to standard output.

-version

Display the software version of the globus-job-clean program including DiRT information to standard output.

-resource RESOURCE, -r RESOURCE

Submit the clean-up job to the resource named by RESOURCE instead of the default GRAM service on the same host as the job contact.

-force, -f

Do not prompt to confirm job cancel and clean-up.

-quiet, -q

Do not print diagnostics for succesful clean-up. Implies -f

ENVIRONMENT

If the following variables affect the execution of globus-job-clean.

X509_USER_PROXY

Path to proxy credential.

X509_CERT_DIR

Path to trusted certificate directory.

GLOBUS-JOB-GET-OUTPUT(1)

NAME

globus-job-get-output - Retrieve the output and error streams from a GRAM job

SYNOPSIS

globus-job-get-output -r RESOURCE | -resource RESOURCE

-out | -err -t LINES | -tail LINES -follow LINES | -f LINES JOBID

Description

The globus-job-get-output program retrieves the output and error streams of the job named by JOBID. By default, globus-job-get-output will retrieve all output and error data from the job and display them to its own output and error streams. Other behavior can be controlled by using command-line options. The data retrieval is implemented by submitting another job which simply displays the contents of the first job’s output and error streams. By default this retrieval job is submitted to the default GRAM resource running on the same host as the job. This behavior can be controlled by specifying a particular resource manager contact string as the RESOURCE parameter to the -r or -resource option.

Options

The full set of options to globus-job-get-output are:

-help, -usage

Display a help message to standard error and exit.

-version

Display the software version of the globus-job-get-output program to standard output.

-version

Display the software version of the globus-job-get-output program including DiRT information to standard output.

-resource RESOURCE, -r RESOURCE

Submit the retrieval job to the resource named by RESOURCE instead of the default GRAM service on the same host as the job contact.

-out

Retrieve only the standard output stream of the job. The default is to retrieve both standard output and standard error.

-err

Retrieve only the standard error stream of the job. The default is to retrieve both standard output and standard error.

-tail LINES, -t LINES

Print only the last LINES count lines of output from the data streams being retrieved. By default, the entire output and error file data is retrieved. This option can not be used along with the -f or -follow options.

-follow LINES, -f LINES

Print the last LINES count lines of output from the data streams being retrieved and then wait until canceled, printing any subsequent job output that occurs. By default, the entire output and error file data is retrieved. This option can not be used along with the -t or -tail options.

ENVIRONMENT

If the following variables affect the execution of globus-job-get-output.

X509_USER_PROXY

Path to proxy credential.

X509_CERT_DIR

Path to trusted certificate directory.

GLOBUS-JOB-MANAGER(8)

NAME

globus-job-manager - Execute and monitor jobs

SYNOPSIS

globus-job-manager -type LRM [-conf CONFIG_PATH] [-help ] [-globus-host-manufacturer MANUFACTURER] [-globus-host-cputype CPUTYPE] [-globus-host-osname OSNAME] [-globus-host-osversion OSVERSION] [-globus-gatekeeper-host HOST] [-globus-gatekeeper-port PORT] [-globus-gatekeeper-subject SUBJECT] [-home GLOBUS_LOCATION] [-target-globus-location TARGET_GLOBUS_LOCATION] [-condor-arch ARCH] [-condor-os OS] [-history HISTORY_DIRECTORY] [-scratch-dir-base SCRATCH_DIRECTORY] [-enable-syslog ] [-stdio-log LOG_DIRECTORY] [-log-pattern PATTERN] [-log-levels LEVELS] [-state-file-dir STATE_DIRECTORY] [-globus-tcp-port-range PORT_RANGE] [-globus-tcp-source-range SOURCE_RANGE] [-x509-cert-dir TRUSTED_CERTIFICATE_DIRECTORY] [-cache-location GASS_CACHE_DIRECTORY] [-k ] [-extra-envvars VAR=VAL,…​] [-seg-module SEG_MODULE] [-audit-directory AUDIT_DIRECTORY] [-globus-toolkit-version TOOLKIT_VERSION] [-disable-streaming ] [-disable-usagestats ] [-usagestats-targets TARGET] [-service-tag SERVICE_TAG]

Description

The globus-job-manager program is a servivce which starts and controls GRAM jobs which are executed by a local resource management system, such as LSF or Condor. The globus-job-manager program is typically started by the globus-gatekeeper program and not directly by a user. It runs until all jobs it is managing have terminated or its delegated credentials have expired.

Typically, users interact with the globus-job-manager program via client applications such as globusrun, globus-job-submit, or tools such as CoG jglobus or Condor-G.

The full set of command-line options to globus-job-manager consists of:

-help

Display a help message to standard error and exit

-type LRM

Execute jobs using the local resource manager named LRM.

-conf CONFIG_PATH

Read additional command-line arguments from the file CONFIG_PATH. If present, this must be the first command-line argument to the globus-job-manager program.

-globus-host-manufacturer MANUFACTURER:: Indicate the manufacturer of the system which the jobs will execute on. This parameter sets the value of the $(GLOBUS_HOST_MANUFACTURER) RSL substitution to MANUFACTURER

-globus-host-cputype CPUTYPE

Indicate the CPU type of the system which the jobs will execute on. This parameter sets the value of the $(GLOBUS_HOST_CPUTYPE) RSL substitution to CPUTYPE

-globus-host-osname OSNAME

Indicate the operating system type of the system which the jobs will execute on. This parameter sets the value of the $(GLOBUS_HOST_OSNAME) RSL substitution to OSNAME

-globus-host-osversion OSVERSION

Indicate the operating system version of the system which the jobs will execute on. This parameter sets the value of the $(GLOBUS_HOST_OSVERSION) RSL substitution to OSVERSION

-globus-gatekeeper-host HOST

Indicate the host name of the machine which the job was submitted to. This parameter sets the value of the $(GLOBUS_GATEKEEPER_HOST) RSL substitution to HOST

-globus-gatekeeper-port PORT

Indicate the TCP port number of gatekeeper to which jobs are submitted to. This parameter sets the value of the $(GLOBUS_GATEKEEPER_PORT) RSL substitution to PORT

-globus-gatekeeper-subject SUBJECT

Indicate the X.509 identity of the gatekeeper to which jobs are submitted to. This parameter sets the value of the $(GLOBUS_GATEKEEPER_SUBJECT) RSL substitution to SUBJECT

-home GLOBUS_LOCATION

Indicate the path where the Grid Community Toolkit is installed on the service node. This is used by the job manager to locate its support and configuration files.

-target-globus-location TARGET_GLOBUS_LOCATION

Indicate the path where the Grid Community Toolkit is installed on the execution host. If this is omitted, the value specified as a parameter to -home is used. This parameter sets the value of the $(GLOBUS_LOCATION) RSL substitution to TARGET_GLOBUS_LOCATION

-history HISTORY_DIRECTORY

Configure the job manager to write job history files to HISTORY_DIRECTORY. These files are described in the FILES section below.

-scratch-dir-base SCRATCH_DIRECTORY

Configure the job manager to use SCRATCH_DIRECTORY as the default scratch directory root if a relative path is specified in the job RSL’s scratch_dir attribute.

-enable-syslog

Configure the job manager to write log messages via syslog. Logging is further controlled by the argument to the -log-levels parameter described below.

-log-pattern PATTERN

Configure the job manager to write log messages to files named by the string PATTERN. The PATTERN string may contain job-independent RSL substitutions such as $(HOME), $(LOGNAME), etc, as well as the special RSL substition $(DATE) which will be resolved at log time to the date in YYYYMMDD form.

-stdio-log LOG_DIRECTORY

Configure the job manager to write log messages to files in the LOG_DIRECTORY directory. This is a backward-compatible parameter, equivalent to '-log-pattern '.

-log-levels LEVELS

Configure the job manager to write log messages of certain levels to syslog and/or log files. The available log levels are FATAL, ERROR, WARN, INFO, DEBUG, and TRACE. Multiple values can be combined with the | character. The default value of logging when enabled is FATAL|ERROR.

-state-file-dir STATE_DIRECTORY

Configure the job manager to write state files to STATE_DIRECTORY. If not specified, the job manager uses the default of $GLOBUS_LOCATION/tmp/gram_job_state/. This directory must be writable by all users and be on a file system which supports POSIX advisory file locks. . This directory must be writable by all users and be on a file system which supports POSIX advisory file locks.

-globus-tcp-port-range PORT_RANGE

Configure the job manager to restrict its TCP/IP communication to use ports in the range described by PORT_RANGE. This value is also made available in the job environment via the GLOBUS_TCP_PORT_RANGE environment variable.

-globus-tcp-source-range SOURCE_RANGE

Configure the job manager to restrict its TCP/IP communication to use source ports in the range described by SOURCE_RANGE. This value is also made available in the job environment via the GLOBUS_TCP_SOURCE_RANGE environment variable.

-x509-cert-dir TRUSTED_CERTIFICATE_DIRECTORY

Configure the job manager to search TRUSTED_CERTIFICATE_DIRECTORY for its list of trusted CA certificates and their signing policies. This value is also made available in the job environment via the X509_CERT_DIR environment variable.

-cache-location GASS_CACHE_DIRECTORY

Configure the job manager to use the path GASS_CACHE_DIRECTORY for its temporary GASS-cache files. This value is also made available in the job environment via the GLOBUS_GASS_CACHE_DEFAULT environment variable.

-k

Configure the job manager to assume it is using Kerberos for authentication instead of X.509 certificates. This disables some certificate-specific processing in the job manager.

-extra-envvars VAR=VAL,…​

Configure the job manager to define a set of environment variables in the job environment beyond those defined in the base job environment. The format of the parameter to this argument is a comma-separated sequence of VAR=VAL pairs, where VAR is the variable name and VAL is the variable’s value. If the value is not specified, then the value of the variable in the job manager’s environment is used. This option may be present multiple times on the command-line or the job manager configuration file to append multiple environment settings.

-seg-module SEG_MODULE

Configure the job manager to use the schedule event generator module named by SEG_MODULE to detect job state changes events from the local resource manager, in place of the less efficient polling operations used in GT2. To use this, one instance of the globus-job-manager-event-generator must be running to process events for the LRM into a generic format that the job manager can parse.

-audit-directory AUDIT_DIRECTORY

Configure the job manager to write audit records to the directory named by AUDIT_DIRECTORY. This records can be loaded into a database using the globus-gram-audit program.

-globus-toolkit-version TOOLKIT_VERSION

Configure the job manager to use TOOLKIT_VERSION as the version for audit and usage stats records.

-service-tag SERVICE_TAG

Configure the job manager to use SERVICE_TAG as a unique identifier to allow multiple GRAM instances to use the same job state directories without interfering with each other’s jobs. If not set, the value untagged will be used.

-disable-streaming

Configure the job manager to disable file streaming. This is propagated to the LRM script interface but has no effect in GRAM5.

-disable-usagestats

Disable sending of any usage stats data, even if -usagestats-targets is present in the configuration.

-usagestats-targets TARGET

Send usage packets to a data collection service for analysis. The TARGET string consists of a comma-separated list of HOST:PORT combinations, each contaiing an optional list of data to send. See Usage Stats Packets for more information about the tags. Special tag strings of all (which enables all tags) and default may be used, or a sequence of characters for the various tags. If this option is not present in the configuration, then the default of usage-stats.globus.org:4810 is used.

-condor-arch ARCH

Set the architecture specification for condor jobs to be ARCH in job classified ads generated by the GRAM5 codnor LRM script. This is required for the condor LRM but ignored for all others.

-condor-os OS

Set the operating system specification for condor jobs to be OS in job classified ads generated by the GRAM5 codnor LRM script. This is required for the condor LRM but ignored for all others.

Environment

If the following variables affect the execution of globus-job-manager

HOME

User’s home directory.

LOGNAME

User’s name.

JOBMANAGER_SYSLOG_ID

String to prepend to syslog audit messages.

JOBMANAGER_SYSLOG_FAC

Facility to log syslog audit messages as.

JOBMANAGER_SYSLOG_LVL

Priority level to use for syslog audit messages.

GATEKEEPER_JM_ID

Job manager ID to be used in syslog audit records.

GATEKEEPER_PEER

Peer information to be used in syslog audit records

GLOBUS_ID

Credential information to be used in syslog audit records

GLOBUS_JOB_MANAGER_SLEEP

Time (in seconds) to sleep when the job manager is started. [For debugging purposes only]

GRID_SECURITY_HTTP_BODY_FD

File descriptor of an open file which contains the initial job request and to which the initial job reply should be sent. This file descriptor is inherited from the globus-gatekeeper.

X509_USER_PROXY

Path to the X.509 user proxy which was delegated by the client to the globus-gatekeeper program to be used by the job manager.

GRID_SECURITY_CONTEXT_FD

File descriptor containing an exported security context that the job manager should use to reply to the client which submitted the job.

GLOBUS_USAGE_TARGETS

Default list of usagestats services to send usage packets to.

GLOBUS_TCP_PORT_RANGE

Default range of allowed TCP ports to listen on. The -globus-tcp-port-range command-line option overrides this.

GLOBUS_TCP_SOURCE_RANGE

Default range of allowed TCP ports to bind to. The -globus-tcp-source-range command-line option overrides this.

Files

$HOME/.globus/job/HOSTNAME/LRM.TAG.red

Job manager delegated user credential.

$HOME/.globus/job/HOSTNAME/LRM.TAG.lock

Job manager state lock file.

$HOME/.globus/job/HOSTNAME/LRM.TAG.pid

Job manager pid file.

$HOME/.globus/job/HOSTNAME/LRM.TAG.sock

Job manager socket for inter-job manager communications.

$HOME/.globus/job/HOSTNAME/JOB_ID/

Job-specific state directory.

$HOME/.globus/job/HOSTNAME/JOB_ID/stdin

Standard input which has been staged from a remote URL.

$HOME/.globus/job/HOSTNAME/JOB_ID/stdout

Standard output which will be staged from a remote URL.

$HOME/.globus/job/HOSTNAME/JOB_ID/stderr

Standard error which will be staged from a remote URL.

$HOME/.globus/job/HOSTNAME/JOB_ID/x509_user_proxy

Job-specific delegated credential.

$GLOBUS_LOCATION/tmp/gram_job_state/job.HOSTNAME.JOB_ID

Job state file.

$GLOBUS_LOCATION/tmp/gram_job_state/job.HOSTNAME.JOB_ID.lock

Job state lock file. In most cases this will be a symlink to the job manager lock file.

$GLOBUS_LOCATION/etc/globus-job-manager.conf

Default location of the global job manager configuration file.

$GLOBUS_LOCATION/etc/grid-services/jobmanager-LRM

Default location of the LRM-specific gatekeeper configuration file.

$GLOBUS_LOCATION/etc/globus/gram/job—​manager.rvf

Default location of the site-specific job manager RSL validation file.

$GLOBUS_LOCATION/etc/globus/gram/lrm.rvf

Default location of the site-specific job manager RSL validation file for the named lrm.

See Also

globusrun(1), globus-gatekeeper(8), globus-personal-gatekeeper(1), globus-gram-audit(8)

GLOBUS-JOB-RUN(1)

NAME

globus-job-run - Execute a job using GRAM

SYNOPSIS

globus-job-run [-dumprsl ] [-dryrun ] [-verify ]

[-file ARGUMENT_FILE]

SERVICE_CONTACT

-np PROCESSES | -count PROCESSES

-m MAX_TIME | -maxtime MAX_TIME

-p PROJECT | -project PROJECT

-q QUEUE | -queue QUEUE

-d DIRECTORY | -directory DIRECTORY [-env NAME'VALUE']

[-stdin -l | -s STDIN_FILE] [-stdout -l | -s STDOUT_FILE] [-stderr -l | -s STDERR_FILE]

[-x RSL_CLAUSE]

-l | -s EXECUTABLE [ARGUMENT …​]

Description

The globus-job-run program constructs a job description from its command-line options and then submits the job to the GRAM service running at SERVICE_CONTACT. The executable and arguments to the executable are provided on the command-line after all other options. Note that the -dumprsl, -dryrun, -verify, and -file command-line options must occur before the first non-option argument, the SERVICE_CONTACT.

The globus-job-run provides similar functionality to globusrun in that it allows interactive start-up of GRAM jobs. However, unlike globusrun, it uses command-line parameters to define the job instead of RSL expressions.

Options

The full set of options to globus-job-run are:

-help, -usage

Display a help message to standard error and exit.

-version

Display the software version of the globus-job-run program to standard output.

-version

Display the software version of the globus-job-run program including DiRT information to standard output.

-dumprsl

Translate the command-line options to globus-job-run into an RSL expression that can be used with tools such as globusrun.

-dryrun

Submit the job request to the GRAM service with the dryrun option enabled. When this option is used, the GRAM service prepares to execute the job but stops before submitting the job to the LRM. This can be used to diagnose some problems such as missing files.

-verify

Submit the job request to the GRAM service with the dryrun option enabled and then without it enabled if the dryrun is successful.

-file ARGUMENT_FILE

Read additional command-line options from ARGUMENT_FILE.

-np PROCESSES, -count PROCESSES

Start PROCESSES instances of the executable as a single job.

-m MAX_TIME, -maxtime MAX_TIME

Schedule the job to run for a maximum of MAX_TIME minutes.

-p PROJECT, -project PROJECT

Request that the job use the allocation PROJECT when submitting the job to the LRM.

-q QUEUE, -queue QUEUE

Request that the job be submitted to the LRM using the named QUEUE.

-d DIRECTORY, -directory DIRECTORY

Run the job in the directory named by DIRECTORY. Input and output files will be interpreted relative to this directory. This directory must exist on the file system on the LRM-managed resource. If not specified, the job will run in the home directory of the user the job is running as.

-env NAME=VALUE

Define an environment variable named by NAME with the value VALUE in the job environment. This option may be specified multiple times to define multiple environment variables.

-stdin [-l | -s] STDIN_FILE

Use the file named by STDIN_FILE as the standard input of the job. If the -l option is specified, then this file is interpreted to be on a file system local to the LRM. If the -s option is specified, then this file is interpreted to be on the file system where globus-job-run is being executed, and the file will be staged via GASS. If neither is specified, the local behavior is assumed.

-stdout [-l | -s] STDOUT_FILE

Use the file named by STDOUT_FILE as the destination for the standard output of the job. If the -l option is specified, then this file is interpreted to be on a file system local to the LRM. If the -s option is specified, then this file is interpreted to be on the file system where globus-job-run is being executed, and the file will be staged via GASS. If neither is specified, the local behavior is assumed.

-stderr [-l | -s] STDERR_FILE

Use the file named by STDERR_FILE as the destination for the standard error of the job. If the -l option is specified, then this file is interpreted to be on a file system local to the LRM. If the -s option is specified, then this file is interpreted to be on the file system where globus-job-run is being executed, and the file will be staged via GASS. If neither is specified, the local behavior is assumed.

-x RSL_CLAUSE

Add a set of custom RSL attributes described by RSL_CLAUSE to the job description. The clause must be an RSL conjunction and may contain one or more attributes. This can be used to include attributes which can not be defined by other command-line options of globus-job-run.

-l

When included outside the context of -stdin, -stdout, or -stderr command-line options, -l option alters the interpretation of the executable path. If the -l option is specified, then the executable is interpreted to be on a file system local to the LRM.

-s

When included outside the context of -stdin, -stdout, or -stderr command-line options, -l option alters the interpretation of the executable path. If the -s option is specified, then the executable is interpreted to be on the file system where globus-job-run is being executed, and the file will be staged via GASS. If neither is specified, the local behavior is assumed.

ENVIRONMENT

If the following variables affect the execution of globus-job-run.

X509_USER_PROXY

Path to proxy credential.

X509_CERT_DIR

Path to trusted certificate directory.

See Also

globusrun(1), globus-job-submit(1), globus-job-clean(1), globus-job-get-output(1), globus-job-cancel(1)

GLOBUS-JOB-STATUS(1)

NAME

globus-job-status - Check the status of a GRAM5 job

SYNOPSIS

globus-job-status JOBID

Description

The globus-job-status program checks the status of a GRAM job by sending a status request to the job manager contact for that job specifed by the JOBID parameter. If successful, it will print the job status to standard output. The states supported by globus-job-status are:

PENDING

The job has been submitted to the LRM but has not yet begun execution.

ACTIVE

The job has begun execution.

FAILED

The job has failed.

SUSPENDED

The job is currently suspended by the LRM.

DONE

The job has completed.

UNSUBMITTED

The job has been accepted by GRAM, but not yet submitted to the LRM.

STAGE_IN

The job has been accepted by GRAM and is currently staging files prior to being submitted to the LRM.

STAGE_OUT

The job has completed execution and is currently staging files from the service node to other http, GASS, or GridFTP servers.

Options

The full set of options to globus-job-status are:

-help, -usage

Display a help message to standard error and exit.

-version

Display the software version of the globus-job-status program to standard output.

-versions

Display the software version of the globus-job-status program including DiRT information to standard output.

ENVIRONMENT

If the following variables affect the execution of globus-job-status.

X509_USER_PROXY

Path to proxy credential.

X509_CERT_DIR

Path to trusted certificate directory.

Bugs

The globus-job-status program can not distinguish between the case of the job manager terminating for any reason and the job being in the DONE state.

See Also

globusrun(1)

GLOBUS-JOB-SUBMIT(1)

NAME

globus-job-submit - Submit a batch job using GRAM

SYNOPSIS

globus-job-submit [-dumprsl ] [-dryrun ] [-verify ]

[-file ARGUMENT_FILE]

SERVICE_CONTACT

-np PROCESSES | -count PROCESSES

-m MAX_TIME | -maxtime MAX_TIME

-p PROJECT | -project PROJECT

-q QUEUE | -queue QUEUE

-d DIRECTORY | -directory DIRECTORY [-env NAME'VALUE']

[-stdin -l | -s STDIN_FILE] [-stdout -l | -s STDOUT_FILE] [-stderr -l | -s STDERR_FILE]

[-x RSL_CLAUSE]

-l | -s EXECUTABLE [ARGUMENT …​]

Description

The globus-job-submit program constructs a job description from its command-line options and then submits the job to the GRAM service running at SERVICE_CONTACT. The executable and arguments to the executable are provided on the command-line after all other options. Note that the -dumprsl, -dryrun, -verify, and -file command-line options must occur before the first non-option argument, the SERVICE_CONTACT.

The globus-job-submit provides similar functionality to globusrun in that it allows batch submission of GRAM jobs. However, unlike globusrun, it uses command-line parameters to define the job instead of RSL expressions.

To retrieve the output and error streams of the job, use the program globus-job-get-output. To reclaim resources used by the job by deleting cached files and job state, use the program globus-job-clean. To cancel a batch job submitted by globus-job-submit, use the program globus-job-cancel.

Options

The full set of options to globus-job-submit are:

-help, -usage

Display a help message to standard error and exit.

-version

Display the software version of the globus-job-submit program to standard output.

-versions

Display the software version of the globus-job-submit program including DiRT information to standard output.

-dumprsl

Translate the command-line options to globus-job-submit into an RSL expression that can be used with tools such as globusrun.

-dryrun

Submit the job request to the GRAM service with the dryrun option enabled. When this option is used, the GRAM service prepares to execute the job but stops before submitting the job to the LRM. This can be used to diagnose some problems such as missing files.

-verify

Submit the job request to the GRAM service with the dryrun option enabled and then without it enabled if the dryrun is successful.

-file ARGUMENT_FILE

Read additional command-line options from ARGUMENT_FILE.

-np PROCESSES, -count PROCESSES

Start PROCESSES instances of the executable as a single job.

-m MAX_TIME, -maxtime MAX_TIME

Schedule the job to run for a maximum of MAX_TIME minutes.

-p PROJECT, -project PROJECT

Request that the job use the allocation PROJECT when submitting the job to the LRM.

-q QUEUE, -queue QUEUE

Request that the job be submitted to the LRM using the named QUEUE.

-d DIRECTORY, -directory DIRECTORY

Run the job in the directory named by DIRECTORY. Input and output files will be interpreted relative to this directory. This directory must exist on the file system on the LRM-managed resource. If not specified, the job will run in the home directory of the user the job is running as.

-env NAME=VALUE

Define an environment variable named by NAME with the value VALUE in the job environment. This option may be specified multiple times to define multiple environment variables.

-stdin [-l | -s] STDIN_FILE

Use the file named by STDIN_FILE as the standard input of the job. If the -l option is specified, then this file is interpreted to be on a file system local to the LRM. If the -s option is specified, then this file is interpreted to be on the file system where globus-job-submit is being executed, and the file will be staged via GASS. If neither is specified, the local behavior is assumed.

-stdout [-l | -s] STDOUT_FILE

Use the file named by STDOUT_FILE as the destination for the standard output of the job. If the -l option is specified, then this file is interpreted to be on a file system local to the LRM. If the -s option is specified, then this file is interpreted to be on the file system where globus-job-submit is being executed, and the file will be staged via GASS. If neither is specified, the local behavior is assumed.

-stderr [-l | -s] STDERR_FILE

Use the file named by STDERR_FILE as the destination for the standard error of the job. If the -l option is specified, then this file is interpreted to be on a file system local to the LRM. If the -s option is specified, then this file is interpreted to be on the file system where globus-job-submit is being executed, and the file will be staged via GASS. If neither is specified, the local behavior is assumed.

-x RSL_CLAUSE

Add a set of custom RSL attributes described by RSL_CLAUSE to the job description. The clause must be an RSL conjunction and may contain one or more attributes. This can be used to include attributes which can not be defined by other command-line options of globus-job-submit.

-l

When included outside the context of -stdin, -stdout, or -stderr command-line options, -l option alters the interpretation of the executable path. If the -l option is specified, then the executable is interpreted to be on a file system local to the LRM.

-s

When included outside the context of -stdin, -stdout, or -stderr command-line options, -l option alters the interpretation of the executable path. If the -s option is specified, then the executable is interpreted to be on the file system where globus-job-run is being executed, and the file will be staged via GASS. If neither is specified, the local behavior is assumed.

ENVIRONMENT

If the following variables affect the execution of globus-job-submit.

X509_USER_PROXY

Path to proxy credential.

X509_CERT_DIR

Path to trusted certificate directory.

See Also

globusrun(1), globus-job-run(1), globus-job-clean(1), globus-job-get-output(1), globus-job-cancel(1)

GLOBUS-PERSONAL-GATEKEEPER(1)

NAME

globus-personal-gatekeeper - Manage a user’s personal gatekeeper daemon

SYNOPSIS

globus-personal-gatekeeper [-help ] [-usage ] [-version ] [-versions ] [-list ] [-directory CONTACT]

Description

The globus-personal-gatekeeper command is a utility which manages a gatekeeper and job manager service for a single user. Depending on the command-line arguments it will operate in one of several modes. In the first set of arguments indicated in the synopsis, the program provides information about the globus-personal-gatekeeper command or about instances of the globus-personal-gatekeeper that are running currently. The second set of arguments indicated in the synopsis provide control over starting a new globus-personal-gatekeeper instance. The final set of arguments provide control for terminating one or more globus-personal-gatekeeper instances.

The -start mode will create a new subdirectory of $HOME/.globus and write the configuration files needed to start a and write the configuration files needed to start a globus-gatekeeper daemon which will invoke the globus-job-manager service when new authenticated connections are made to its service port. The globus-personal-gatekeeper then exits, printing the contact string for the new gatekeeper prefixed by GRAM contact: to standard output. In addition to the arguments described above, any arguments described in globus-job-manager(8) can be appended to the command-line and will be added to the job manager configuration for the service started by the globus-gatekeeper.

The new globus-gatekeeper will continue to run in the background until killed by invoking globus-personal-gatekeeper with the -kill or -killall argument. When killed, it will kill the globus-gatekeeper and globus-job-manager processes, remove state files and configuration data, and then exit. Jobs which are running when the personal gatekeeper is killed will continue to run, but their job directory will be destroyed so they may fail in the LRM.

The full set of command-line options to globus-personal-gatekeeper consists of:

-help, -usage

Print command-line option summary and exit

-version

Print software version

-versions

Print software version including DiRT information

-list

Print a list of all currently running personal gatekeepers. These entries will be printed one per line.

-directory CONTACT

Print the configuration directory for the personal gatekeeper with the contact string CONTACT.

-debug

Print additional debugging information when starting a personal gatekeeper. This option is ignored in other modes.

-start

Start a new personal gatekeeper process.

-jmtype LRM

Use LRM as the local resource manager interface. If not provided when starting a personal gatekeeper, the job manager will use the default fork LRM.

-auditdir AUDIT_DIRECTORY

Write audit report files to AUDIT_DIRECTORY. If not provided, the job manager will not write any audit files.

-port PORT

Listen for gatekeeper TCP/IP connections on the port PORT. If not provided, the gatekeeper will let the operating system choose.

-log[=DIRECTORY]

Write job manager log files to DIRECTORY. If DIRECTORY is omitted, the default of $HOME will be used. If this option is not present, the job manager will not write any log files. will be used. If this option is not present, the job manager will not write any log files.

-seg

Try to use the SEG mechanism to receive job state change information, instead of polling for these. These require either the system administrator or the user to run an instance of the globus-job-manager-event-generator program for the LRM specified by the -jmtype option.

-acctfile ACCOUNTING_FILE

Write gatekeeper accounting entries to ACCOUNTING_FILE. If not provided, no accounting records are written.

Examples

This example shows the output when starting a new personal gatekeeper which will schedule jobs via the lsf LRM, with debugging enabled.

%  globus-personal-gatekeeper -start -jmtype lsf

verifying setup...
done.
GRAM contact: personal-grid.example.org:57846:/DC=org/DC=example/CN=Joe User

This example shows the output when listing the current active personal gatekeepers.

%  globus-personal-gatekeeper -list

personal-grid.example.org:57846:/DC=org/DC=example/CN=Joe User

This example shows the output when querying the configuration directory for th eabove personal gatekeeper. gatekeepers.

%  globus-personal-gatekeeper -directory "personal-grid.example.org:57846:/DC=org/DC=example/CN=Joe User"

/home/juser/.globus/.personal-gatekeeper.personal-grid.example.org.1337
%  globus-personal-gatekeeper -kill "personal-grid.example.org:57846:/DC=org/DC=example/CN=Joe User"

killing gatekeeper: "personal-grid.example.org:57846:/DC=org/DC=example/CN=Joe User"

See Also

globusrun(1), globus-job-manager(8), globus-gatekeeper(8)

GLOBUS-RVF-CHECK(8)

NAME

globus-rvf-check - Edit a GRAM5 RSL validation file

SYNOPSIS

globus-rvf-check [-h ] [-help ]

Description

The globus-rvf-check command is a utility which checks the syntax of a RSL validation file, and prints out parse errors when encountered. It can also parse the RVF file contents and then dump file’s contents to stdout, after canonicalizing values and quoting. The exit code of globus-rvf-check is 0 if all files specified on the command line exist and have no parse errors.

The full set of command-line options to globus-rvf-check consists of:

-h, -help, --help

Print command-line option summary and exit

-d

Dump the RVF contents to stdout. In the output, Each file which is parsed will be prefixed by an RVF comment which contains the input filename. If not specified, globus-rvf-check just prints a diagnostic message to standard output indicating whether the file could be parsed.

GLOBUS-RVF-EDIT(8)

NAME

globus-rvf-edit - Edit a GRAM5 RSL validation file

SYNOPSIS

globus-rvf-edit [-h ]

Description

The globus-rvf-edit command is a utility which opens the default editor on a specified RSL validation file, and then, when editing completes, runs the globus-rvf-check command to verify that the RVF file syntax is correct. If a parse error occurs, the user will be given an option to rerun the editor or discard the modifications.

The full set of command-line options to globus-rvf-edit consists of:

-h

Print command-line option summary and exit

-s

Edit of the site-specific RVF file, which provides override values applicable to all LRMs installed on the system.

-l LRM

Edit the site-specific LRM overrides for the LRM named by the LRM parameter to the option.

-f PATH

Edit the RVF file located at PATH

GLOBUS-SCHEDULER-EVENT-GENERATOR-ADMIN(8)

NAME

globus-scheduler-event-generator-admin - Manage SEG modules

SYNOPSIS

globus-scheduler-event-generator-admin [-h ]

Description

The globus-scheduler-event-generator-admin program manages SEG modules which are used by the globus-scheduler-event-generator to monitor a local resource manager or batch system for events. The globus-scheduler-event-generator-admin can list, enable, or disable specific SEG modules. The -h command-line option shows a brief usage message.

Listing SEG Modules

The -l command-line option to globus-scheduler-event-generator-admin will cause it to list all of the SEG modules which are available to be run by the globus-scheduler-event-generator. In the output, the service name will be followed by its status in brackets. Possible status strings are ENABLED and DISABLED.

Enabling SEG Modules

The '-e ' command-line option to globus-scheduler-event-generator-admin will cause it to enable the module so that the init script for the globus-scheduler-event-generator will run it.

Disabling SEG Modules

The '-d ' command-line option to globus-scheduler-event-generator-admin will cause it to disable the module so that it will not be started by the globus-scheduler-event-generator init script.

Files

/etc/globus/scheduler-event-generator

Default location of enabled SEG modules.

See Also

globus-scheduler-event-generator(8)

GLOBUS-SCHEDULER-EVENT-GENERATOR(8)

NAME

globus-scheduler-event-generator - Process LRM events into a common format for use with GRAM

SYNOPSIS

globus-scheduler-event-generator -s LRM

[-t TIMESTAMP] [-d DIRECTORY]

[-b ] [-p PIDFILE]

Description

The globus-scheduler-event-generator program processes information from a local resource manager to generate LRM-independent events which GRAM can use to track job state changes. Typically, the globus-scheduler-event-generator is started at system boot time for all LRM adapters which have been installed. The only required parameter to globus-scheduler-event-generator is '-s ', which indicates what LRM-specific module to load. A list of available modules can be found by using the globus-scheduler-event-generator-admin command.

Other options control how the globus-scheduler-event-generator program runs and where its output goes. These options are:

-t TIMESTAMP

Start processing events which start at TIMESTAMP in seconds since the UNIX epoch. If not present, the globus-scheduler-event-generator will process events from the time it was started, and not look for historical events.

-d DIRECTORY

Write the event log to files in DIRECTORY, instead of printing them to standard output. Within DIRECTORY, logs will be named by the time when they were created in YYYYMMDD format.

-b

Run the globus-scheduler-event-generator program in the background.

-p PIDFILE

Write the process-id of globus-scheduler-event-generator to PIDFILE.

Files

/var/lib/globus/globus-seg-LRM/YYYYMMDD

LRM-independent event log generated by globus-scheduler-event-generator

See Also

globus-scheduler-event-generator-admin(8), globus-job-manager(8)

GLOBUSRUN(1)

NAME

globusrun - Execute and manage jobs via GRAM

SYNOPSIS

globusrun [-help ] [-usage ] [-version ] [-versions ]

Description

The globusrun program for submits and manages jobs run on a local or remote job host. The jobs are controlled by the globus-job-manager program which interfaces with a local resource manager that schedules and executes the job.

The globusrun program can be run in a number of different modes chosen by command-line options.

When -help, -usage, -version, or -versions command-line options are used, globusrun will print out diagnostic information and then exit.

When the -p or -parse command-line option is present, globusrun will verify the syntax of the RSL specification and then terminate. If the syntax is valid, globusrun will print out the string "RSL Parsed Successfully…​" and exit with a zero exit code; otherwise, it will print an error message and terminate with a non-zero exit code.

When the -a or -authenticate-only command-line option is present, globusrun will verify that the service named by RESOURCE_CONTACT exists and the client’s credentials are granted permission to access that service. If authentication is successful, globusrun will display the string "GRAM Authentication test successful" and exit with a zero exit code; otherwise it will print an explanation of the problem and will with a non-zero exit code.

When the -j or -jobmanager-version command-line option is present, globusrun will attempt to determine the software version that the service named by RESOURCE_CONTACT is running. If successful, it will display both the Toolkit version and the Job Manager package version and exit with a zero exit code; otherwise, it will print an explanation of the problem and exit with a non-zero exit code.

When the -k or -kill command-line option is present, globusrun will attempt to terminate the job named by JOB_ID. If successful, globusrun will exit with zero; otherwise it will display an explanation of the problem and exit with a non-zero exit code.

When the -y or -refresh-proxy command-line option is present, globusrun will attempt to delegate a new X.509 proxy to the job manager which is managing the job named by JOB_ID. If successful, globusrun will exit with zero; otherwise it will display an explanation of the problem and exit with a non-zero exit code. This behavior can be modified by the -full-proxy or -D command-line options to enable full proxy delegation. The default is limited proxy delegation.

When the -status command-line option is present, globusrun will attempt to determine the current state of the job. If successful, the state will be printed to standard output and globusrun will exit with a zero exit code; otherwise, a description of the error will be displayed and it will exit with a non-zero exit code.

Otherwise, globusrun will submit the job to a GRAM service. By default, globusrun waits until the job has terminated or failed before exiting, displaying information about job state changes and at exit time, the job exit code if it is provided by the GRAM service.

The globusrun program can also function as a GASS file server to allow the globus-job-manager program to stage files to and from the machine on which globusrun is executed to the GRAM service node. This behavior is controlled by the -s, -o, and -w command-line options.

Jobs submitted by globusrun can be monitored interactively or detached. To have globusrun detach from the GRAM service after submitting the job, use the -b or -F command-line options.

Options

The full set of options to globusrun consist of:

-help

Display a help message to standard error and exit.

-usage

Display a one-line usage summary to standard error and exit.

-version

Display the software version of globusrun to standard error and exit.

-versions

Display the software version of all modules used by globusrun (including DiRT information) to standard error and then exit.

-p, -parse

Do a parse check on the job specification and print diagnostics. If a parse error occurs, globusrun exits with a non-zero exit code.

-f RSL_FILENAME, -file RSL_FILENAME:: Read job specification from the file named by RSL_FILENAME.

-n, -no-interrupt

Disable handling of the SIGINT signal, so that the interrupt character (typically ) causes globusrun to terminate without canceling the job.

-r RESOURCE_CONTACT, -resource RESOURCE_CONTACT

Submit the request to the resource specified by RESOURCE_CONTACT. A resource may be specified in the following ways:

  • HOST

  • HOST:'PORT'

  • HOST:'PORT'/SERVICE

  • HOST/SERVICE

  • HOST:/SERVICE

  • HOST::'SUBJECT'

  • HOST:'PORT':'SUBJECT'

  • HOST/SERVICE:'SUBJECT'

  • HOST:/SERVICE:'SUBJECT'

  • HOST:'PORT'/SERVICE:'SUBJECT'

    If any of PORT, SERVICE, or SUBJECT is omitted, the defaults of 2811, jobmanager, and host@HOST are used respectively.

-j, -jobmanager-version

Print the software version being run by the service running at RESOURCE_CONTACT.

-k JOB_ID, -kill JOB_ID

Kill the job named by JOB_ID

-D, -full-proxy

Delegate a full impersonation proxy to the service. By default, a limited proxy is delegated when needed.

-y, -refresh-proxy

Delegate a new proxy to the service processing JOB_ID.

-status

Display the current status of the job named by JOB_ID.

-q, -quiet

Do not display job state change or exit code information.

-o, -output-enable

Start a GASS server within the globusrun application that allows access to its standard output and standard error streams only. Also, augment the RSL_SPECIFICATION with a definition of the GLOBUSRUN_GASS_URL RSL substitution and add stdout and stderr clauses which redirect the output and error streams of the job to the output and error streams of the interactive globusrun command. If this is specified, then globusrun acts as though the -q were also specified.

-s, -server

Start a GASS server within the globusrun application that allows access to its standard output and standard error streams for writing and any file local the the globusrun invocation for reading. Also, augment the RSL_SPECIFICATION with a definition of the GLOBUSRUN_GASS_URL RSL substitution and add stdout and stderr clauses which redirect the output and error streams of the job to the output and error streams of the interactive globusrun command. If this is specified, then globusrun acts as though the -q were also specified.

-w, -write-allow

Start a GASS server within the globusrun application that allows access to its standard output and standard error streams for writing and any file local the the globusrun invocation for reading or writing. Also, augment the RSL_SPECIFICATION with a definition of the GLOBUSRUN_GASS_URL RSL substitution and add stdout and stderr clauses which redirect the output and error streams of the job to the output and error streams of the interactive globusrun command. If this is specified, then globusrun acts as though the -q were also specified.

-b, -batch

Terminate after submitting the job to the GRAM service. The globusrun program will exit after the job hits any of the following states: PENDING, ACTIVE, FAILED, or DONE. The GASS-related options can be used to stage input files, but standard output, standard error, and file staging after the job completes will not be processed.

-F, -fast-batch

Terminate after submitting the job to the GRAM service. The globusrun program will exit after it receives a reply from the service. The JOB_ID will be displayed to standard output before terminating so that the job can be checked with the -status command-line option or modified by the -refresh-proxy or -kill command-line options.

-d, -dryrun

Submit the job with the dryrun attribute set to true. When this is done, the job manager will prepare to start the job but start short of submitting it to the service. This can be used to detect problems with the RSL_SPECIFICATION.

Environment

If the following variables affect the execution of globusrun

X509_USER_PROXY

Path to proxy credential.

X509_CERT_DIR

Path to trusted certificate directory.

Bugs

The globusrun program assumes any failure to contact the job means the job has terminated. In fact, this may be due to the globus-job-manager program exiting after all jobs it is managing have reached the DONE or FAILED states. In order to reliably detect job termination, the two_phase RSL attribute should be used.

See Also

globus-job-submit(1), globus-job-run(1), globus-job-clean(1), globus-job-get-output(1), globus-job-cancel(1)

GSI-OpenSSH Commands

Introduction

The gsissh, gsiscp, and gsiftp commands provide the same interfaces as the standard OpenSSH ssh, scp, and sftp commands, respectively, with the added ability to perform X.509 proxy credential authentication and delegation.

GSISSH(1)

NAME

gsissh - Secure remote login

SYNOPSIS

gsissh

Tool description

Use the gsissh command to securely login to a remote machine.

Command syntax

gsissh [-l login_name] hostname | user@hostname [command]

GSISCP(1)

NAME

gsiscp - Secure remote file copy

SYNOPSIS

gsiscp

Tool description

Use the gsiscp command to securely copy files to or from a remote machine.

Command syntax

gsiscp [-P port] [[user@]host1:]file1 […​] [[user@]host2:]destfile

GSISFTP(1)

NAME

gsisftp - Secure file transfer

SYNOPSIS

gsisftp

Tool description

The gsisftp command provides an interactive interface for transferring files to and from remote machines.

Command syntax

gsisftp [[user@host[:dir[/]]] ]

Simple CA Commands

GRID-CA-CREATE(1)

NAME

grid-ca-create - Create a CA to sign certificates for use on a grid

SYNOPSIS

grid-ca-create [-help ] [-h ] [-usage ] [-version ] [-versions ]

Description

The grid-ca-create program creates a self-signed CA certificate and related files needed to use the CA with other GCT tools. The grid-ca-create program prompts for information to use to generate the CA certificate, but the prompts may be avoided by using the command line options.

By default, the grid-ca-create program creates the self-signed CA certificate, installs it on the current machine in its trusted certificate directory, and creates a source tarball which can be used to generate an RPM package for the CA. If the RPM package is installed on a machine, users on that machine can create certificate requests for user, host, or service identity certificates to be signed by the CA certificate generated by running grid-ca-create.

If run as a privileged user, the grid-ca-create program creates the CA certificate and support files in ${localstatedir}/lib/globus/simple_ca and the CA certificate and signing policy are installed in the and the CA certificate and signing policy are installed in the /etc/grid-security directory. Otherwise, the files are created in the directory. Otherwise, the files are created in the ${HOME}/.globus/simpleCA directory. directory.

The full set of command-line options to grid-ca-create follows. In addition to these, unknown options will be passed to the openssl command when creating the self-signed certificate.

-help, -h, -usage

Display the command-line options to grid-ca-create and exit.

-version, -versions

Display the version number of the grid-ca-create command. The second form includes more details.

-force

Overwite existing CA in the destination directory if one exists

-noint

Run in non-interactive mode. This will choose defaults for parameters or those specified on the command line without prompting. This option also implies -force.

-dir DIRECTORY

Create the CA in DIRECTORY. The DIRECTORY must not exist prior to running grid-ca-create.

-subject SUBJECT

Use SUBJECT as the subject name of the self-signed CA to create. If this is not specified on the command-line, grid-ca-create will default to using the subject name cn=Globus Simple CA, ou=$HOSTNAME.

-email ADDRESS

Use ADDRESS as the email address of the CA. The default instructions generated by grid-ca-create tell users to mail the certificate request to this address. If this is not specified on the command-line, grid-ca-create will default to the $LOGNAME@$HOSTNAME

-days DAYS

Set the default lifetime of the self-signed CA certificate to DAYS. If not set, the grid-ca-create program will default to 1825 days (5 years).

-pass PASSWORD

Use the string PASSWORD to protect the CA’s private key. This is useful for automating Simple CA, but may make it easier to compromise the CA if someone obtains a shell on the machine storing the CA’s private key.

-nobuild

Disable building a source tarball for distributing the CA’s public information to other machines. The source tarball can be created later by using the grid-ca-package command.

-g

Create a binary GPT package containing the new CA’s public information. The package will be created in the current working directory. This package can be deployed by with the gpt-install tool.

-b

Create a binary GPT package containing the new CA’s public information that is backward-compatible with GPT 3.2. Packages created in this manner will work with Globus Toolkit 2.0.0-5.0.x.

Examples

Create a simple CA in $HOME/SimpleCA

%  grid-ca-create -noint -dir

    C e r t i f i c a t e    A u t h o r i t y    S e t u p

    This script will setup a Certificate Authority for signing Globus
    users certificates.  It will also generate a simple CA package
    that can be distributed to the users of the CA.

    The CA information about the certificates it distributes will
    be kept in:

    /home/juser/SimpleCA

    The unique subject name for this CA is:

    cn=Globus Simple CA, ou=simpleCA-grid.example.org, ou=GlobusTest, o=Grid

    Insufficient permissions to install CA into the trusted certifiicate
    directory (tried ${sysconfdir}/grid-security/certificates and
    ${datadir}/certificates)
    Creating RPM source tarball... done
      globus_simple_ca_0146c503.tar.gz

Environment Variables

The following environment variables affect the execution of grid-ca-create:

GLOBUS_LOCATION

Non-standard installation path of the Grid Community Toolkit.

See Also

grid-cert-request(1), grid-ca-sign(1), grid-default-ca(1), grid-ca-package(1)

GRID-CA-PACKAGE(1)

NAME

grid-ca-package - Prepare a CA certificate, configuration, and policy for distribution

SYNOPSIS

grid-ca-package [-help ] [-h ] [-usage ] [-version ] [-versions ]

Description

The grid-ca-package utility creates a tarball containing an RPM spec file and the files needed to use a CA with grid tools. It optionally will also create a GPT package for distributing a CA.

By default, the grid-ca-package utility displays a list of installed grid CA and prompts for which CA to package. It then creates a tarball containing the CA certificate, signing policy, CA configuration files, and an spec script to generate a binary RPM package containing the CA. If the CA hash is known prior to running grid-ca-package, it may provided as an argument to the -ca parameter to avoid prompting. grid-ca-package may also be used to package a SimpleCA directory, using the -cadir parameter.

In addition to generating a spec script and tarball, grid-ca-package creates a GPT package if either the -g or -b options are used on the command-line. These packages may be used to distribute a CA and configuration to systems which do not support RPM packages.

The grid-ca-package utility writes the package tarballs to the current working directory.

The full set of command-line options to grid-ca-package follows.

-help, -h, -usage

Display the command-line options to grid-ca-package and exit.

-version, -versions

Display the version number of the grid-ca-package command. The second form includes more details.

-ca CA

Use the CA whose name matches the hash string CA. When invoked with this option, grid-ca-package runs non-interactively.

-cadir SIMPLECADIR

Use the SimpleCA located in SIMPLECADIR When invoked with this option, grid-ca-package runs non-interactively.

-g

Create a GPT binary package in addition to the RPM script tarball. This package may be installed on other systems using the gpt-install program.

-b

Create a GPT binary package with GPT metadata located in the path expected by GPT 3.2 (used in Globus 2.0.0-5.0.x) instead of ${datadir}/globus/packages as used in Globus 5.2.x. This option overrides the as used in Globus 5.2.x. This option overrides the -g command-line option.

-r

Create a binary RPM package for the CA. This option currently only works on RPM-based distributions.

-d

Create a binary Debian package for the CA. This option currently only works on Debian-based distributions.

Examples

Package a Simple CA with hash 0146c503

%  grid-ca-package -ca
Creating RPM source tarball... done
  globus_simple_ca_0146c503.tar.gz

Environment Variables

The following environment variables affect the execution of grid-ca-package:

GLOBUS_LOCATION

Non-standard installation path of the Grid Community Toolkit.

See Also

grid-cert-request(1), grid-ca-sign(1), grid-default-ca(1), grid-ca-create(1)

GRID-CA-SIGN(1)

NAME

grid-ca-sign - Sign a certificate with a SimpleCA for use on a grid

SYNOPSIS

grid-ca-sign [-help ] [-h ] [-usage ] [-version ] [-versions ]

Description

The grid-ca-sign program signs a certificate based on a request file with a CA certificate created by grid-ca-create. The new certificate is written to a file. If the CA has already signed a certificate with the same subject name as contained in the certificate request, it will refuse to sign the new request unless the -force option is provided on the command-line.

If run as a privileged user, grid-ca-sign uses the CA certificate and configuration located in ${localstatedir}/lib/globus/simple_ca to sign the certificate. For a non-privileged user, to sign the certificate. For a non-privileged user, grid-ca-sign uses the CA certificate and configuration located in $HOME/.globus/simpleCA. The . The grid-ca-sign program an use a different CA configuration and certificate by using the -dir option.

The full set of command-line options to grid-ca-sign follows. In addition to these, unknown options will be passed to the openssl command when creating the self-signed certificate.

-help, -h, -usage

Display the command-line options to grid-ca-sign and exit.

-version, -versions

Display the version number of the grid-ca-sign command. The second form includes details about the package containing grid-ca-sign.

-in REQUEST

Sign the request contained in the REQUEST file.

-out CERTIFICATE

Write the signed request to the CERTIFICATE file.

-force

Revoke any previously issued certificate with the same subject name as in the certificate request and issue a new certificate. Otherwise, grid-ca-sign will refuse to sign the request.

-dir DIRECTORY

Sign the certificate using the Simple CA certificate and configuration located in DIRECTORY instead of the default.

-openssl-help

Print the command-line options available for the openssl ca command.

Examples

Sign a certificate request using the simple CA in $HOME/SimpleCA

%  grid-ca-sign -in usercert_request.pem -out usercert.pem -dir

To sign the request
please enter the password for the CA key:

The new signed certificate is at: /home/juser/.globus/simpleCA/newcerts/01.pem

Environment Variables

The following environment variables affect the execution of grid-ca-sign:

GLOBUS_LOCATION

Non-standard installation path of the Grid Community Toolkit.

See Also

grid-cert-request(1), grid-ca-create(1), grid-default-ca(1), grid-ca-package(1)