System Administration

Access to the administrative page is restricted to ShakeCast users with administrative privileges. Tasks that can be performed from the interface include:

• General system configuration
• Earthquake/ShakeMap management
• Facility management
• Station management
• Group/User account and notification management
• Inventory upload

The ShakeCast administrative interface does not manage system level services and supporting software: three ShakeCast daemon services (dispatch, notify queue, notify processes), the Apache Web server and MySQL database applications. An administrator must log on to the server system where the ShakeCast system resides to make changes to the configuration files of applications and to start and stop ShakeCast system processes and supporting software.

Scope of System Management

Most ShakeCast system administrative functions can be accessed via the web interface. The administrative web interface is a collection of HTML5-compatiable pages that interact with the backend ShakeCast database via a uniform Application Programming Interface (API). ShakeCast V3 prohibits direct editing (except delete) of inventory from the database. A universal file drop page is created in V3 to receive updated inventory data.

Figure 1. ShakeCast administrative web interface. The default page displays summary of the system inventory stored inside the database and active processes.

General Settings

The General Settings page allows the ShakeCast administrator to manage system-wide configurable information in six different categories: 1) ShakeCast Database 2) Email Server 3) ShakeMap Server 4) ShakeMap Region 5) System Directory and 6) Misc. Parameter.

NOTE: A system restart is required to load new system configurations.

Figure 2. ShakeCast administrative web interface for general system settings.

System Services Restart

The ShakeCast administrator requires local administration privileges to restart services from the command line. As a general rule of thumb, 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”

ShakeCast Database

The ShakeCast Database form specifies the database connection information. The ShakeCast database account has full privileges to the ShakeCast database only and changes to the database account require database administration privileges. Users should consult with the system administrator and MySQL documentation for information on modifying the database and access privileges.

Table 1. ShakeCast database server information.

Configuring the Notification Email Server

ShakeCast V3 supports the following email protocols,

Mail Transport Agent (MTA) via mailx

• SMTP with plain text (port 25) with and without authentication
• SMTP over Secure Sockets Layer (SSL, port 465)
• SMTP over Transport Layer Security (TLS, port 587)

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 override 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 3. ShakeCast administrative web interface for Email Server configuration.

Table 2. SMTP Email server information.

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         shakecast@usgs.gov
From                shakecast@usgs.gov
</Notification>

After saving email server information, the administrator will need to restart the ShakeCast notification service to reload the new configuration settings.

ShakeMap Server

The ShakeMap Server form specifies ShakeMap server information and is the source of other USGS earthquake products. All ShakeMap products and maps, and the DYFI, PAGER, tectonic summary and historical seismicity plot products are retrieved automatically. The administrator can enable/disable selected servers by toggling the Query flag if multiple servers have been configured.

Figure 4. ShakeCast administrative web interface for ShakeMap Server configuration.

Table 3. Upstream server information.

ShakeMap Region

The ShakeMap Region form specifies information of the ShakeMap regions to be processed by the system. The ShakeMap Region directive functions as a spatial filter based on the predefined boundaries of seismic networks. With the user-defined monitoring region via the GROUP definition, users combine notification requests with user-defined regions to improve performance of the system without unnecessary processing.

For example, users interested in receiving notifications for California enter “NC CI SC NN” corresponding to the Northern California, Southern California, and Nevada networks. The only exception is when there is no group defined in the database and the monitoring regions coincide with the seismic networks.

Figure 5. ShakeCast administrative web interface for ShakeMap Region configuration.

Table 4. ShakeMap region configuration information.

System Directory and Miscellaneous Parameters

The System Directory and Miscellaneous Parameters forms specify information of main directories of ShakeCast and its supporting application. Users usually do not need to change the default settings and will need verify access permissions (data directory needs to be readable from the Internet) when specifying a new location in the file system.

Figure 6. ShakeCast administrative web interface for System Directory (top) and Misc. Parameters configuration (bottom).

Table 5. Directory and Miscellaneous Parameters.

Earthquake Database Management

The Earthquake Database Management section allows a ShakeCast administrator to manage earthquake inventory in three different categories:

• Processed ShakeMap events
• Significant earthquakes list
• ShakeMap scenarios

Processed ShakeMap events are those automatically downloaded and processed by the user’s system based on the ShakeMap Region configuration. Events flagged by the user as “significant” can be more readily accessed. Scenarios are hypothetical event ShakeMaps produced and stored on the USGS web pages:

http://earthquake.usgs.gov/earthquakes/shakemap/list.php?x=1&s=1

ShakeCast users can “inject” (import) any scenarios for their own for ShakeCast testing or for earthquake planning exercises using ShakeMap/ShakeCast.

The web form inside the page is used to retrieve additional ShakeMap inventory from the USGS Web site. The ShakeCast local test event type “*_scte” is merged with the scenario type “*_se” in V3. The scenario is supported but users are encouraged to switch to using the standard scenario type.

Figure 7. ShakeCast web interface for earthquake database administration.

Geospatial and magnitude filters determine the list of earthquakes processed and stored inside the ShakeCast database. The geospatial filter is based on either seismic network or user-defined polygon boundaries as a pre-processor for ShakeCast. The magnitude threshold filter is also a pre-processor filter for triggering ShakeCast process. The default 3.0 magnitude can be changed from the web interface. The archiving magnitude filter is used by the earthquake maintenance cron job for archiving purpose and the default 5.0 magnitude can only be changed inside the ShakeCast configuration file from the file system. For users within seismically active regions, these filters and archiving thresholds become key for balancing the immediate access to and the volume of ShakeMap products stored.

The ShakeCast V3 earthquake maintenance cron job runs daily and automatically maintains the earthquake inventory. Earthquakes without any facility exposure and with magnitudes below the archiving magnitude will be removed from the system once they fall outside twice the active response time window (as defined by the user) from the earthquake origin time.

The three main operations on an earthquake and its associated products via the GUI are to

• Toggle an archive flag
• Trigger a scenario run
• Delete an event

Figure 8. ShakeCast administrative web interface for earthquake database management.

The new archival flag is used to manually override the default system behavior. An earthquake will be permanently archived if the archive flag is set. All events retrieved and triggered via the web interface are treated as scenario events. To trigger a ShakeMap as an actual event, the administrator needs to perform the action from the command line to avoid accidental triggering. If the triggered ShakeMap falls outside the active response window, a “-force_run” option is required to execute the command. See Appendix C for details on triggering ShakeMaps (“shake_fetch.pl” and “scfeed_local.pl”) from the command line.

• Processed Earthquakes : A table of all processed actual earthquakes within twice the active response window and all archived events. Available actions are shown as clickable buttons at the top of the table. To apply the action, select the earthquake rows (multiple selections are allowed using CTRL-click or SHIFT-click) then click on the corresponding action button.
• Significant Events : A table of all processed actual earthquakes with a set archive flag. Available actions are the same as processed earthquakes.
• ShakeMap Scenarios : A table of both scenarios and actual earthquakes converted for use as scenarios. Scenario earthquakes are not subject to the archiving rules.
• USGS ShakeMap Archive : The USGS ShakeMap Web form reads one network ID and one event ID and retrieves the specified event as a scenario. If the event has already been processed by the system, the request will fail. The user should use the Trigger Scenario function instead. The collection of ShakeMaps for real events includes the thousands of historic events found in the ShakeMap Atlas.
• Custom ShakeMap Scenarios : ShakeMaps that are not available from the USGS web site can be uploaded into ShakeCast via the upload utility page. These ShakeMaps are usually custom-made based on user request or for an earthquake exercise. Most of the pre-compiled ShakeMap scenarios can be found on the ShakeCast Wiki site.

Facility Database Management

The Facility Database Management section allows the administrator to inspect facility information and to perform simple maintenance tasks. ShakeCast V3 has greatly expanded facility-related information and processing capabilities and includes:

• Basic facility and fragility information.
• Probabilistic fragility curve information.
• Supplemental attributes and facility-specific assessment methods.
• Supplemental geometric features and detailed facility information.
• Prototype facility-station association.
• Prototype predictive ground motion estimates.

Figure 9. ShakeCast administrative web interface for facility inventory management.

The two main actions for an earthquake via the GUI are to either (1) delete selected facilities or (2) purge facilities for the selected facility type. Due to the increasing complexity of facility-related information, direct editing of facility information stored inside the ShakeCast database is disabled via the web interface. ShakeCast operators will be required to maintain their facility inventory in external data systems and produce ShakeCast compatible XML or CSV formatted files as their facility inventory and data changes over time. The XML/CSV files are then used to periodically update the facility inventory in the ShakeCast system using an upload utility page. The general approach for ShakeCast database management is that a ShakeCast operator will maintain facility data (as well as user, notification, and other ShakeCast input) offline locally to avoid editing the operational system’s database, and update the operational system with pre-compiled, separately maintained data.

To view information for a single a facility, select the facility in the facility table to display detailed facility information.

Figure 10. ShakeCast administrative web interface for facility inventory management.

(a)

(b)

(c)

(d)

Figure 11. (a) Basic facility fragility for notification, (b) facility features, (c) fragility probability information and (d) facility attributes for a selected facility.

Earthquake Product Management

The Earthquake Product Management section allows the administrator to control and customize the products listed in the earthquake page that are presented to users, as shown in the figure below.

Figure 12. Earthquake product list in both the ShakeCast earthquake list and detailed page.

In ShakeCast V3, the scope of earthquake products covers not only the ShakeMap products required by ShakeCast, but also other ShakeMap products and products available from the USGS web site. Depending on the system setup, earthquake products are received via either the earthquake JSON data feed or via the PDL client. The system is pre-configured to recognize selected USGS earthquake product types including DYFI?, PAGER, ShakeMap, tectonic summary, and some local ShakeCast products. Products besides ShakeMap and ShakeCast are saved into the “eq_product” data directory. Products not registered in the ShakeCast database, such as additional DYFI? and PAGER products, geoserve, nearby_cities, and seismicity plots, are reserved for user customization in the future. Note that a product (either from USGS or locally generated) needs to be registered in ShakeCast before it can be included in the ShakeCast processing. These processes include both notification attachment and custom assessment procedure calls.

From the administrative interface, a product can be enabled or disabled for direct access by the end-user.

Figure 13. ShakeCast administrative web interface for earthquake product management.

Station Database Management

ShakeCast V3 comes pre-configured with a station database containing information of ~10,000 stations globally. The system will continue to add new stations to its database as it processes new station data from ShakeMap.

ShakeCast V3 includes a prototype feature that permits users to create station-facility associations to preselect actual station recordings nearby a facility to estimate from ShakeMap. The source of ground shaking data is normally based on ShakeMap input station files, but can also be provided by the user via an import program. After an earthquake, the ground shaking estimates at the site of facilities will be based on observations at station-associated facilities, or with ShakeMap estimates initially and then replaced with actual station recordings as they then become available via subsequent ShakeMap revisions or user import.

Users interested in adapting the function should be aware of potential issues pertaining to availability and quality control of strong motion data. The ShakeMap process combines predictive, actual, and converted ground motions to produce the best and stable estimates. Relying solely on a single source of data may result in unreasonable facility shaking assessment if the associated station is not properly maintained or if the recorded data is not processed correctly (e.g., clipped and non-seismic data). Also ShakeMap does not enforce the naming convention of input station data, so it is possible that the ShakeCast station database contains duplicate entries of the same station. The baseline station information will be refreshed as part of the ShakeCast update to reflect the changes to station location and instrumentation.

From the administrative interface shown below, users can inspect the station information, but the only permitted action is to remove the selected stations from the ShakeCast database.