4 Creating and setting up client-side programs

4.1 Creating a Ninf-G Client

4.2 Setting up the Ninf-G Client operating environment

4.3 Ninf-G Client configuration file specifications

4.3.1 Structure of the configuration file

The Ninf-G Client configuration file is a text file which contains settings information that is required for the operation of a Ninf-G Client. It consists of seven sections, which are INCLUDE, CLIENT, FUNCTION_INFO, INVOKE_SERVER, CLIENT_COMMUNICATION_PROXY, INFORMATION_SOURCE, SERVER, and SERVER_DEFAULT.

Examples of section and attribute descriptions are shown below.

#comment
<section>
attribute    value    # comment

attribute    value    # comment
attribute    value    # comment
</section>
...

Examples of errors in description are shown below.

<section>Attribute Value
                             # Section and attribute on the same line
 
AttributeValue     # No delimiter between the attribute and attribute value
 
Attribute  Value   Attribute  Value
                             # Multiple attributes on the same line
 
Attribute                    # Attribute and attribute value
Value                        # extend across more than one line.
 
Attribute \
Value                        # Line continued with a backslash (\)
 
Attribute                    #  No attribute value
</section>
 
<CLIENT>                     # Multiple definitions in a section where
...                          #
</CLIENT>                    #
<CLIENT>                     # multiple definitions are not allowed
...                          #
</CLIENT>                    #
 
<INVOKE_SERVER>              # Attribute value redundancy within a section
type  TypeA                  #  where multiple definitions are allowed
</INVOKE_SERVER>
<INVOKE_SERVER>
type  TypeA
</INVOKE_SERVER>             #
 
<SERVER>                     # Attribute value redundancy
hostname  example.org        # for an attribute that allows
hostname  example.org        #  multiple attribute values
</SERVER>
 
<SERVER>
HostName  example.com        # Upper and lower case letters
hostname  EXAMPLE.COM        # Upper and lower case letters
</SERVER>

4.3.2 Specifying the unit for time

When a time value is specified as an attribute value (for time-out or other such attributes), a unit of time can be specified (e.g., 30 s, 30 sec or 30 seconds).

It is also possible to specify 'minute' or 'hour' as the time unit. Character strings such as 'se' and 'seco' are also interpreted to mean second, but strings that are not contained in 'second', such as 'set' will cause an error.

4.3.3 Specifying the unit for number of bytes

When specifying the number of bytes as an attribute value for attributes such as log file size, units (*) such as 1 K or 1 Kilo can be specified. Mega and Giga can also be specified as a unit for number of bytes.

Character strings such as Me, Meg, etc. are also interpreted to mean Mega, but strings that are not contained in Mega, such as Ma cause an error.

(*) 1 K = 1024 bytes, 1 M = 1024 Kbytes, 1 G = 1024 Mbytes

Each section of the configuration file is described below.

4.3.4 INCLUDE section

The INCLUDE section allows multiple definitions.

An example of an INCLUDE section description is shown below.

<INCLUDE>
filename    file name
filename    file name
</INCLUDE>

The attributes and attribute values of the INCLUDE section are shown below.

Attribute Attribute value Default value Multiple Explanation
filename File name None Yes File to be included

4.3.5 CLIENT section

The CLIENT section does not allow multiple definitions.

An example of a CLIENT section description is shown below.

<CLIENT>
hostname                  Host name
save_sessionInfo          Session information count
loglevel                  [0-5]
loglevel_ninfgProtocol    [0-5]
loglevel_ninfgInternal    [0-5]
loglevel_ninfgGrpc        [0-5]
log_filePath              File name
log_suffix                Suffix
log_nFiles                Number of files
log_maxFileSize           Number of bytes
log_overwriteDirectory    [true/false]
tmp_dir                   Directory
refresh_credential        Seconds
invoke_server_log         log name
client_communication_proxy_log log name
information_service_log   log name
fortran_compatible        [true/false]
handling_signals          Signals ...
listen_port               Port number 
use_vfork                 [true/false]
</CLIENT>

The attributes and attribute values of the CLIENT section are shown below.

Attribute Attribute value Default value Multiple Explanation
hostname Host name system hostname No The host name of the client
save_sessionInfo Session information count 256 No The number of session information units to be saved
loglevel [0-5] 2 No Overall log level
loglevel_ninfgProtocol [0-5] 2 No Ninf-G protocol error log level
loglevel_ninfgInternal [0-5] 2 No Ninf-G internal error log level
loglevel_ninfgGrpc [0-5] 2 No Grid RPC API error log level
log_filePath File name stderr No The log file name
log_suffix Suffix Sequence number No The log file suffix
log_nFiles Number of files 1 No The number of files for log
log_maxFileSize Number of bytes 1M/unlimited No Maximum number of bytes for log file
log_overwriteDirectory [true/false] false No Over-write permission for log directory
tmp_dir For temporary files /tmp No The directory in which temporary files are placed
refresh_credential Seconds 0 No Refreshing proxy credential interval
invoke_server_log log name None No Invoke Server log filename
client_communication_proxy_log log name None No Client Communication Proxy log filename
information_service_log log name None No Information Service log filename
fortran_compatible [true/false] false No Fortran compatible mode
handling_signals Signal names/numbers SIGHUP SIGINT SIGTERM No Handling signals
listen_port Port number 0 No The port number for listening requests
use_vfork [true/false] false No Whether Ninf-G Client uses vfork() for invoking external modules

The log level can be specified by using the strings listed in the 'Meaning' column in the table below as well as by using a number value.

The meanings of the log level values are described below.

Value Meaning Explanation
0 Off Nothing is output.
1 Fatal A fatal error is output.
2 Error A nonfatal error is output.
3 Warning A warning error is output.
4 Information Guidance or other such information is output.
5 Debug Debugging information is output.

4.3.6 FUNCTION_INFO section

The FUNCTION_INFO section allows multiple definitions. The FUNCTION_INFO section may be omitted.

An example of a FUNCTION_INFO section description is shown below.

<FUNCTION_INFO>
hostname     Host name
funcname     Function name

path         Path
staging      [true/false]
backend      Backend
session_timeout Seconds
transferTimeout_argument         Seconds
transferTimeout_result           Seconds
transferTimeout_callbackArgument Seconds
transferTimeout_callbackResult   Seconds
</FUNCTION_INFO>

The attributes and attribute values of the FUNCTION_INFO section are shown below.

Attribute Attribute value Default value Multiple Explanation
hostname Host name None No Server machine host name
funcname Function name None No The function name of the remote function
path Path None No The path to the Ninf-G Executable
staging [true/false] false No Staging enabled or disabled
backend Backend normal No Backend software by which Ninf-G Executable is launched
session_timeout Seconds 0 No RPC execution timeout
transferTimeout_argument Seconds 0 No argument transfer timeout
transferTimeout_result Seconds 0 No result transfer timeout
transferTimeout_callbackArgument Seconds 0 No callback argument transfer timeout
transferTimeout_callbackResult Seconds 0 No callback result transfer timeout

4.3.7 INVOKE_SERVER section

The INVOKE_SERVER section allows multiple definitions. The INVOKE_SERVER section can be omitted.

An example of an INVOKE_SERVER section description is shown below.

<INVOKE_SERVER>
type           type name
path           path name
max_jobs       Number of jobs
log_filePath   path of logfile
status_polling Seconds
option         "option string"
</INVOKE_SERVER>

The attributes and attribute values of the INVOKE_SERVER section are shown below.

Attribute Attribute value Default value Multiple Explanation
type type name None No Invoke Server type
path path name $NG_DIR/bin/
ng_invoke_server.[type] 		No Invoke Server executable file path
max_jobs Number of jobs 0 No max jobs for one Invoke Server
log_filePath path None No log file path
status_polling Seconds 0 No Polling interval
option "option string" None Yes option

4.3.8 CLIENT_COMMUNICATION_PROXY section

The CLIENT_COMMUNICATION_PROXY section allows multiple definitions. The CLIENT_COMMUNICATION_PROXY section can be omitted.

An example of an CLIENT_COMMUNICATION_PROXY section description is shown below.

<CLIENT_COMMUNICATION_PROXY>
type           type name
path           path name
buffer_size    size
max_jobs       Number of jobs
log_filePath   path of logfile
option         "option string"
</CLIENT_COMMUNICATION_PROXY>

The attributes and attribute values of the CLIENT_COMMUNICATION_PROXY section are shown below.

Attribute Attribute value Default value Multiple Explanation
type type name None No Communication Proxy type
path path name $NG_DIR/bin/
ng_client_communication_proxy.[type] 		No Client Communication Proxy executable file path
buffer_size Number of Bytes 0 No Client Communication Proxy buffer size
max_jobs Number of jobs 0 No max jobs for one Client Communication Proxy
log_filePath path None No log file path
option "option string" None Yes option

4.3.9 INFORMATION_SOURCE section

The INFORMATION_SOURCE section allows multiple definitions. The INFORMATION_SOURCE section can be omitted.

An example of an INFORMATION_SOURCE section description is shown below.

<INFORMATION_SOURCE>
type           type name
tag            tag name
path           path name
log_filePath   path of logfile
timeout        Seconds
source         source string
option         "option string"
</INFORMATION_SOURCE>

The attributes and attribute values of the INFORMATION_SOURCE section are shown below.

Attribute Attribute value Default value Multiple Explanation
type type name None No Information Service type
tag tag name None No Information Source tag
path path name $NG_DIR/bin/
ng_information_service.[type] 		No Information Service executable file path
log_filePath path None No log file path
timeout Seconds 0 No timeout time
source "source string" None Yes Information source
option "option string" None Yes option

4.3.10 SERVER section

The SERVER section allows multiple definitions.

When the SERVER section contains multiple definitions, the following API checks to see if remote function information is registered in the first-defined SERVER. If it is, that server is used. If it is not, a check is made for registered remote function information in the second SERVER. This is repeated until remote function information is found.

An example of a SERVER section description is shown below.

<SERVER>
hostname                      Host name
hostname                      Host name  host name  host name ...

tag                           Tag name
port                          Port number
invoke_server                 Type
invoke_server_option          "option string"
communication_proxy           Type
communication_proxy_staging   [true/false]
communication_proxy_path      path name
communication_proxy_buffer_size Size
communication_proxy_option    "option string"
information_source_tag        Tag name
keep_connection               [true/false]
mpi_runNoOfCPUs               [function name=]number of CPUs
force_xdr                     [true/false]
jobmanager                    JOBMANAGER
subject                       "Subject"
client_hostname               Host name

job_startTimeout              Seconds
job_stopTimeout               Seconds
job_maxTime                   Minutes
job_maxWallTime               Minutes
job_maxCpuTime                Minutes
job_queue                     Queue name
job_project                   Project name
job_hostCount                 Number of nodes
job_minMemory                 Size
job_maxMemory                 Size
job_rslExtensions             "extension string"

heartbeat                     Seconds
heartbeat_timeoutCount        Times
redirect_outerr               [true/false]
tcp_nodelay                   [true/false]
tcp_connect_retryCount        Counts
tcp_connect_retryBaseInterval Seconds
tcp_connect_retryIncreaseRatio Ratio
tcp_connect_retryRandom       [true/false]
argument_transfer             [wait/nowait/copy]
compress                      [raw/zlib]
compress_threshold            Number of bytes
argument_blockSize            Number of bytes
workDirectory                 Directory name
coreDumpSize                  Size

commLog_enable                [true/false]
commLog_filePath              File name
commLog_suffix                Suffix
commLog_nFiles                Number of files
commLog_maxFileSize           Number of bytes
commLog_overwriteDirectory    [true/false]

debug                         [true/false]
debug_display                 DISPLAY
debug_terminal                Command path name
debug_debugger                Command path name
debug_busyLoop                [true/false]

environment                   Variable name
environment                   Variable name = value
</SERVER>

The attributes and attribute values of the SERVER section are shown below.

Attribute Attribute value Default value Multiple Explanation
hostname Host name None Yes Server machine host name
tag Tag name None No Server tag name
port Port number 0 No The server port number
invoke_server type None No Invoke Server type
invoke_server_option option string None Yes Invoke Server option
communication_proxy type None No Communication Proxy type
communication_proxy_staging [true/false] None false Remote Communication Proxy staging enabled or not
communication_proxy_path Path None No Remote Communication Proxy path
communication_proxy_buffer_size Number of bytes 0 No Remote Communication Proxy buffer size
communication_proxy_option option string None Yes Communication Proxy option
information_source_tag Tag name None No Information Source tag
keep_connection [true/false] true No keep connection to Ninf-G Client
mpi_runNoOfCPUs Function name, Number of CPUs None Yes The number of CPUs used by MPI function
force_xdr [true/false] false No Makes XDR compulsory
jobmanager JOBMANAGER None No The job manager used on the server machine
subject Subject None No Subject
client_hostname Host name hostname of CLIENT section No Client machine host name
job_startTimeout Seconds 0 No The time-out at job startup
job_stopTimeout Seconds -1 No The time-out for when the job stops
job_maxTime Minutes None No The maximum job execution time
job_maxWallTime Minutes None No The maximum job execution wall clock time
job_maxCpuTime Minutes None No The maximum job execution cpu time
job_queue queue name None No A remote queue name
job_project project name None No A remote project name
job_hostCount Number of nodes None No Number of nodes (for SMP clusters)
job_minMemory Size None No Minimum amount of memory, in Megabytes
job_maxMemory Size None No Maximum amount of memory, in Megabytes
job_rslExtensions extension string None No RSL extensions
heartbeat Seconds 60 No The heart-beat interval
heartbeat_timeoutCount Times 5 No The heart-beat time-out times
redirect_outerr [true/false] true No Ninf-G Executable output redirect
tcp_nodelay [true/false] false No TCP_NODELAY socket option
tcp_connect_retryCount Counts 4 No The maximum number of retries for a TCP connection
tcp_connect_retryBaseInterval Seconds 1 No The base interval time for the first retry
tcp_connect_retryIncreaseRatio Ratio 2.0 No The increase ratio for calculating the maximum interval time between retries
tcp_connect_retryRandom [true/false] true No A flag that specifies whether the random value is used or not for the interval time
argument_transfer [wait/nowait/copy] wait No Returns the called function for an asynchronous function call Timing (Wait or do not wait for completion of argument transfer.)
compress [raw/zlib] raw No Compression method
compress_threshold Number of bytes 64KBytes No Threshold for performing compression
argument_blockSize Number of bytes 16KBytes No The block size of transferred arguments
workDirectory Directory name The path to the Ninf-G Executable No The working directory for Ninf-G Executable
coreDumpSize Size Undefined No Core dump size for Ninf-G Executable
commLog_enable [true/false] false No Whether the communication log output is enabled or disabled
commLog_filePath File name stderr No Communication log file name
commLog_suffix Suffix Sequence number No The communication log file suffix
commLog_nFiles Number of files 1 No The number of files for communication log output
commLog_maxFileSize Number of bytes 1M/unlimited No Maximum number of bytes for the communication log file
commLog_overwriteDirectory [true/false] false No Overwrite permission for the communication log directory
debug [true/false] false No Whether the debugging function is enabled or not
debug_display DISPLAY Environment variable No Debugging display
debug_terminal Command path name Environment variable No Path to the debugging terminal emulator
debug_debugger Command path name Environment variable No Debugger path
debug_busyLoop [true/false] false No Wait for attach from debugger or not
environment Character string None Yes Environment variable

4.3.11 SERVER_DEFAULT section

The SERVER_DEFAULT section does not allow multiple definitions. This section may be omitted.

The SERVER_DEFAULT section defines the default values for attributes which are used when attributes are omitted in the SERVER section.

The description of the SERVER_DEFAULT section is the same as the SERVER section, except that the attribute "hostname" is not described.

The SERVER_DEFAULT section may also be described in the configuration file or other such places. (*)

(*) For example, even if the SERVER_DEFAULT section is written later than the SERVER section, if attributes are omitted in the previously described SERVER section, the attributes defined in the SERVER_DEFAULT section are used.

4.4 Invoke Server setup

Ninf-G implements mechanisms for remote process invocation as a separate module called Ninf-G Invoke Server. This architecture enables to support any job submission interfaces by implementing Ninf-G Invoke Server for the interface.

Users must specify the Invoke Server for each server in Ninf-G Client Configuration file.

Here is an example of the description of <SERVER> section in the Ninf-G Client Configuration file for specifying Globus WS GRAM as a job submission interface.


<SERVER>
hostname your-host
invoke_server GT4py
</SERVER>

Invoke Server can be set and configured in the Ninf-G Client Configuration file as described above. The details of the configuration of Invoke Server are described in sections 4.3.7 and 4.3.10.

Each Invoke Server may have its own options. In order to specify such options, the following attributes are provided in the Ninf-G Client Configuration file.

Example: 

<SERVER>
hostname your-host
invoke_server GT4py
invoke_server_option "delegate_full_proxy true"
</SERVER>

Some attributes in <SERVER> section are interpreted by each Invoke Server. For example, Invoke Server GT4py interprets "port" attribute as the port number of Globus WS GRAM and Invoke Server SSH interprets "port" attribute as the port number of SSH daemon.

4.4.1 Invoke Server GT4py

Invoke Server GT4py invokes Ninf-G Executable via Globus WS GRAM.

  1. Prerequisite

    GT4 must be installed on both client and server. globusrun-ws command must be available on the client and remote server must be able to accept WS GRAM access.

    A scratch directory for the server must be prepared.

    For each server host, the scratch directory must be created in advance.

    The scratch directory is "$HOME/.globus/scratch" ($GLOBUS_SCRATCH_DIR variable in GT4 GRAM RSL) and used for transferring files. See WS GRAM System Administrator's Guide 3.5.2. Local resource manager configuration on Globus Toolkit manual.

    Please create the directory as follows:

    
% mkdir ~/.globus/scratch
% chmod 700 ~/.globus/scratch

  2. Install

    Invoke Server GT4py is automatically installed through the Ninf-G installation processes described in section 2 of this manual.

  3. Extra options

    Invoke Server GT4py accepts the following extra options.

  4. RSL extensions

    WS GRAM RSL has <extensions> tag, which enables the user to pass extra information to WS GRAM server.

    Invoke Server handles this feature by using job_rslExtensions attribute in <SERVER> section.

  5. Using staging function

    Executable staging on WS GRAM server via Invoke Server GT4py requires the following steps in advance.

    1. Invoke GridFTP servers on both server and client hosts.

      Invoke Server GT4py requires GridFTP servers on both remote and local hosts. The GridFTP server should be invoked either directly or via inetd/xinetd daemon. The port for the GridFTP server is not limited to the default port 2811.

    2. Specify the port number for client-side GridFTP server in the client configuration file.

      If the client-side GridFTP server does not use the default port (2811), the port number of the GridFTP server must be specified in client configuration file. The port number can be specified by gsiftp_port option in invoke_server_option attribute in <SERVER> section.

      
example:
<SERVER>
invoke_server GT4py
invoke_server_option "gsiftp_port 12811"
...
</SERVER>

    3. Specify subject name for authentication.

      Subject names which are used for mutual authentication between WS GRAM container and client-side GridFTP server depends on the owner of those daemons.

      If they are invoked by the system, subject name of the host certificate is used. If they are invoked by a user, subject name of the user certificate is used.

      According to the combination of the owners of the WS GRAM container and the client-side GridFTP server, some attributes need to be specified in the client configuration file.

      • Case 1: Both the WS GRAM container and the client-side GridFTP server are run by the system.

        It is not necessary to specify the subject name.

      • Case 2: The WS GRAM container is run by the system and the client-side GridFTP server is run by a user.

        The subject name of the user must be specified by staging_source_subject attribute in <SERVER> section.

        
<SERVER>
invoke_server_option "staging_source_subject /Subject/of/User"
...
</SERVER>

      • Case 3: Both the WS GRAM container and the client-side GridFTP server are run by a user.

        The subject name of the user must be specified by subject attribute in <SERVER> section.

        
<SERVER>
subject "/Subject/of/User"
...
</SERVER>

      • Case 4: The WS GRAM container is run by a user and the client-side GridFTP server is run by the system.

        The subject name of the user must be specified by subject attribute in <SERVER> section. The subject name of the client-side host must be specified by staging_source_subject attribute in <SERVER> section. The subject name of the user must be specified by staging_destination_subject and deletion_subject attributes in <SERVER> section.

        
<SERVER>
subject "/Subject/of/User"
invoke_server_option "staging_source_subject /Subject/of/ClientHost"
invoke_server_option "staging_destination_subject /Subject/of/User"
invoke_server_option "deletion_subject /Subject/of/User"
...
</SERVER>

4.4.2 Invoke Server GT2c

Invoke Server GT2c invokes the Ninf-G Executable via Globus Pre-WS GRAM.

  1. Prerequisite

    GT4 must be installed on both client and server. The server must be able to accept Pre-WS GRAM access.

  2. Install

    Invoke Server GT2c is automatically installed through the Ninf-G installation process described in section 2 of this manual.

  3. Extra options

    Invoke Server GT2c has no extra options.

4.4.3 Invoke Server SSH

Invoke Server SSH invokes Ninf-G Executable via SSH.

  1. Prerequisite

    User must be able to execute commands on the server using ssh command. In addition, it is recommended to configure user's ssh environments not to require user's input (e.g. password) for executions to avoid repetitious input while Ninf-G application is executed. "ssh-agent" and "ssh-add" commands are usually used for such purposes.

    The following commands are required by Invoke Server SSH and must be available on the server.

    /bin/sh, /bin/echo, /bin/grep, /bin/chmod, /bin/mkdir, /bin/cat, /bin/rm, /bin/kill

  2. Install

    Invoke Server SSH is automatically installed through the Ninf-G installation processes described in section 2 of this manual.

  3. Job submission system

    Like Globus GRAM, Invoke Server SSH is able to launch remote processes via a backend queuing system including SGE and PBS(*1). The backend queuing system is specified by "jobmanager" attribute in <SERVER> section in the Ninf-G Client Configuration file. The value of "jobmanager" attribute can be either "jobmanager-sge" for SGE or "jobmanager-pbs" for PBS.

    Example: 
    
<SERVER>
   hostname example.org
   invoke_server SSH
   jobmanager jobmanager-sge
      :
      :
</SERVER>

    It should be noted that although the values "jobmanager-sge" and "jobmanager-pbs" are also used for Invoke Servers for Globus GRAM (e.g. GT4py), jobmanager programs used by Invoke Server SSH are implemented by the Ninf-G development team hence they are completely different with the jobmanager programs provided by the Globus Toolkit.

    The jobmanager program assumes that user's home directory is shared between front (master) node and compute nodes.

    Invoke Server SSH uses qsub, qstat, and qdel commands in jobmanager-sge and jobmanager-pbs. Therefore, the path of these commands should be included in PATH environment variable. Otherwise, the path of these commands must be passed by options described below.

    CommandOption
    qsubssh_submitCommand
    qstatssh_statusCommand
    qdelssh_deleteCommand

    The detailed description of these options is described in section 4.4.3.4 of this manual.

    (*1) Invoke Server SSH is tested with PBS Pro and Torque.

  4. Extra options

    Invoke Server SSH accepts the following extra options.

4.4.4 Invoke Server Condor

Invoke Server Condor invokes Ninf-G Executable via Condor(*1).

*1 Condor Project: http://www.cs.wisc.edu/condor/

  1. Prerequisite

  2. Install

    Invoke Server Condor is not installed by the default Ninf-G installation and it must additionally installed manually according to the following steps.

    1. Set the NG_DIR environment variable. 

      
csh.
% setenv NG_DIR /path/to/ninf-g

sh.
$ NG_DIR=/path/to/ninf-g ; export NG_DIR

    2. Change directory to the directory of Invoke Server Condor. 

      
% cd ng-5.x.x  # expanded Ninf-G package
% cd src/InvokeServer/condor

    3. Run "make" command to compile Invoke Server Condor. 

      
% make

    4. Run "make install" command to install Invoke Server Condor. 

      
% make install

      This command copies the following files under ${NG_DIR} directory.

      ${NG_DIR}/lib/

      • classad.jar - Log analysis library for Condor Job
      • condorAPI.jar - Condor Java API Library
      • condorIS.jar - Invoke Server Condor

      ${NG_DIR}/bin/

      • ng_invoke_server.Condor - Startup script for Invoke Server Condor

  3. Extra options

    Invoke Server Condor accepts the following extra options.

  4. Information

    Invoke Server Condor automatically creates the Condor job cluster log when it invokes jobs. The name of the log file is "ninfg-invoke-server-condor-log".

  5. Limitation

4.4.5 Invoke Server NAREGISS

Invoke Server NAREGISS invokes Ninf-G Executable via NAREGI Super Scheduler.

  1. Prerequisite

    NAREGI Middleware V1.1 or later is required. Java 1.5.0 or later is required.

  2. Install

    Invoke Server NAREGISS can be installed as a part of Ninf-G installation steps. Invoke Server NAREGISS is installed if --with-naregi is specified as a Ninf-G configure script option.

    Example: 

    
% ./configure --with-naregi

    NOTE: If NAREGI Middleware is not installed in default the directory (/usr/naregi), it is necessary to specify it with configuration option "--with-naregidir".

    Details of Ninf-G configure script are described in 2.4 Configure command options.

  3. Note

    Invoke Server NAREGISS assumes that the Ninf-G Client is invoked as a job via NAREGI SS, and expects the followings.

  4. Extra options

    Invoke Server NAREGISS accepts the following extra options.

  5. Known Problems

    Invoke Server NAREGISS has some problems. Details are described in 11.5 Problems related to NAREGI SS.

4.4.6 Invoke Server SSH_Condor

Invoke Server SSH_Condor invokes Ninf-G Executables via SSH and Condor.

  1. Prerequisite

    User must be able to execute commands on the server using ssh command. In addition, it is recommended to configure user's ssh environments not to require user's input (e.g. password) for executions to avoid repetitious input while Ninf-G application is executed. "ssh-agent" and "ssh-add" commands are usually used for such purposes.

    In addition, the followings are required on the server.

    Java5 or later is required on a client host.

  2. Install

    Invoke Server Condor is not installed by default but must be installed manually. Installation steps are the follows.

  3. Options

4.5 Communication Proxy setup

Ninf-G implements several mechanisms for communication between the client and servers as a separate module called Ninf-G Communication Proxy. This architecture enables Ninf-G to support any communication methods by implementing Ninf-G Communication Proxy

If the Communication Proxy is used for the server, the attributes must be set in the configuration file.


<SERVER>
hostname your-host 
communication_proxy GT 
</SERVER>

Communication Proxy can be set and configured in the Ninf-G Client configuration file as described above. The details of the configuration of Communication Proxy are described in sections 4.3.8 and 4.3.10.

Each Communication Proxy can have its own options. In order to specify such options, the following attributes are provided in the Ninf-G Client configuration file.

4.5.1 Communication Proxy GT

Communication Proxy GT uses the Globus XIO to establish communication between Ninf-G Executables and the Ninf-G Clients.

  1. Prerequisite

    GT4 must be installed on both client and server.

  2. Install

    Communication Proxy GT is automatically installed through the Ninf-G installation processes.

  3. Extra options

    Communication Proxy GT accepts the following attribute as <CLIENT_COMMUNICATION_PROXY> section option attribute.

    Communication Proxy GT accepts the following attribute as <SERVER> section communication_proxy_option attributes.

  4. Client Relay, Remote Relay

    Client Relay and Remote Relay are introduced to enable communication between Ninf-G Client and Ninf-G Executable in a environment where direct IP connection is not possible for some reason, like firewalls..

    Client Relay and Remote Relay run on gateway hosts on firewalls, or globally accessible hosts with global IP addresses. There are 2 invocation methods for Client/Remote Relay: 1) in-advance manual invocation by the user, 2) on-demand automatic invocation by the Communication Proxy, via GSISSH.

    Client Relay and Remote Relay can be independently used. Users can just use one of them, which is actually required.

    Client/Remote Relay have following options.

  5. Limitation

4.5.2 Communication Proxy SSH

Communication Proxy SSH uses SSH to establish communication between Ninf-G Executables and Ninf-G Client.

  1. Outline of operation

    Communication Proxy SSH establishes a communication channel between client host and specified host by SSH protocol to relay communications between Ninf-G Client and Ninf-G Executables. The specified host is called "relay node".

    When Communication Proxy SSH is invoked, client host connets to "relay node" and the "relay node" listens connection requests from Ninf-G Executables. The "relay node" does not authenticate Ninf-G Executables, hence the address range from which the "relay node" accepts connection requests must be appropriately specified.

    Accepting the connection from Ninf-G Executable, Communication Proxy SSH relays the connection to Ninf-G Client via SSH tunnel.

    Note: "relay node" can be run on the same host where Ninf-G Executable runs. In this case, you can confiure Communication Proxy SSH so that the "relay node" accepts requests only from "localhost."

  2. Prerequisite

    python version 2.3 or later is required on both client host and "relay node". Please be noted that Communication Proxy SSH does not run with python 3.0 or later.

    Users must be able to execute commands on "relay node" using ssh command. In addition, it is recommended to configure user's ssh environments not to require user's input (e.g. password) for executions to avoid input while Ninf-G Client is executed.

  3. Install

    Communication Proxy SSH is automatically installed through the Ninf-G installation process when target environment has python.

  4. Extra options

    Communication Proxy SSH accepts no attributes as an option attribute in <CLIENT_COMMUNICATION_PROXY> section. Communication Proxy SSH accepts the following attributes as communication_proxy_option attributes in <SERVER> section.

4.6 Information Service setup

Ninf-G implements several mechanisms for searching and retrieving the Ninf-G Executable information as a separate module called Ninf-G Information Service. This architecture enables Ninf-G to support any information search methods by implementing Ninf-G Information Service.

To search and retrieve the Ninf-G Executable information, Information Service is used and the attributes must be set in the configuration file.


<INFORMATION_SOURCE>
type NRF 
tag nrf 
source module-name.your-host.nrf 
</INFORMATION_SOURCE>

Information Service can be set and configured in the Ninf-G Client configuration file as described above. The details of the configuration of Information Service are described in section 4.3.9.

Each Information Service can have its own options. In order to specify such options, the following attribute is provided in the Ninf-G Client configuration file.

4.6.1 Information Service NRF

Information Service NRF retrieves the Ninf-G Executable information via NRF (Ninf-G Remote information File).

  1. Prerequisite

    No prerequisite is required.

  2. Install

    Information Service NRF is automatically installed through the Ninf-G installation process.

  3. Source

    The source values specified by Ninf-G Client configuration file is interpreted as file name of the NRF file. Multiple definitions of the source attribute are allowed. The specified NRF files must be prepared on the client machine.

  4. Extra options

    Information Service NRF has no extra options.

4.6.2 Information Service MDS4

Information Service MDS4 retrieves the Ninf-G Executable information via MDS4 (Globus Toolkit WS MDS).

  1. Prerequisite

    GT4 must be installed on client and MDS4 server. MDS4 server must be able to accept WS MDS access. Providing the Ninf-G Executable information by MDS4 (WS MDS) is also needed. Java 1.5.0 or later and Ant 1.6.0 or later are required.

  2. Install

    Information Service MDS4 is not installed by the default Ninf-G installation and it must be additionally installed according to the following steps.

    1. Set the NG_DIR environment variable. 

      
csh.
% setenv NG_DIR /path/to/ninf-g

sh.
$ NG_DIR=/path/to/ninf-g ; export NG_DIR

    2. Change directory to the directory of Information Service MDS4. 

      
% cd ng-5.x.x  # expanded Ninf-G package
% cd src/InformationService/mds4/informationService

    3. Run "ant" command to compile and install Information Service MDS4. 

      
% ant

  3. Server Side registration

    On server side, the NRF file registration to the WS MDS server is required. Ninf-G information service on WS MDS publishes the informations of the NRF files on $GLOBUS_LOCATION/var/gridrpc. Thus, the NRF files generated from the IDL file must be copied to that directory.

    For example: 

    
% ng_gen sample.idl
% make -f sample.mak
(The Ninf-G Executable and the NRF file are created.)
% cp *.nrf $GLOBUS_LOCATION/var/gridrpc

    Note: $GLOBUS_LOCATION/var/gridrpc is a system shared directory like /tmp. Thus, Be careful not to conflict module name and filename of other user's.

  4. Source

    The source values specified by the Ninf-G Client configuration file are interpreted as a MDS4 (WS MDS) server URL. Multiple definitions of source attribute in one <INFORMATION_SOURCE> section are not allowed.

    Example: source https://example.org:8443/

  5. Extra options

    Information Service MDS4 accepts the following extra options.

4.7 Running the Ninf-G Client program

4.8 Creating application programs

Ninf-G supports the GridRPC API for C and Java.

In this section, the flow of an application program (written in C) for using GridRPC is described and a few typical GridRPC API functions are introduced.

Of the functions described here, those that contain *_np are not included in the GridRPC API standard (i.e., they are specific to Ninf-G).

A full list of the GridRPC APIs and a detailed explanation of each API can be found in chapter 7, "API Reference."

The functions used in the above processes are described below.

  1. Initialization

    The following function is used for initialization.

    grpc_error_t grpc_initialize(char *configFile)

    This function accepts the name of the configuration file as an argument, reads the file named by the argument, analyzes the content, and saves the values.

    If the argument value is NULL, the file specified by the NG_CONFIG_FILE environment variable is taken to be the configuration file.

    As the return value, an error status code is returned to inform of failure to read the configuration file or failure to save the values that were read.

    An example of using grpc_initialize() is given below. (In this example, the configuration file name is taken from the command line argument and that value is used as the argument.)

    
main (int argc, char *argv[]) {
       grpc_error_t result;
       char *configFile = argv[1];

       result = grpc_initialize(configFile);
       ...

  2. Creation of handles

    In GridRPC, "handles" are used when performing operations such as executing remote functions and remote methods. A handle must be created before executing a remote function or remote method, but the type of handle created differs with the type of Ninf-G Executable used.

    If only one remote function is defined for the Ninf-G Executable used, a "function handle" is used; if multiple remote methods are defined, an "object handle" is used.

    Functions for creating both kinds of handles are shown below.

    These functions accept a 'server name' and 'function or class name,' and create a handle for operating the specified Ninf-G Executable on the specified server.

    As the return value, an error code is returned to inform of failure to create the handle.

    For example, a function handle is created as follows.

    
    grpc_function_handle_t *handle;
    grpc_function_handle_init(&handle, "server.example.org", "lib/mmul");

    The following functions for creating multiple handles at one time are also provided by Ninf-G. (See Section 7 for details)

  3. Calling and synchronizing remote functions and remote methods

    The handle just created can be used to call the specified remote function or remote method on the server. When the call is made, the value of the argument defined by the Ninf-G IDL must be passed.

    The functions used for calling a function differ for a function handle and an object handle. When calling a remote method with an object handle, the name of the remote method must be specified.

    Remote functions and remote methods can be called in two ways, with a 'synchronous call' and with an 'asynchronous call.'

    The synchronous call does not return until the execution of the remote function or remote method is completed.

    The asynchronous call returns either at the beginning or at the completion of the sending of the arguments to the remote function or remote method; it then waits for the completion of the remote function or remote method to obtain the result. (The return timing of the function that makes the asynchronous call can be specified in the configuration file.)

  4. Destruction of handles

    For releasing resources, unnecessary "handles" must be destructed. The function for destructing differs with the type of "handles."

    Functions for destructing handles are shown below.

    These functions destruct the specified handle.

    As the return value, an error status code is returned to inform of failure to destruct the handle.

    If two or more handles were created at once, then the following functions for destructing multiple handles at one time must be used.

  5. Termination processing

    The following function is used to perform termination processing.

    grpc_error_t grpc_finalize()

    This function executes the processing when the Ninf-G Client is terminated.

    The return value is an error status code to inform the user when termination processing fails.

appendix

a.1 : How to use multiple user certificates

Ninf-G Client is able to use multiple user proxy certificates. Being enabled by Invoke Server, this capability is useful for using different user proxy certificates according to the security configuration (accepted CAs) of servers.

This section describes how to use multiple certificates.

a.1.1 Create a script which specifies a user proxy certificates used for user authentication by the server. It is recommended to create a script using a template provided by Ninf-G.

Copy the script from template ($NG_DIR/etc/ng_invoke_server.GTtempl).

% cp $NG_DIR/etc/ng_invoke_server.GTtempl $NG_DIR/bin/ng_invoke_server.GT4cert1 
% chmod u+x $NG_DIR/bin/ng_invoke_server.GT4cert1

Modify the copied script in which you have to specify the user proxy certificate(*1) and the script file(*2) which you will use. 

#! /bin/sh

X509_USER_PROXY=/path/to/x509up_xxxx <- (*1)
export X509_USER_PROXY
exec $NG_DIR/bin/ng_invoke_server.GT4py <- (*2)

a.1.2 Modify the client configuration file

Modify the client configuration file and specify the Invoke Server that you created at a.1.1. 

<SERVER>
    hostname  example.org
        :
    invoke_server  GT4cert1
</SERVER>

a.2 : How to implement cascading RPC

Ninf-G supports cascading RPC, which enables Ninf-G Executable to call GridRPC API. Cascading RPC is realized by (1) implementing remote functions that calls GridRPC API (server-side implementation) and (2) configuring Ninf-G client to enable delegation of full-proxy certificates (client-side configuration).

  1. Server-side implementation

    In the IDL file,


  2. Client-side configuration
last update : $Date: 2010-04-16 01:09:22 +0900 (金, 16 4月 2010) $