Changes between Version 19 and Version 20 of Installation_and_Configuration


Ignore:
Timestamp:
11/16/11 15:33:06 (10 years ago)
Author:
branden
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Installation_and_Configuration

    v19 v20  
    174174== 6. Load the Earthworm Software == 
    175175 
    176 The Earthworm Directory Structure: 
     176=== Earthworm Directory Structure === 
    177177 
    178178 
     
    208208  
    209209 
    210 Loading the Software: 
    211  
    212 * Create the root directory for Earthworm (e.g. c:\earthworm). Bring the current Earthworm release from [wiki:Downloads Downloads] into this directory, and unpack it there. 
    213  
    214 * Note that the executable binaries are in separate directories of the ftp site. The appropriate version of the executables should be placed in the \bin directory (e.g. c:\earthworm\v#.#\bin). 
    215  
    216 * Note that the "src" (\earthworm\v#.#\src) directory of the release contains a subdirectory for each module. Each such directory contains the source and make files, as well as example error processing configuration files (*.desc) and parameter files (*.d).  
     210=== Loading the Software === 
     211 
     212 * Create the root directory for Earthworm (e.g. c:\earthworm). Bring the current Earthworm release from [wiki:Downloads Downloads] into this directory, and unpack it there. 
     213 
     214 * Note that the executable binaries are in separate directories of the ftp site. The appropriate version of the executables should be placed in the \bin directory (e.g. c:\earthworm\v#.#\bin). 
     215 
     216 * Note that the "src" (\earthworm\v#.#\src) directory of the release contains a subdirectory for each module. Each such directory contains the source and make files, as well as example error processing configuration files (*.desc) and parameter files (*.d).  
    217217   
    218218  
     
    222222It is recommended that each node have the same directory structure. This is not required, but has been found useful in simplifying maintenance and updates. 
    223223 
    224 * Under the \earthworm root directory, create a 'run' directory for each node. (ie., c:\earthworm\run_central, c:\earthworm\run_remote1, c:\earthworm\run_remote2 etc) 
    225  
    226 * Under each such run directory create a \log and a \params directory. The \log directory will contain all log files witten by modules in this node. The \params directory will contain all configuration files (.d and .desc) neccessary to run this node. 
    227  
    228 * Copy three files from the release the each of the \parms directories. These are [wiki:earthworm_global earthworm_global].d, [wiki:earthworm earthworm].d, and "ew_nt.cmd" (or "ew_sol_sparc.cmd", or "ew_sol_intel.cmd", depending on the platform). These files are located in the Earthworm release in the \environment directory.  
     224 * Under the \earthworm root directory, create a 'run' directory for each node. (i.e., c:\earthworm\run_central, c:\earthworm\run_remote1, c:\earthworm\run_remote2 etc) 
     225 
     226 * Under each such run directory create a \log and a \params directory. The \log directory will contain all log files witten by modules in this node. The \params directory will contain all configuration files (.d and .desc) neccessary to run this node. 
     227 
     228 * Copy three files from the release the each of the \parms directories. These are [wiki:earthworm_global earthworm_global].d, [wiki:earthworm earthworm].d, and "ew_nt.cmd" (or "ew_sol_sparc.cmd", or "ew_sol_intel.cmd", depending on the platform). These files are located in the Earthworm release in the \environment directory.  
    229229   
    230230  
     
    232232== 8. Configure the Earthworm Environment Files == 
    233233 
    234 * The [wiki:earthworm_global earthworm_global].d file should contain your Installation Id. Contact Mitch Withers at [http://www.ceri.memphis.edu/index.shtml CERI] (Center for Earthquake Research and Information, University of Memphis, USA), who acts as control for this file. Local editing of this file is possible, but will prevent the installation form exchanging data with other sites. 
    235  
    236 * Edit [wiki:earthworm earthworm].d: Using your Earthworm software diagram, enter a definition for each each mesasage Ring Name and Module ID at each node. At this point, do not alter the Message Types found there, but use the default entries. 
    237  
    238 * Create a .cmd file for each node. This file contains the environment variables used by the Earthworm system. As mentioned above, these files are platform specific, and currently three versions exist: for Windows 2000 and NT: "ew_nt.cmd", for Solaris on Sparc: "ew_sol_sparc.cmd", and for Solaris on Intel: "ew_sol_intel.cmd". (OS/2 has sadly been dropped). Thus, for example, one would create files such as "ew_sol_sparc_central.cmd", "ew_nt_remote1.cmd", and "ew_nt_remote2.cmd". 
     234 * The [wiki:earthworm_global earthworm_global].d file should contain your Installation Id. Contact Mitch Withers at [http://www.ceri.memphis.edu/index.shtml CERI] (Center for Earthquake Research and Information, University of Memphis, USA), who acts as control for this file. Local editing of this file is possible, but will prevent the installation form exchanging data with other sites. 
     235 
     236 * Edit [wiki:earthworm earthworm].d: Using your Earthworm software diagram, enter a definition for each each mesasage Ring Name and Module ID at each node. At this point, do not alter the Message Types found there, but use the default entries. 
     237 
     238 * Create a .cmd file for each node. This file contains the environment variables used by the Earthworm system. As mentioned above, these files are platform specific, and currently three versions exist: for Windows 2000 and NT: "ew_nt.cmd", for Solaris on Sparc: "ew_sol_sparc.cmd", and for Solaris on Intel: "ew_sol_intel.cmd". (OS/2 has sadly been dropped). Thus, for example, one would create files such as "ew_sol_sparc_central.cmd", "ew_nt_remote1.cmd", and "ew_nt_remote2.cmd". 
    239239 
    240240In each file, edit the definitions for EW_INSTALLATION, EW_HOME, EW_VERSION, EW_PARAMS and EW_LOG. The remainder of the file requires no change: 
     
    256256For each module within a node you will need to create a parameter (.d) and an error processing file (.desc). Samples of these files are in the source directory for each module (e.g. c:\earthworm\v#.#\src). 
    257257 
    258 To configure a module, first create the invocation paragraph for the module in [wiki:startstop_nt startstop_nt].d (see below). Then copy the sample .d and .desc files from that module's source directory. Change the names to match the name of the Module Id. Edit the files to suit the configuration. At a minimum this involves changing the name of the Module Id (this is where the executable learns its Module Id), Installation Id (in the .desc file) and possibly the ring names. Change any other parameters to suit the configuration. 
     258To configure a module, first create the invocation paragraph for the module in [wiki:startstop_nt startstop_nt].d, [wiki:startstop_sol startstop_sol].d, or[wiki:startstop_unix startstop_unix].d (see below). Then copy the sample .d and .desc files from that module's source directory. Change the names to match the name of the Module Id. Edit the files to suit the configuration. At a minimum this involves changing the name of the Module Id (this is where the executable learns its Module Id), Installation Id (in the .desc file) and possibly the ring names. Change any other parameters to suit the configuration. 
    259259 
    260260[wiki:startstop startstop] and [wiki:statmgr statmgr] are required to run in all nodes an an Earthworm system. Since the [wiki:startstop startstop] and [wiki:statmgr statmgr] module's parameter and error processing files contain settings that control and effect the overall node it is advised to first configure these modules. [wiki:startstop startstop] is the module which starts first, and brings up the system by creating the specified rings and starting each module. [wiki:statmgr statmgr] is responsible for processing error messages created by other modules, monitoring their heartbeats, and issuing restart requests when a module's heartbeat ceases (see below). 
    261261 
    262 === 9.1 [wiki:startstop startstop] === 
    263  
    264 This module is system-specific. Therefore, there are system-specific configuration files (startstop_nt.d and startstop_sol.d) It's configuration file contains the substance of the Earthworm configuration diagram (Sect.4). It first lists the rings required for this construction, and then lists a paragraph for each module to be started. This paragraph lists the name of the module's executable, the configuration file it is to read when starting, the priority it is to run at, and (in the Windows 2000 case) whether the module is to have its own window. 
    265  
    266 === 9.2 [wiki:statmgr statmgr] === 
     262=== [wiki:startstop startstop] === 
     263 
     264This module is system-specific. Therefore, there are system-specific configuration files ([wiki:startstop_nt startstop_nt].d, [wiki:startstop_sol startstop_sol].d and [wiki:startstop_unix startstop_unix].d) It's configuration file contains the substance of the Earthworm configuration diagram. It first lists the rings required for this construction, and then lists a paragraph for each module to be started. This paragraph lists the name of the module's executable, the configuration file it is to read when starting, the priority it is to run at, and (in the Windows 2000 case) whether the module is to have its own window. 
     265 
     266=== [wiki:statmgr statmgr] === 
    267267 
    268268This module's configuration file ([wiki:statmgr statmgr].d) lists the error processing files (.desc) of all modules which it is to keep track of. Here are listed the procedures to be followed for the various error types which a client module may issue (email, page, etc), as well as the token "restartMe". If this token appears in a module's .desc file, statmgr will initiate the restart procedure for that module if it's heartbeat should not appear within the stated time period. This procedure involves issuing a 'kill' to the offending module's process id, and [wiki:startstop startstop] will then restart the module in a manner identical to that used at startup. 
    269269 
    270 Note that [wiki:statmgr statmgr], like all modules, has one input. That is, it attaches and listens to one message ring. In order for it to receive error and heartbeat messages from all modules in a node, there are helper modules which 'conduct' such messages from one ring to another. These are the module [wiki:copystatus copystatus]. They are extremely simple, and have no associated .d or .desc files. They are listed in "startstop_xx.d" (e.g., [wiki:startstop_unix startstop_unix] as other modules, but their command line arguments, instead of being the name of the configuration file, name the input and output rings to which they are to attach.  
    271    
    272   
    273  
    274 === 9.3 Other Modules === 
     270Note that statmgr, like all modules, has one input. That is, it attaches and listens to one message ring. In order for it to receive error and heartbeat messages from all modules in a node, there are helper modules which 'conduct' such messages from one ring to another. These are the module [wiki:copystatus copystatus]. They are extremely simple, and have no associated .d or .desc files. They are listed in "startstop_xx.d" (e.g., [wiki:startstop_unix startstop_unix]) as other modules, but their command line arguments, instead of being the name of the configuration file, name the input and output rings to which they are to attach.  
     271   
     272  
     273 
     274=== Other Modules === 
    275275 
    276276The Earthworm release currently includes over 100 modules. However, several key modules are discussed below: 
    277277 
    278 * Import / Export 
     278 * Import / Export 
    279279 
    280280These modules perform long-distance message exchange between Earthworm systems. The Import (e.g., [wiki:import_generic import_generic]) module is supplied with the IP address and port of the Export it is to accept connections from. When it senses a connect request, it connects, and places all incoming messages on it's specified output message ring. The 'shipping label' of the message is that of the incoming message. It exchanges predetermined heartbeat texts with it's Import at specified rates. If the incoming heartbeat text does not match the specification in its configuration file, it closes the connection. If the heartbeat from its Import does not arrive on time, it re-initialized the connection. 
     
    284284[wiki:export_generic export_generic] accepts a list of shipping labels which it is to ship. [wiki:export_scnl export_scnl] ('scnl' as in Station Component Network Location), specializes in shipping only trace messages, and accepts a list of SCNL names to ship. This permits selective sending of only specified data channels. 
    285285 
    286 * [wiki:ringtocoax ringtocoax] / [wiki:coaxtoring coaxtoring] 
     286 * [wiki:ringtocoax ringtocoax] / [wiki:coaxtoring coaxtoring] 
    287287 
    288288These modules effect short-distance replication of messages on a ring. "ringtocoax" (the name dates back to thin-net times), will broadcast all messages in its specified input ring onto a network adapter. The messages are broadcast in the IP sense, in that no recipient is specified. This allows any number of unknown systems to be listening, without affecting the sending system. 
    289289 
    290 * Adsend: e.g., [wiki:adsend adsend] 
    291  
    292 * Picker: e.g., [wiki:pick_ew pick_ew] 
    293  
    294 * Assoc: [wiki:binder_ew binder_ew] 
    295  
    296 * Carl Trig: [wiki:carlstatrig carlstatrig] and [wiki:carlsubtrig carlsubtrig] 
    297  
    298 * HypoInverse: [wiki:eqproc eqproc], ... 
    299  
    300 * See [wiki:Earthworm Earthworm] for a comprehensive list of available modules.  
     290 * Adsend: e.g., [wiki:adsend adsend] 
     291 
     292 * Picker: e.g., [wiki:pick_ew pick_ew] 
     293 
     294 * Assoc: [wiki:binder_ew binder_ew] 
     295 
     296 * Carl Trig: [wiki:carlstatrig carlstatrig] and [wiki:carlsubtrig carlsubtrig] 
     297 
     298 * HypoInverse: [wiki:eqproc eqproc], ... 
     299 
     300 * See [wiki:Earthworm Earthworm] for a comprehensive list of available modules.  
    301301   
    302302  
     
    306306After all modules are configured, the system can be started. 
    307307 
    308 *For mulit-node configurations, it is recommended that at least one remote node be physically close to the central node for initial debugging. 
    309  
    310 * Establish and test all communication links. 
    311  
    312 * Start each node. This is initially best done manually: create a command window, and manually change the directory to the /run_xx/params of this node. Execute the applicable environment file (ew_nt.cmd, ew_sol_sparc.cmd, etc.). Enter the command '[wiki:startstop startstop]'. 
    313  
    314 * The window should display a list of modules and their status, as produced by "startstop" pressing 'enter' will re-display this list. The window will also display any error messages from modules which are sharing this window (see below). 
     308 *For mulit-node configurations, it is recommended that at least one remote node be physically close to the central node for initial debugging. 
     309 
     310 * Establish and test all communication links. 
     311 
     312 * Start each node. This is initially best done manually: create a command window, and manually change the directory to the /run_xx/params of this node. Execute the applicable environment file (ew_nt.cmd, ew_sol_sparc.cmd, etc.). Enter the command '[wiki:startstop startstop]'. 
     313 
     314 * The window should display a list of modules and their status, as produced by "startstop" pressing 'enter' will re-display this list. The window will also display any error messages from modules which are sharing this window (see below). 
    315315 
    316316== 11. Debugging Tools and Hints ==