Cluster Management System CRONO - v1.3.6
  USER MANUAL

  This document is a reference for the CRONO's users. The information here
  explains the use of the users tools, the steps necessary to compile and
  run programs and some examples for the CRONO commands.


  _________________________________________________________________________



  Table of Contents


  1. User Interface Programs
      1.0  amconf (-f option)
      1.1  cralloc (CRONO Allocate)
      1.2  crrls (CRONO Release)
      1.3  crqview (CRONO Queue View)
      1.4  crnodes (CRONO Nodes)
      1.5  crinfo (CRONO Information)
      1.6  crnmc (CRONO Node Manager Client)
      1.7  crsetdef (CRONO Set Defaults)

  2. How to compile and run programs
      2.1 crcomp and crrun
      2.2 Defining the number of processes to execute for each node
      2.3 Batch jobs
 
  3. User Pre and Post Processing
     3.1 UPREPS and Batch jobs

  4. Example of a session using the CRONO commands



  _________________________________________________________________________



  1. User Interface Programs

     These programs are provided for the users to send their requests to the
     CRONO system. Each one has specific parameters. The requests are sent to
     the Access Manager, which evaluates each request, looks for access rights,
     checks the user command parameters and so on. The last program (crsetdef)
     was designed to make easier the utilization of the other user programs.

  
  1.0 amconf (-f option) (The administrator should take care about this file)

     Most commands described here uses the '-f' option. This option is used for
     the User Interface programs to know where is the file that defines the
     hostname and port for the Access Manager. The name of this file is amconf.
     Omitting the '-f' option, the User Interface programs will get the file
     specified at the CRONO's compilation time (so the administrator takes care
     about this).
     An example of the amconf file is:
     #################################################################
     # <hostname> <port>
     servername 7001
     #################################################################
     
     Probably the administrator has configured this file for the users,
     so if you're not the administrator don't worry about this file.


  1.1 cralloc (CRONO Allocate)

     Use this program to allocate nodes in a cluster. The parameters are the
     number of nodes, the time for allocation, the cluster name and the
     configuration file.

     Usage:
     As soon as possible:
        cralloc -c <cluster> -n <nodes> -t <time> [-s|-e] [ -b <bjscript> ]
          [ -f <file> ]

     At a given time:
        cralloc -c <cluster> -n <nodes> -it <itime> [ -t <time> | -ft <ftime> ]
          [-s|-e] [ -b <bjscript> ] [ -u <user> ] [ -f <file> ]

       cralloc --help

        -c <cluster>            : Cluster name
        -n <nodes>              : Number of nodes or
                                  a file to make qualitative allocation
        -t <time>               : Time of allocation in minutes
        -s                      : Shared access
        -e                      : Exclusive access
        -b <bjscript>           : Batch job script
        -it <itime>             : Initial Time (HH:MM[-dd[/mm[/yyyy]]])
        -ft <ftime>             : Final Time (HH:MM[-dd[/mm[/yyyy]]])
        -u <user>               : User Name (option only for root)
        -f <file>               : Configuration file
        --help                  : Display this help and exit

     Examples: cralloc -c cluster1 -n 3 -t 15 -e             (Interactive mode)
               cralloc -c cluster1 -n 3 -t 15 -e -b prog1.sh (Batch job mode)

               cralloc -c cluster1 -n 3 -it 20:00 -ft 20:15 -e (At a given time)
               cralloc -c cluster1 -n 3 -it 20:00 -t 2 -e (At a given time)

     If you want to make a qualitative allocation, that is, you want to
     choose the node types, you must create a file with the following syntax:
     <node type>:<number of nodes>
     <node type>:<number of nodes>
       ....

     For example:
     p3-550:4
     p4-2000:2

     And, use this file as the argument for -n option.
     Another option is specifying the node types without a file.
     For example:
       cralloc -n p3-550:2
          or
       cralloc -n "p3-550:4 p4-2000:2"

     Note that if you have more than one node type specify them within double 
     commas ("...").

     In order to discover the available node types, use the crinfo command.

     Important advise:
     If the crsetdef was used to set the "bjscript" parameter and
     a user wants to allocate the resources in interactive mode, the
     "bjscript" must be cleared (crsetdef -d bjscript).


  1.2 crrls (CRONO Release)

     This program allows to release nodes allocated by cralloc. Using this
     program, your nodes will be released and all your process executing will be
     finalized (if you have resources) or cancel a request (if you don't have
     resources).

     Usage: crrls -c <cluster> [ -rid <rid> ] [ -u <user> ] [ -f <file> ] 
       crrls --help

        -c <cluster>            : Cluster name
        -rid <rid>              : Request id (cancel a reserve)
        -u <user>               : User Name (option only for root)
        -f <file>               : Configuration file
        --help                  : Display this help and exit

     Example: crrls -c cluster1
              crrls -c cluster1 -rid 2

  1.3 crqview (CRONO Queue View)

     This program shows information about the requests queue, like user names,
     start and finish times of the users, the number of available nodes and the
     allocation type (exclusive or shared).

     Usage: crqview -c <cluster> [ -t ] [ -f <file> ]
             -c <cluster>            : Cluster name
             -t                      : Show node types information
             -f <file>               : Configuration file

     Example: crqview -c cluster1
              crqview -c cluster1 -t
     


  1.4 crnodes (CRONO Nodes)

     This program can be used to show the hostname of each node allocated by the
     cralloc command. Using the -s option, it is possible to show some
     additional information about the nodes. This command now has a flag (-w)
     which is used to show all the cluster nodes and who is using each of them.

     Usage: crnodes -c <cluster> [ -s "<sel> <sel> ... <sel>" ] [ -f <file> ]
     crnodes --help
     
        -c <cluster>            : Cluster name
        -s <sel>...             : Select nodes information
                                  (sel='nprocs','type','arch','desc' or 'all')
        -w                      : Show all cluster nodes and who is using
                                  each of them
        -f <file>               : Configuration file
        --help                  : Display this help and exit
 
     Example: crnodes -c cluster1
              crnodes -c cluster1 -s all
              crnodes -c cluster1 -s "type arch"
              crnodes -c cluster1 -w 
                                                                       

  1.5 crinfo (CRONO Information)

     Using this program, you can view information about the managed clusters.
     This information are access rights for allocations, cluster name, number of
     nodes, special periods and others.

     Usage: crinfo [ -c <cluster> || -all ] [ -f <file> ]

          -c <cluster> : Cluster name
          -all         : Show information about all clusters available (default)
          -f <file>    : Configuration file


     Examples: crinfo -c tropical
               crinfo -all

  1.6 crnmc (CRONO Node Manager Client)

     This program allows you to execute operation directly on the nodes
     allocated.
     The available operations are created by the Administrator and you can
     obtain them using the -v option.

     Usage: crnmc -c <cluster> -v [-f <file>] | -c <cluster> <-all> |
               -n <node1> <node2> ... > -op <operation> [-f <file>] | -mf <mach>

             -c <cluster>            : Cluster name
             -all                    : All allowed nodes
             -mf                     : Machine file
             -n                      : Nodes
             -op <operation>         : Operation to execute
             -v                      : View operations
             -f <file>               : Configuration file

     Example:
         crnmc -c cluster1 -all -op killp   #Kill processes of all allowed notes
                                             of a user
         crnmc -c cluster1 -n cluster1_01   #Kill processes just on cluster1_01
                                             node

  1.7 crsetdef (CRONO Set Defaults)

     The missing parameters (<cluster>,<time>,<nodes>,<share>,<bjscript>,
     <mpicomp>, <mpirun>, <arch>) of the above commands will be filled out using
     the default file.
     This program was made to allow you easily to modify the default
     configuration file ($HOME/.crono/defaults) without needing to edit it by
     hand.
     Its functions are:
          - show one or all keywords of the default configuration file.
          - set a new value for an existing keyword.
          - add or remove an entry in file.
          - create your personal definitions for specific use.

     Usage: crsetdef [ <keyword> [ <value> ] ] | -d <keyword> | --help
             <keyword>         : Shows the keyword from defaults file
             <keyword> <value> : If keyword exists, set a new value. If not,
                                 add a new entry in file
             -d <keyword>      : Remove the line that contains keyword

     In the usage, keyword and value mean:
           <keyword> is a string that contains a value associated.
           <value> is the value for a keyword specified.

     Examples: Assuming a typical default configuration file below:

           To show the definitions
           $ crsetdef
           CRONO definitions
           ===== ===========
           cluster=tropical
           time=15
           nodes=3
           shared=n
           bjscript=<empty>
           mpicomp=mpiethercc
           mpirun=mpiether


           To show an entry from file:
           $ crsetdef cluster

           To modify the value for the "time" keyword, type:
           $ crsetdef time 20

           To add an entry to the file, type:
           $ crsetdef something somevalue

           To remove an entry, type:
           $ crsetdef -d tmppath

     Please use this program to modify the defaults configuration file. If you
     decide to edit the file by hand, feel free. But in this case, take care with
     the correct sintax in each line, that must be <keyword>=<value> without the
     "<" and ">" signals.
     The keywords also must be in the start of each line.


  _________________________________________________________________________

  2. How to Compile and Run Programs
   
  2.1 crcomp and crrun

  There are two wrapper scripts to help users to compile and run programs:
  crcomp and crrun. The first one is useful in environments which have more
  than one Mpi.
  So the Administrator defines, for example, the Mpi directories and you can
  choose one of the Mpi versions available. The second one is used to run
  programs. In this second script you have to specify the environment, the
  cluster, and optionality the architecture which will be used to run the
  programs.
  Below are just examples of the usage of these scripts.

  To compile: crcomp (CRONO Compiler)

  The user can specify if he/she wants an executable for a specific
  architecture or not. For this procedure the user can provide use the
  flag "-arch <arch_name>". Possible values for this flag are defined by the
  administrator. When the user doesn't specify this flag, it will be generated
  two executables for all the available architectures. In this case, one will
  add extension in the executable with the architecture names.
      
   Usage: crcomp -env <mpicomp> [ -arch <arch> ] [options]

   If -arch is not specified, one will compile for both architectures
  
   Ex1.: crcomp -env mpiethercc hello.c -o hello
   Ex2.: crcomp -env mpiethercc -arch ia64 hello.c -o hello


  To run: crrun (CRONO Runner)

  Usage: crrun -c <cluster> -env <mpirun> [-arch <arch> ] [options]
        
   If -arch is not specified, one will run on available architectures
        
   Ex1.: crrun -c amazonia -env mpiether -arch ia32 -np 8 hello
   Ex2.: crrun -c amazonia -env mpigm -np 16 multiply 20 30

  If the user has nodes of more than one architecture, crrun will look for the
  extensions of all architecture names (like ".ia32" and ".ia64").
  If the user doesn't want to use extensions, he/she can use the %a symbol,
  for example /home/stelmar/%a/myprog.

  When the user time starts, CRONO can create the machine files for all
  execution environments. Therefore the "-machinefile" parameter will not
  be used.
  To simplify the command line the user will pass just one "-np" and the
  crrun command will create more than one "-np" (if necessary).

  For example, suppose two machine files:
  - IA64 machines:
       amazonia01
       amazonia02

 - IA32 machines:
       amazonia03
       amazonia04
       amazonia05

  When the user gives "-np 3" crrun will create "-np 2" and "-np 1".
  When the user gives "-np 5" crrun will create "-np 2" and "-np 3".
  When the user gives "-np 7" crrun will create "-np 4" and "-np 3".
  When the user gives "-np 9" crrun will create "-np 4" and "-np 5".
  And so on.

  Note  that the "best" machines will be used before the others.
  In our case, the IA64 will be used before the iA32.

  The machine files are stored in:
     $HOME/.crono/machfile.<cluster>.<arch>.<environment>

  2.2 Defining the number of processes to execute for each node

    The administrator defines the number of processes that will be executed
  on each node (regarding the node type). Using the crinfo command you can
  view the definitions (nprocs variable).

  If you want to modify the default values you can create a file
  $HOME/.crono/nodetypes with following syntax:
  <nodetype>=<nprocs>
  <nodetype>=<nprocs>
    . . .

     Example:
               p3=4
               p4=8

  So, when your time starts, and the machine files are created, your values
  are considered.


  2.3 Batch jobs

  Batch jobs is a mechanism to submit user jobs automatically when the
  requested time starts. The resources will be released when the job or the
  user time finishes. There are some variables available to make the scripts:
     - CR_CLUSTER   = cluster name
     - CR_USERID    = user id
     - CR_USERNAME  = user name
     - CR_NODES     = list of user nodes (e.g. : "tropical01 tropical02")
     - CR_NODESINFO  = list of user nodes with additional information
          Format: (for each node)
             <hostname>:<nodetype>:<architecture>:
             <number of processes>:"<description>"<space>
     - CR_RID      = request id

  Example of a batch job script:

  #!/bin/sh
  #
  # Multiply matrix
  #########################################################################
  /usr/local/bin/crrun -c $CR_CLUSTER -np 16 mult_matrix
  /usr/local/bin/crrun -c $CR_CLUSTER -np 16 mult_matrix
  rm $HOME/tmp/*
  ########################################################################  

  An example of how to allocate the nodes using batch jobs:
  
  $ cralloc -c tropical -n 16 -t 15 -b mult_matrix.sh

  The batch job file can be a binary or a script file.
  _________________________________________________________________________

  3. User Pre and Post Processing

     The User Pre Processing Script and Post Processing Script are files used
     to execute tasks when the user time starts and when the user time finishes.
  
     The path of these files are:
       $HOME/.crono/<cluster>.upreps  (Pre Processing)
       $HOME/.crono/<cluster>.upostps (Post Processing)

     When the user time starts, the tasks in the script of Pre Processing
     can be executed until the user time finishes.
     There are some variables available to make the scripts:
         - CR_CLUSTER    = cluster name
         - CR_USERID     = user id
         - CR_USERNAME   = user name
         - CR_NODES      = list of user nodes (e.g. : "tropical01 tropical02")
         - CR_NODESINFO  = list of user nodes with additional information
              Format: (for each node)
                 <hostname>:<nodetype>:<architecture>:
                 <number of processes>:"<description>"<space>
         - CR_RID       = request id

      The upreps and upostps can be either scripts or programs.

  3.1 UPREPS and Batch jobs

     -  Both of them use a script that is executed when the user time starts.
     -  You can use the UPREPS and Batch Jobs together.
     -  When the execution of a batch jobs script finishes the user time
        also finishes.
     -  When the execution of a UPREPS finishes the user time doesn't finish.
        For example, if a user requested 5 minutes and the UPREPS is executed 
        in 1 minute, the user still has 4 minutes (in interactive mode).

  _________________________________________________________________________


  4. Example of a session using the CRONO commands 


  1) Let's start using the crsetdef command to setup the some values of the
     unspecified parameters:

     $ crsetdef cluster cluster1
     $ crsetdef time 15
     $ crsetdef nodes 14
     $ crsetdef mpirun mpiether
     $ crsetdef mpicomp mpiethercc
     $ crsetdef arch ia32

  2) To view who is using the cluster cluster1 type:
     $ crqview

  3) You can view the users of another cluster, for example:
     $ crqview -c cluster2

  4) To get some resources use the cralloc command:
     $ cralloc
  
  5) If you want for example sixteen nodes type:
     $ cralloc -n 16
     Or
     $ crsetdef nodes 16
     $ cralloc

  6) To compile a hello.c program using the mpi ethernet use the crcomp script:
     $ crcomp hello.c -o hello
     You can execute
     $ crcomp -env mpiethercc hello.c -o hello
 
     But the -env options is not necessary because the crsetdef was used to
     define the mpicomp.
   
  7) To run the hello using twelve processes you can use the crrun script:
     $ crrun hello -np 12


  _________________________________________________________________________