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.

Figure 14. ShakeCast administrative web interface for station database management.

User Database Management

ShakeCast V3 defines three different user types: ADMIN , USER , and GROUP. The system comes pre-configured with a default administrator account “scadmin” and the administrator should change the password or remove the account before bringing the server into production.

The figure below shows the interface for user administration. The user group ( GROUP ) category operates as a universal filter for notification requests.

Figure 15. ShakeCast administrative web interface for user database management.

The most distinct feature of User Group is the dual purposes of the geometric polygon definition. The user-defined polygon is used to compile a list of facilities within the footprint of the polygon for notification requests. After an earthquake occurs, the same custom polygon is used as a filter to determine whether or not it should be processed by the ShakeCast system.

As a result, a user group geometry polygon is equivalent to an earthquake response region defined by the administrator. Thus the user is no longer bound to existing earthquake or ShakeMap regions defined by the seismic networks. When multiple polygons are defined, the union of the polygon footprints is the effective response region. As the default, the ShakeCast V3 system currently has one user group defined in the database with global coverage for the 40,000+ city inventory.

ShakeCast V3 only permits the GROUP user type to register notification requests in the ShakeCast database, both the ADMIN and USER type users need to be associated with at least one group in order to receive ShakeCast notifications. A user can be affiliated with multiple groups to receive multiple group-specific notifications. Notifications from multiple groups will not be aggregated into a single message for the user. Thus users may receive duplicate notifications if the same request is configured in separate group-specific notification requests.

Appendix A contains detailed information regarding specifications of user data, notification requests, and monitoring regions. There are two corresponding programs described in Appendix C that handle GROUP (“mange_group.pl”) and ADMIN/USER (“manage_user.pl”) data.

Figure 16. Notification requests for the GLOBAL group defined in the ShakeCast user database.

Figure 17. An example of user information and group association defined in the ShakeCast user database.

Inventory Upload Utility

ShakeCast V3 introduces a new centralized inventory upload utility page for transferring user inventory files to the ShakeCast file system. The upload page uses a drag-and-drop mechanism to provide a unified interface for all inventory types. The system is allows up to five files to be uploaded simultaneously with a maximum file size of ~500MB.

Figure 18. ShakeCast administrative interface for drag-and-drop inventory upload.

The inventory upload page displays both the status and result of individual upload attempts. All uploaded files are collected in the “tmp” directory under the ShakeCast system directory. After a successful upload, the file will be examined and the software will prompt the user with applicable choices given the nature of the file uploaded.

Recognized file types include:

• Compressed (zip) archive: The uploaded zip file will be uncompressed to inspect the content. ShakeMap scenario and ShakeCast test events will trigger an event processing action.
• Configuration (conf) file: The content of an uploaded configuration file will be examined to determine if it is a valid group configuration file. A user group processing action will be triggered if the file passes the validity checks.
• CSV file: The content of an uploaded CSV file will be examined to determine if it is a valid facility or user file. A user processing action will be triggered if the file is a valid user file. A CSV facility processing action will be triggered if the file is a valid facility file.
• Image file: gif, jpg, and png are acceptable file types. No actions will be applied. Uploaded image files will be saved as read only files into the ShakeCast image directory. This is used to upload user-specific images to overwrite the system default logo and facility icons.
• XML file : The content of an uploaded XML file will be examined to determine if it is a valid facility XML. An XML facility processing action will be triggered if the file passes the test.
• All other files : No actions will be taken if the content of an uploaded file cannot be verified. Examples of uploaded files in this category include ShakeCast patch updates and notification templates.

Figure 19. ShakeCast administrative interface for inventory upload showing the result of upload and the recommended user options to further process the uploaded file.

If a subsequent process is applicable to the uploaded file, a dialog form will be displayed above the drag-and-drop section. The allowed actions, insert, update and delete, will complement the inventory management described in previous sections. Results of a submitted action will be prompted as shown in the figure above. ShakeCast administrators should use the upload utility to perform common inventory maintenance tasks.

Figure 20. ShakeCast administrative interface for inventory upload showing output messages from the processing program for the uploaded file.

Cron Job

Repeated tasks are performed by a generic Cron function in ShakeCast V3. Cron Job simulates the generic cron function of a UNIX system and is platform independent. Cron jobs (crons) are saved inside the ShakeCast database managed by the ShakeCast dispatcher. The administrator does not need a separate system account with elevated credentials to create a cron job.

The scope of executable crons covers all aspects of the system and secondary computation processes to expand the core functions of the system (System Worker). Details of executable crons are described in Appendix C (task_inject), and provide the following functions:

• Compute theoretical ground motions for facilities of the specified earthquake.
• Rotate the ShakeCast log files.
• Generate log statistics plots.
• Trigger a ShakeCast heartbeat message.
• Refresh the USGS earthquake JSON feed and process new earthquakes.
• Trigger maintenance of the ShakeCast database.
• Trigger the process to compute probabilistic facility fragilities.
• Trigger the process to compute exceedance of regulatory levels.
• Take a screen shot for the selected earthquake and save the output image.
• Generate image tile overlay to be displayed on the web interface.

There are five pre-installed default cron jobs for a ShakeCast system that receive earthquake products and perform maintenance of the system. Custom configuration of cron jobs should only be performed by an experienced ShakeCast administrator.

[]: