EnFuzion 8.0 User Manual
PrevChapter 10. Interfacing with the DispatcherNext

Command Line Interface

EnFuzion provides command line programs enfsub and enfcmd to communicate with the Dispatcher. The enfsub is primarily used to submit runs for execution. It is also able to handle user identity. The enfcmd program provides a complete set of commands to interact with the Dispatcher. Most common tasks are simplified with high level commands. A complete Dispatcher API is provided for other tasks. All enfcmd commands can be easily used in scripts.

The following sections describe enfsub and enfcmd in detail.

The enfsub Program

Enfsub has the following options: 


    enfsub  [ <options> ]  <program>  [ <program_options> ]
    enfsub  [ <options> ]  <script>  [ <script_options> ]
    enfsub  [ <options> ]  -run  <run_file>  [ <input_files> ]
enfsub is used to submit the run for execution as a command line program, a script or a parametric execution, respectively.

<options> are:

Enfsub uses the following API commands to submit a run: 


    enfcmd cluster add run name <run_name>
    enfcmd copy <run_file> root:run-<run_id>
    enfcmd copy <input_file_1> root:run-<run_id>
    ...
    enfcmd copy <input_file_n> root:run-<run_id>
    
    # the following two lines are used for parametric executions
    enfcmd run <run_id> load <run_file>
    enfcmd run <run_id> start 

    # the following line is used for command line programs and scripts
    enfcmd run <run_id> add command <options>
The last few lines depend on whether the run is a parametric study or a command line program or a script.

The examples below illustrate how the same run can be performed using a command line program, a script or a run file.

Examples of Using the Enfsub Program

This section gives an example of enfsub usage. It demonstrates the same run, but executed as a command line program, a script and a run file.

The following is the command line example for Windows: 


    enfsub.exe -n sample -a account -v VAR1=value1 \
        -i input.file=input.txt \
        -o output-$ENFJOBNAME-$ENFHOSTNAME.txt=output.file,input \
        -r -count 2 -e user@domain.com -m d \
        "copy input.file input > output.file" \
        "set >> output.file"

The following is the same command line example for Linux/Unix: 


    enfsub.exe -n sample -a account -v VAR1=value1 \
        -i input.file=input.txt \
        -o output-\$ENFJOBNAME-\$ENFHOSTNAME.txt=output.file,input \
        -r -count 2 -e user@domain.com -m d \
        "cp input.file input > output.file" \
        "set >> output.file"

The following is a Windows script that has the same effect as the command line example above: 


    @echo off
    rem ENF -i script.bat
    rem
    rem ENF -n sample -a account -v VAR1=value1
    rem ENF -i input.file=input.txt
    rem ENF -o output-$ENFJOBNAME-$ENFHOSTNAME.txt=output.file,input
    rem ENF -r -count 2 -e user@domain.com -m d

    copy input.file input > output.file
    set >> output.file
The script is submitted with: 

    enfsub.exe script.bat

The following is a Linux/Unix script that has the same effect as the command line example above: 


   #!/bin/sh
   #ENF -i script.sh
   #ENF -n sample -a account -v VAR1=value1
   #ENF -i input.file=input.txt
   #ENF -o output-$ENFJOBNAME-$ENFHOSTNAME.txt=output.file,input
   #ENF -rd -count 2 -e user@domain.com -m d
   cp input.file input > output.file
   set >> output.file
The script is submitted with: 

    enfsub ./script.sh

The following is the run file with the same results: 


    set VAR1 "value1";
    set ENFNOTIFY_EMAIL "user@domain.com";
    set ENFNOTIFY_CONDITION "done";
    task main
        copy input.txt node:input.file
        node:execute copy input.file input > output.file
        node:execute set >> output.file
        copy node:output.file output-$ENFJOBNAME-$ENFHOSTNAME.txt
        copy node:input input
    endtask
    jobs
    1
    2
    endjobs
The run is submitted as: 

    enfsub -r -run sample.run input.txt

The Enfcmd Program

Enfcmd has the following syntax: 


    enfcmd [host <hostname> <port>] [refresh <seconds>] \
        show [detailed] [ cluster | run <run_id> | node <node_name> ] |
        submit <run_file> [ <input_file_1> ... <input_file_n> ] |
        copyrun <run_id>
        copy <file_name> user[:<directory>] |
        copy <file_name> root[:<directory>] |
        identity |
        <API_command>

The host <hostname> <port> command defines the host and the port of the Dispatcher that enfcmd connects to. The command is optional. If it is not specified, the values from the submit.config file are used.

If the refresh command is specified, enfcmd repeats the requested action every <seconds> seconds.

The show command prints out information about the Dispatcher. The following options can be added to the show command:

The submit <run_file> [ <input_file_1> ... <input_file_n> ] command submits a new run for execution. It performs the following steps:

These steps are performed with the following API commands: 

    enfcmd cluster add run name <run_name>
    enfcmd copy <run_file> root:run-<run_id>
    enfcmd copy <input_file_1> root:run-<run_id>
    ...
    enfcmd copy <input_file_n> root:run-<run_id>
    enfcmd run <run_id> load <run_file>
    enfcmd run <run_id> start

The copyrun <run_id> copies files from the run directory on the EnFuzion root system to the current working directory on the local system. The run directory is preserved.

The copy <file_name> user[:<directory>] command copies file <file_name> from the EnFuzion root system to directory <directory> on the local system. If <directory> is omitted, the file is copied to the current working directory.

The copy <file_name> root[:<directory>] command copies file <file_name> from the local system to directory <directory> on the EnFuzion root system. If <directory> is omitted, the file is copied to the main Dispatcher directory.

The identity command generates a user identification file, named <user>@<host_name>.enflogin. <user> is the user account name on the submit system and <host_name> is the host name of the system. The file contains an encoded user identification string. The file can be copied to another system or user account to represent the same user.

<API_command> is used to pass API commands directly to the Dispatcher. <API_command> is an API command string.

The example below demonstrates the use of enfcmd to get all run identifiers from the Dispatcher:

Example:


    # enfcmd host localhost 3521 cluster get runs
    0237200033 0237200034

If no command is specified in the command line, the enfcmd reads the command from standard input, which is useful in scripts.

Using enfcmd in a script

The example below demonstrates how additional tasks can be specified by using the enfcmd in a shell.

Example:


    #!/bin/sh
    # parameter $1 is the port number of the Dispatcher
    # parameter $2 is the run ID to which the script adds a new task
    
    director="enfcmd host localhost $1"
    
    echo $director
    
    # Read task specification from stdin
    $director <<EOF
        run $2 add task testtask
            execute echo testtask executed on `date`
            node:execute ps -ef | grep enf > ps.$ENFJOBNAME
            node:copy node:ps.$ENFJOBNAME .
        endtask
    EOF
    
    # Add a job which executes the added task
    # and return the status
    addjob_status=`$director run $2 add job task testtask`
    
    # Print status
    echo Added task status:$addjob_status

The script accepts the Dispatcher port as the first argument and must be executed on the same host as the Dispatcher.

Handling of Privileges

Root options privileges, see details in the Section called Enforcing Privileges in Chapter 6, and protect, see details in the Section called Prevent Execution of User Programs on the EnFuzion Root System in Chapter 6, affect which actions can be performed by enfsub and enfcmd users. By default, privileges and protect are turned off, which allows any action to be performed by any user. The option noanonsubmit, see details in the Section called Rejecting Anonymous Run Submission in Chapter 6, does not affect enfsub and enfcmd, since they always provide a user ID with the job submission.

If privileges are turned on, then the following actions are permitted only by users with administrative privileges:

Enfcmd commands are not affected by the privileges option.

If protect is turned on, then the user is not allowed to specify files outside of the run directory on the root. Files names must be relative and are not allowed to start with "/", "\", "<letter>:" or contain the string "..". The following commands are affected:

Access Control

The Dispatcher offers IP-based authentication for enfsub and enfcmd access. The administrator can set a list of IP addresses that are allowed or denied to connect to the Dispatcher with enfsub and enfcmd (see the Section called Restricting Access to the Dispatcher Interface in Chapter 6 for details).

PrevHomeNext
Interfacing with the DispatcherUpApplication Programming Interface