Changes between Version 1 and Version 2 of startstop_unix


Ignore:
Timestamp:
11/15/11 17:46:28 (10 years ago)
Author:
branden
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • startstop_unix

    v1 v2  
    77 
    88== Details == 
     9Startstop is a system-specific module; the configuration file described here is for the Linux version. On startup, startstop changes to the directory specified by the EW_PARAMS environment variable. Then it reads the configuration file named startstop_unix.d. This file sets up all parameters required to run an Earthworm system. In the configuration file, lines may begin with a valid startstop command (listed below) or with a # to denote a comment. Command names must be typed in the configuration file exactly as shown in this document (upper/lower case matters!). 
     10 
     11=== Example startstop_unix.d Configuration File ===  
     12{{{ 
     13# 
     14#       Startstop (Linux Version) Configuration File 
     15# 
     16#    <nRing> is the number of transport rings to create. 
     17#    <Ring> specifies the name of a ring followed by it's size 
     18#    in kilobytes, eg        Ring    WAVE_RING 1024 
     19#    The maximum size of a ring is 1024 kilobytes. 
     20#    Ring names are listed in file earthworm.h. 
     21# 
     22 nRing               3 
     23 Ring   WAVE_RING 1024 
     24 Ring   PICK_RING 1024 
     25 Ring   HYPO_RING 1024 
     26# 
     27 MyModuleId    MOD_STARTSTOP  # Module Id for this program 
     28 HeartbeatInt  50             # Heartbeat interval in seconds 
     29 MyClassName   TS             # For this program 
     30 MyPriority     0             # For this program 
     31 LogFile        1             # 1=write a log file to disk, 0=don't 
     32 KillDelay      5             # seconds to wait before killing modules on 
     33                              #  shutdown 
     34 HardKillDelay  5             # seconds to wait after SIGKILL 
     35                              #   if absert, no SIGKILL is sent 
     36# maxStatusLineLen 120         # Uncomment to specify length of lines in status 
     37 Stderr         None          # Where to send stderr messages: None, Console or File 
     38# 
     39#    Class must be RT or TS 
     40#    RT priorities from 0 to 59 
     41#    TS priorities le 0 
     42# 
     43#    If the command string required to start a process contains 
     44#    embedded blanks, it must be enclosed in double-quotes. 
     45#    Processes may be disabled by commenting them out. 
     46#    To comment out a line, preceed the line by #. 
     47#    The optional Agent command lists the user and group names under which 
     48#       the command will be run. Make sure they are valid names! 
     49#       You cannot use "root" as the Agent user. If an earthworm module 
     50#       needs to run as root, you should make that module's binary setuid root. 
     51# 
     52 Process          "pick_ew pick_ew.d" 
     53 Class/Priority    TS 0 
     54 Agent             "eworm" "net" 
     55# 
     56# Process          "coaxtoring coaxtoring.d" 
     57# Class/Priority    RT 10 
     58# 
     59# Process          "export_generic export_picks.d" 
     60# Class/Priority    TS 0 
     61# 
     62 Process          "binder_ew binder_ew.d" 
     63 Class/Priority    TS 0 
     64 Stderr            File 
     65# 
     66# 
     67 Process          "eqproc eqproc.d" 
     68 Class/Priority    TS 0 
     69 Stderr            Console 
     70# 
     71 Process          "diskmgr diskmgr.d" 
     72 Class/Priority    TS 0 
     73# 
     74 Process          "pagerfeeder pagerfeeder.d" 
     75 Class/Priority    TS 0 
     76# 
     77 Process          "statmgr statmgr.d" 
     78 Class/Priority    TS 0 
     79# 
     80# Process          "eqalarm_ew eqalarm_ew.d" 
     81# Class/Priority    TS 0 
     82# 
     83 Process          "copystatus WAVE_RING HYPO_RING" 
     84 Class/Priority    RT 5 
     85# 
     86 Process          "copystatus PICK_RING HYPO_RING" 
     87 Class/Priority    RT 5 
     88# 
     89 Process          "menlo_report menlo_report.d" 
     90 Class/Priority    TS 0 
     91# 
     92}}} 
     93 
     94=== Functional Commands === 
     95Unlike most other Earthworm modules, startstop expects the lines in its control file to be in a certain order. Below are the commands recognized by startstop, grouped by the function they influence and listed in the order in which they must appear in the control file. All commands are required! 
     96 
     97==== Shared memory setup ==== 
     98{{{ 
     99nRing                   required 
     100Ring                    required (nRing) 
     101}}} 
     102 
     103===== nRing ===== 
     104nRing [nRing] 
     105 
     106Specifies the number of shared memory regions (aka transport rings) that startstop will create for "public" use by the modules of this Earthworm system. nRing should be an integer from 1 to MAX_RING (currently defined to be 50). 
     107 
     108Example:  nRing 3 
     109 
     110===== Ring ===== 
     111Ring [name size] 
     112 
     113Specifies the name and size, in kilobytes, of one transport ring. There must be exactly nRing "Ring" commands following the "nRing" command in the startstop_unix.d. name is a character string (up to 19 characters long, valid strings are listed in earthworm.d) that relates (in earthworm.d) to a unique number for the key to the shared memory region. size should be an integer between 1 and 1024 (the default maximum size). When deciding how large to make a memory region, realize that the transport layer uses a portion of the memory region for its own bookkeeping. The region size is NOT required to be an even multiple of the size of the messages it will contain. However, suppose you want the region to be exactly large enough to store NUM messages of size MSGSIZE. To include space for transport bookkeeping too, the region size (in bytes) should be: 
     114sizeof(SHM_HEAD) + NUM * ( sizeof(TPORT_HEAD) + MSGSIZE ) 
     115 
     116where SHM_HEAD and TPORT_HEAD are structures defined in transport.h. Startstop places all of its outgoing messages in the memory region specified by the first "Ring" command. 
     117 
     118Example:  Ring  WAVE_RING 1024 
     119 
     120==== Startstop-specific info ==== 
     121{{{ 
     122MyModuleId              required 
     123HeartbeatInt            required 
     124MyClassName             required 
     125MyPriority              required 
     126LogFile                 required 
     127KillDelay               required 
     128HardKillDelay           optional 
     129maxStatusLineLen        optional 
     130Stderr                  optional 
     131}}} 
     132 
     133===== !MyModuleId ===== 
     134!MyModuleId [mod_id] 
     135 
     136Sets the module id for labeling all outgoing messages. mod_id is a character string (up to 30 characters, valid strings listed in earthworm.d) that relates (in earthworm.d) to a unique single-byte number. Startstop places its outgoing messages on the shared memory ring specified by the first "Ring" command in startstop_sol.d. 
     137 
     138Example:  !MyModuleId MOD_STARTSTOP 
     139 
     140===== !HeartbeatInt ===== 
     141!HeartbeatInt [nsec] 
     142 
     143Defines the number of seconds, nsec, between TYPE_HEARTBEAT messages issued by startstop. Startstop places its heartbeats on the shared memory ring specified by the first "Ring" command in startstop_unix.d. 
     144 
     145Example:  !HeartbeatInt 30 
     146 
     147===== !MyClassName ===== 
     148!MyClassName [class] 
     149 
     150Sets the process class for startstop. class is a character string that must be set to either "RT" (for Real-Time) or "TS" (for Time- Share) on solaris. 
     151 
     152Example:  !MyClassName RT 
     153 
     154===== !MyPriority ===== 
     155!MyPriority priority 
     156 
     157Sets the process priority for startstop. See the "!Class/Priority" command below for allowed values. After startstop reads its configuration file, it changes its own class/priority to the values specified in the "!MyClassName" and "!MyPriority" commands. 
     158 
     159Example:  !MyPriority 4 
     160 
     161===== !LogFile  ===== 
     162!LogFile [switch] 
     163 
     164Sets the on-off switch for writing a log file to disk. If switch is 0, no log file will be written. If switch is 1, startstop will write a daily log file(s) called cfname_yyyymmdd.log where cfname is the name (without extension) of startstop's configuration file (ex: startstop_unix) and yyyymmdd is the current UTC date (ex: 19960123) on the system clock. The file(s) will be written in the EW_LOG directory (environment variable). 
     165 
     166Example:  !LogFile 1 
     167 
     168===== !KillDelay ===== 
     169!KillDelay [nsec] 
     170 
     171Gives the number of seconds nsec that startstop will wait for modules to shutdown gracefully on termination. After this delay, startstop will force modules to shut down with the TERM signal. If module still does not stop after nsec seconds, behavior is determined by the "!HardKillDelay" command. 
     172 
     173Example:  !KillDelay 10 
     174 
     175===== !HardKillDelay ===== 
     176!HardKillDelay [nsec] 
     177 
     178Optional specification of number of seconds nsec that startstop will wait for modules to shutdown after being sent a KILL signal before aborting a restart of the module. If not specified, no KILL signal is issued, and any restart is aborted after sequence described in the "!KillDelay" command. 
     179 
     180Example:  !HardKillDelay 10 
     181 
     182===== !maxStatusLineLen ===== 
     183!maxStatusLineLen [nchars] 
     184 
     185Optional specification of maximum length of a line when printing status to nchars characters; default is 80, and new value cannot be smaller. When specified, status will adjust column widths to minimize truncation of information. 
     186 
     187Example:  !maxStatusLineLen 120 
     188 
     189===== Stderr ===== 
     190Stderr [target] 
     191 
     192Optional specification of what to do with messages printed to stderr; target can be either "Console" (the screen, the default), "None" (messages are eliminated), or "File" (messages get written to a file in the Log directory, named as the log file for this module would be but with the extension .err). When specified for startstop itself, it is the default for all modules (save startstop); when specified for a specific module, it overrides the specification for all modules. In the example configuration, every module's stderr messages are surpressed except for eqproc (whose go to the screen) and binder_ew (whose go to a file). 
     193 
     194Example:  Stderr File 
     195 
     196==== Earthworm modules to run ==== 
     197{{{ 
     198Process                 required \ 
     199Class/Priority          required  |  one set 
     200Stderr                  optional  | per module 
     201Agent                   optional / 
     202}}} 
     203 
     204===== Process ===== 
     205Process [cmdstring] 
     206 
     207Gives the command string, cmdstring, (up to 79 characters) that will be used to start one Earthworm module. Each "Process" command must be immediately followed by a "!Class/Priority" command. If the cmdstring required to start a process contains embedded blanks, it must be enclosed in double-quotes. Startstop can create up to MAX_CHILD (currently defined as 200) child processes. 
     208 
     209Example:  Process "binder_ew binder_ew.d" 
     210 
     211===== !Class/Priority ===== 
     212!Class/Priority [class priority] 
     213 
     214Specifies the class and priority under which the module given by the previous "Process" command will be run. class is a 2-character string and priority is an integer; their values are restricted to: 
     215                      class     priority 
     216        Real-Time     "RT"      0 to 59 
     217        Time-Share    "TS"       <= 0 
     218Class RT processes run at higher priority than class TS processes. Take care not to assign known CPU hogs (binder_ew, for example) to the RT class. Such an assignment could bog down all class TS processes, causing poor Earthworm system performance. After a "!Class/Priority" line, startstop expects to find the "Process" command of the next Earthworm module it should spawn. 
     219 
     220Example:  !Class/Priority  TS  0 
     221 
     222===== Stderr ===== 
     223Stderr [target] 
     224 
     225Optional specification of what to do with messages printed to stderr; target can be either "Console" (the screen, the default), "None" (messages are eliminated), or "File" (messages get written to a file in the Log directory, named as the log file for this module would be but with the extension .err). When specified for startstop itself, it is the default for all modules (save startstop); when specified for a specific module, it overrides the specification for all modules. In the example configuration, every module's stderr messages are surpressed except for eqproc (whose go to the screen) and binder_ew (whose go to a file). 
     226 
     227Example:  Stderr File 
     228 
     229===== Agent ===== 
     230Agent [user group] 
     231 
     232Optional command to specify the user and group names under which this module will run. Normally this feature will not be used. But if you need to have the output and log files from this module owned by a user other than the one who runs startstop, then you can use Agent to do this. You cannot specify root as the user agent. If you need to have a module run with root privelege, you should set that module's file permissions to make it setuid root. Make sure that user is a valid user name and group is a valid group name for your system. 
     233 
     234Example:  Agent "eworm" "net" 
    9235 
    10236== Helpful Hints ==