Post-installation System Configuration
The ShakeCast AWS VM pre-built ShakeCast system comes with a minimal set of configurations with a default email server and worldwide monitoring for earthquake of magnitude 3.0 or greater. Unlike the AWS VM, a non-cloud installation of ShakeCast does not include information for an email server or a polygon of earthquake monitoring.
Until a monitoring region is defined after installation, the ShakeCast system will download earthquake data and ShakeMap products, but will not attempt to process them. No shaking estimates at facilities, local ShakeCast products or ShakeCast notifications can be produced until an earthquake-monitoring region is defined.
To customize the ShakeCast system, users must prepare inventory files outside the ShakeCast system and use the administrative web interface or command-line tools to update the database. The ShakeCast V3 system does not allow direct editing of user or facility inventory in the interface or directly to the database. To upload files, users must use the drag-and-drop upload in the administration area ( Upload tab).
Activate Earthquake Processing
To activate earthquake processing, the administrator must define at least one ShakeCast group. The geometric coordinates of an enclosed polygon defines earthquake monitoring area. When multiple areas are defined, the union of the monitoring regions becomes the new monitoring area.
The configuration file (ca.conf) for the group “CA” in the example below defines an earthquake monitoring that covers the State of California and bordering regions with notifications for new earthquakes of magnitude 3.0 or greater (LIMIT_VALUE) within the region.
# Group Configuration file for CA
# $Id: ca.conf 221 2014-07-23 21:04:39Z klin $
<CA>
POLY 43.000 -126.000 \
39.000 -126.000 \
34.000 -123.000 \
31.000 -118.000 \
31.000 -113.000 \
36.000 -113.000 \
39.000 -118.000 \
43.000 -118.000 \
43.000 -126.000
<NOTIFICATION>
NOTIFICATION\_TYPE NEW\_EVENT
DELIVERY\_METHOD EMAIL\_HTML
EVENT\_TYPE ALL
AGGREGATE 1
LIMIT\_VALUE 3
</NOTIFICATION>
</CA>
ShakeCast can process group definition configuration files via the upload tool from the web interface or from the command line with the manage_group.pl tool. Although not strictly enforced, it is recommended to postfix ShakeCast group definition file with a .conf file extension. After the group configuration file has been successfully processed, the ShakeCast group is displayed under the User tab of the administrative interface as shown below.
Figure 1. ShakeCast Group CA Example.
Configuring Email Server for Notifications
ShakeCast V3 supports the following email protocols:
- Mail Transport Agent (MTA) via mailx
- SMTP with plain text with and without authentication
- SMTP over Secure Sockets Layer (SSL)
- SMTP over Transport Layer Security (TLS)
By default, Linux-based ShakeCast installations (e.g., ShakeCast AWS VM) use the built-in mailx utility and require no additional manual email server configuration. However, the administrator can choose to overwrite the default by specifying an SMTP email server. The Windows system typically lacks MTA support, so the administrator is advised to enter an SMTP server for delivering ShakeCast notifications.
The administrator can enter the SMTP information from either the web interface under the General Settings tab or by editing the ShakeCast system configuration file located at: “<sc_home>/sc/conf/sc.conf.”
Required SMTP email server information:
- DNS hostname of the SMTP server
- Security Layer (none/SSL/TLS)
- Service port (25/465/587)
- Username and Password
Figure 2. SMTP Email server configuration via the web interface.
The administrator must enter a valid email address into the From and EnvelopeFrom fields as the sender email address of the ShakeCast system. The corresponding section inside the sc.conf file is listed as the Notification block as shown below:
<Notification>
SmtpServer smtp.gmail.com
Security SSL
Port 465
DefaultEmailTemplate default.txt
DefaultScriptTemplate default.pl
Password
Username
EnvelopeFrom
From
</Notification>
After saving email server information, the administrator will need to restart the ShakeCast notification service in order to reload the new configuration settings.
Restarting System Services
The ShakeCast administrator requires local administration privileges to restart services from the command line. Restarting system services is needed any time changes are made to entries under the General Settings tab or the system configuration file “ sc.conf.”
Linux : Two shell scripts start/stop daemon services,
- To start services, execute the script “/usr/local/shakecast/sc/rc.d/sc-start-watcher.sh”
- To stop services, execute the script “/usr/local/shakecast/sc/rc.d/sc-stop.sh”
Windows : Two batch files start/stop system services
- To start services, execute the batch “<sc_home>/admin/start_sc_services.bat”
- To stop services, execute the batch “<sc_home>/admin/stop_sc_services.bat”
Database Management
The ShakeCast database repository tracks information from several different sources, including:
- User provided inventory for facilities, user groups and users.
- Earthquake information and related products including ShakeMap and others from the USGS.
- Local ShakeCast products generated as part of the earthquake processing.
- Notification delivery records and miscellaneous system messages.
Once processed, the above information becomes structured data and may be stored among several interconnected tables inside the database. The figure below illustrates the database schema for user’s facility inventory on basic information, attributes, features, and fragility. The ShakeCast administrator should not edit records of the ShakeCast database directly with a database viewing/editing tool but via the ShakeCast administrative interface or command line to avoid database corruption.
- Figure 3. ShakeCast facility inventory database schema
System and Database Reset
The ShakeCast system’s database and file system will increase as it processes more earthquakes, which may slow the system’s performance, depending on the available resources. Although ShakeCast V3 automatically deletes unwanted events from the system, an administrator can delete all events by resetting the system to its original state.
System Reset
Linux
The administrator must manually purge the database and then delete the installed code base from the file system. After ShakeCast is removed from the system, the administrator can check out a new copy of ShakeCast from the USGS github repository below to perform manual installation.
https://github.com/klin-usgs/ShakeCast
Windows
The administrator can use the ShakeCast Installer program to re-install the application to reset a Windows ShakeCast system.
Database Reset
A database reset can manage out-of-control inventory, a critical misconfiguration (e.g., server information) or a ShakeCast database crash.
The database reset is performed from the command line with local Administrator privileges. Switch to the ShakeCast administration script directory default “C:\ShakeCast\admin” and execute the following batch scripts in sequence:
- Drop existing “sc” database and create a new one: create_sc_db.bat
- Create ShakeCast database tables: create_sc_tables.bat
- Load default data: load_sc_data.bat
- Restart ShakeCast services: start_sc_services.bat
- Activate routine tasks: inject_init.bat
- Figure 4. Database reset sequence in ShakeCast for Windows
Facility Inventory
To support component-based fragility assignment and geometric footprints for a facility, an XML file format has been defined to accommodate the expanded scope of information.
The figure below shows an example with information for a typical bridge with 20 components. The combined FACILITY_TYPE and FACILITY_NAME fields must be unique for each facility. Basic information for the facility information is shown in (a). (b) shows geometric features and optional custom html snippet for web presentation. The minimum bounding box of the facility will be used to assess ground motion estimates at the location of facility. (c) shows fragility settings for each defined component and the fragility settings for SYSTEM components and will become the representative setting for the purpose of notifications. Fragility settings for each component consist of one chosen metric and one mean and beta pair for every inspection priority.
The fragility settings for HAZUS (FEMA, 2006) model building types are included in ShakeCast, so buildings with HAZUS model building types defined will have fragility settings associated with them in the ShakeCast system.
If an organization does not have comprehensive facility information, the administrator can still use the legacy file format (in CSV) for facility inventory. Details for preparation of facility inventory in the CSV format is described in Appendix D.
(a)
(b)
(c)
- Figure 5. Sample facility information for one bridge FACILITY: (a) Basic bridge information, (b) bridge geometric features, and (c) fragility settings for bridge components.
After the facility inventory is saved into a file, e.g., bridge.xml, it can be processed by the ShakeCast system via either the Upload tab from the administrative interface or the command line script manage_facility_xml.pl with the following syntax
C:\ShakeCast\sc\bin\manage\_facility\_xml.pl bridge.xml