System Configuration

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.

1. 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:

1. Drop existing “sc” database and create a new one: create_sc_db.bat
2. Create ShakeCast database tables: create_sc_tables.bat
3. Load default data: load_sc_data.bat
4. Restart ShakeCast services: start_sc_services.bat
5. Activate routine tasks: inject_init.bat

1. 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)

1. 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

To delete selected facilities from the ShakeCast database, select the Facilities tab from the administrative web interface.

1. Select Facility Type
2. Highlight facilities to be deleted
3. Click the Delete Selected Facilities button to delete

To delete all facilities of the selected facility type, click the Delete All Facilities button

To revert or delete the facility inventory using the tool under the Upload tab, drop-in the same facility inventory file and choose the Delete option before submit. With the command line script, manage_facility_xml.pl, issue the following command:

C:\ShakeCast\sc\bin\manage_facility_xml.pl –delete bridge.xml

User Groups

A ShakeCast user GROUP registers both the earthquake monitoring region and the notification requests for the user group. For example, we define an area that covers the entire State of California plus one degree buffer for statewide earthquake monitoring. As the result, the contributing networks for earthquake information are not limited to the California Integrated Seismic Network (CISN) and will also include Pacific Northwest network (UW), the Nevada network (NN), and the Global Seismic Network (GSN). Sub-division groups can be derived from the statewide group to provide notifications for specific needs.

Users can belong to multiple groups to further customize their notification preferences. As an example, the Caltrans State Bridge group configuration file shown below contains four directives:

1. FACILITY_TYPE specifies a filter for state bridges only.
2. POLY specifies an area for statewide coverage.
3. NEW_EVENT NOTIFICATION specifies notification requests for new earthquakes (once per event).
4. Inspection Priority (DAMAGE) NOTIFICATION specifies notifications requests for an aggregated list of state bridges in either GREEN, YELLOW, ORANGE, and RED states. This directive will exclude state bridges tagged as GREY (Below Threshold) and will attach a ShakeCast summary PDF file if it is available at the time of notification.

<BRIDGE\_ST>
        FACILITY\_TYPE        BRIDGE\_ST
        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                        ACTUAL
                AGGREGATE                        1
                LIMIT\_VALUE                        4
        </NOTIFICATION>

        <NOTIFICATION>
                NOTIFICATION\_TYPE                DAMAGE
                DELIVERY\_METHOD                EMAIL\_HTML
                DAMAGE\_LEVEL                        GREEN
                EVENT\_TYPE                        ACTUAL
                AGGREGATE                        1
                AGGREGATION\_GROUP                BRIDGE\_ST
                PRODUCT\_TYPE                        PDF\_BRIST
        </NOTIFICATION>

        <NOTIFICATION>
                NOTIFICATION\_TYPE                DAMAGE
                DELIVERY\_METHOD                EMAIL\_HTML
                DAMAGE\_LEVEL                        YELLOW
                EVENT\_TYPE                        ACTUAL
                AGGREGATE                        1
                AGGREGATION\_GROUP                BRIDGE\_ST
                PRODUCT\_TYPE                        PDF\_BRIST
        </NOTIFICATION>

        <NOTIFICATION>
                NOTIFICATION\_TYPE                DAMAGE
                DELIVERY\_METHOD                EMAIL\_HTML
                DAMAGE\_LEVEL                        ORANGE
                EVENT\_TYPE                        ACTUAL
                AGGREGATE                        1
                AGGREGATION\_GROUP                BRIDGE\_ST
                PRODUCT\_TYPE                        PDF\_BRIST
        </NOTIFICATION>

        <NOTIFICATION>
                NOTIFICATION\_TYPE                DAMAGE
                DELIVERY\_METHOD                EMAIL\_HTML
                DAMAGE\_LEVEL                        RED
                EVENT\_TYPE                        ACTUAL
                AGGREGATE                        1
                AGGREGATION\_GROUP                BRIDGE\_ST
                PRODUCT\_TYPE                        PDF\_BRIST
        </NOTIFICATION>
</BRIDGE\_ST>

After the group configuration is saved into a file, bridge_st.conf, it can be processed by the ShakeCast system via either the Upload tab from the administrative interface or the command line script manage_group.pl with the following syntax

C:\ShakeCast\sc\bin\manage\_group.pl –conf bridge\_st.conf

To delete selected groups from the ShakeCast database, select the Users tab from the administrative web interface.

1. Select GROUP User Type
2. Highlight groups to be deleted
3. Click the Delete Selected Users button to delete

To delete all groups of the selected facility type, click the Delete All Users button

To revert or delete the facility inventory using the tool under the Upload tab, drop-in the same group inventory file and choose the Delete option before submit. With the command line script, manage_group.pl, issue the following syntax

C:\ShakeCast\sc\bin\manage\_group.pl –delete –conf bridge\_st.conf

User Inventory

ShakeCast V3 does not provide user-specific notification preferences and requires a user to sign up for at least one user group in order to receive notifications. When signing up for multiple groups, the group-specific messages will not be aggregated for the user, thus the user may receive several messages with group-specific contents for an earthquake.

In addition to designating user’s group and notification preferences, the user inventory also specifies access privileges via the ShakeCast web interface. The defined username and password is for the web access only and does not create local user accounts on the ShakeCast server.

As an example, the above spreadsheet defines the following required information:

1. USER_TYPE is either the USER or ADMIN type. ADMIN users have additional privileges for access and ShakeCast administrative web interface.
2. USERNAME and PASSWORD fields define user access credentials. The combined USER_TYPE and USERNAME field needs to be unique.
3. DELIVERY::EMAIL_HTML field defines the email address for receiving rich content HTML ShakeCast notifications.
4. The GROUP::BRIDGE_ST::BRIDGE_LC header field lists the two allowed group designations (BRIDGE_ST and BRIDGE_LC). The user in the data row has an assigned group for BRIDGE_ST.

After the user inventory is saved into a file in the CSV format, e.g. caltrans_user.csv, it can be processed by the ShakeCast system via either the Upload tab from the administrative interface or the command line script manage_user.pl with the following syntax

C:\ShakeCast\sc\bin\manage\_user.pl caltrans\_user.csv

Deleting selected users via the administrative web interface is identical to deleting a group. The administrator selects either the ADMIN or USER type before highlighting users for deletion. To revert or delete the user inventory using the tool under the Upload tab, drop-in the same user inventory file and choose the Delete option before submit. With the command line script, manage_user.pl, issue the following syntax

C:\ShakeCast\sc\bin\manage\_user.pl –delete caltrans\_user.csv

Earthquake and Scenario Inventory

ShakeCast maintains a local earthquake database, effectively a subset of the USGS ShakeMap archive. ShakeMaps for actual earthquakes are received and processed by the system automaticall, but scenario ShakeMaps must be manually triggered by an administrator. Scenarios can be triggered with a scenario ShakeMap package or downloaded directly from the USGS web site.

For automated earthquake processing, management of the ShakeCast earthquake inventory for actual events require (1) defining the earthquake monitoring regions; and (2) configuring the triggering and archiving filters.

The filters for earthquake triggering and archiving are optional configurations and are not included under the General Settings tab of the administrative interface because of infrequent use. To change the default settings, edit the ShakeCast system configuration file, default at “C:\ShakeCast\sc\conf\sc.conf”.

A snippet of the configuration options shown below dictate the behavior for processing and archiving of actual earthquakes.

• MAG_CUTOFF option specifies the minimum magnitude requirement for triggering the ShakeCast process.
• ARCHIVE_MAG option specifies minimum magnitude requirement for the earthquake to be permanently archive after the active time window expires.
• TIME_WINDOW option specifies the time window (in days) after the origin for an earthquake to be considered as active.

MAG_CUTOFF 3

ARCHIVE_MAG 5.0

<rss>
    AUTOSTART   1
    **TIME\_WINDOW**   7
    PROMPT   rssd>
    MSGLEVEL   2
    SERVICE\_NAME   rssd
    POLL   60
    SPOLL   10
    LOG   C:/Shakecast/sc/logs/sc.log
    REGION   ALL
    SERVICE\_TITLE   ShakeCast RSS Daemon
    LOGGING   1
    PORT   53458
</rss>

As part of the automated processing, a cron job for earthquake inventory maintenance runs daily to identify and delete unwanted earthquakes from the system. Actual earthquakes with magnitude below the archiving magnitude are removed from the database automatically. Earthquakes above the archive magnitude but without any exposed facilities will also be deleted.

To override the default system behavior, an administrator can set the archiving flag for earthquakes to be excluded from the system archiving policy.

To toggle archive flag for selected earthquakes, select the Earthquakes tab from the administrative web interface.

1. Select Processed Earthquake list

2. Highlight earthquakes to be archived

3. Click the Toggle Permanent Archive Flag button to enable/disable the archive flag

Archived earthquakes are indicated in the Permanent Archived column.

The USGS has prepared ~250 ShakeMap scenario packages for for California (80 Northern California and 170 Southern California). To add scenario ShakeMaps to the ShakeCast system, the administrator either upload a premade scenario package via the Upload tab from the administrative interface or download the scenario directly from the USGS web site. The command line script shake_fetch.pl performs the same function using the following syntax

C:\ShakeCast\sc\bin\shake_fetch.pl –network -event -force\_run -scenario

Both actual and scenario ShakeMaps can be deleted from the ShakeCast system using the administrative interface. To delete selected earthquakes from the ShakeCast database:

Select the Earthquakes tab from the administrative web interface.

1. Select Earthquake Inventory
2. Highlight earthquakes to be deleted
3. Click the Delete Selected Events button to delete

To revert or delete the facility inventory using the tool under the Upload tab, drop-in the same group inventory file and choose the Delete option before submit. With the command line script, manage_group.pl, issue the following syntax

C:\ShakeCast\sc\bin\manage_event.pl –delete <eventid …>

Notification and System Records

ShakeCast tracks system activities related to executed tasks, background processes, notifications, and state-of-health warning and error messages. General activities are logged into separate files

• sc.log stores general information and results of program execution
• sc_access.log stores information on access to the system over the web
• sc_error.log stores information when programs return with non-normal status

More critical information related to state of notifications and error messages for the system are stored inside the database in two separate tables as a document trail.

To minimize the need for record maintenance, a cron job for log file maintenance runs daily to rotate log files in a ring buffer. The administrator specifies options for the maintenance script inside the system configuration file, “C:\ShakeCast\sc\conf\sc.conf”

<Logrotate>
    LOGSTATDIR   C:/Shakecast/sc/images
    **rotate-time**   1 week
    compress   Yes
    **keep-files**   5
    status-file   C:/Shakecast/sc/logs/logrotate.status
    **max\_size**   100 M
    **logfile**   C:/Shakecast/sc/logs/sc.log
    logfile   C:/Shakecast/sc/logs/sc\_access.log
    logfile   C:/Shakecast/sc/logs/sc\_error.log
</Logrotate>

Key fields of the configuration section Logrotate from the system configuration are described below:

• rotate-time specifies the length in time before the log entries to be removed from the log file
• keep-files specifies the number of archived log files to be saved before permanently deleted from the system
• max_size specifies the maximum allowed file size of the log files. Once the file size exceeds the limit, log entries will be removed even before the rotation time is reached
• logfile specifies the list of log files to be maintained and rotated

Maintenance of system records stored inside the ShakeCast database is usually not required and is only needed when the system shows signs of slow performance, such as delayed notifications. Accumulation of records depends primarily on the number of inventory and notifications configured for a particular system and can vary greatly from one system to another. The administrator should not interact with the database directly and instead execute the command to clean up stored messages in the database at a suggested frequency of once per quarter:

C:\ShakeCast\sc\util\clear\_notify\_table.pl

[]: