Automatic CAP alerts

Important

Beta version 2.1. What is described here exists only in beta version 2.1: it is installed from the beta repository and only with a licence; the stable version 2.0.2 and the demo edition do not have it. The beta version comes without warranty, and support is best effort (Beta testing programme).

Since version 2.1.1.508, the node accepts emergency alerts in the OASIS CAP 1.2 format (Common Alerting Protocol), from the site’s safety systems and from public alert feeds, and switches channels to the alert clip of the alert’s category (Alert clips). By default a new alert waits for an operator’s confirmation. Intake is set up and run on the “CAP alerts” tab of the “Emergency alerting” screen (The “CAP alerts” tab).

Intake works only while the “Emergency alerting” master switch is on (Emergency alerting). Each node has its own intake settings and state: they are not passed to other nodes of the domain. Waiting alerts and the history are kept in memory: after a streamer restart they are gone, and the feeds bring the alerts in force again at the next poll. The demo edition has no intake.

Where alerts come from

Push. A site system (fire alarm, public address system) sends a CAP 1.2 alert in XML format by a POST request to the address https://<node>:<HTTPS port>/cap/v1/alerts of the node’s web server. The sender does not sign in to the console: its access is checked separately (Push security). Limits: up to 1 MB per request, up to 10 requests per minute from one address, UTF-8 encoding only; text fields longer than 512 characters are truncated.

Feeds. The node itself polls CAP or Atom feeds over HTTPS with certificate verification; https:// URLs only. The poll period is from 30 to 3600 s, 60 s by default; one poll lasts no longer than 60 s. The node trusts a feed’s certificate by the system CAs and, if set, by an extra CA file. If a feed cannot be read (an HTTP or TLS error, a response that is not CAP), alert 82 is raised (cap-source-error, CAP alerts).

Which alerts switch channels

An alert passes if at least one of its info blocks (info) passes all three thresholds and, where required, matches the site’s area.

  • Thresholds: the least severity (“Severe” by default), the least urgency (“Expected” by default) and the least certainty (“Likely” by default). An alert below any threshold is ignored.

  • Site area: the site’s geocodes (pairs like EMMA_ID=DE300) or a point, latitude and longitude. An alert matches if it carries one of these geocodes or its polygon or circle contains the point. Alerts from feeds must always match the area: with no area, no feed alert passes. For push this requirement is turned on separately.

  • Status: Test and Exercise alerts never switch channels; System and Draft are ignored.

  • Restricted distribution (scope Restricted) is accepted only by push.

The XML signature is not verified: trust in the source comes from the sender list, the token and HTTPS for push, and from certificate verification for feeds.

What happens to an alert

  1. Waiting for the operator. A new alert that has passed the filters waits for confirmation; alert 81 is raised (cap-alert). The Admin and Restricted admin roles can confirm or dismiss it, in the console banner or on the “CAP alerts” tab. If “Wait for an operator’s confirmation” is off, the alert switches the channels by itself.

  2. On air. A confirmed alert turns on an emergency override (Emergency override to an announcement): the channels show the clip of the alert’s category or, if the category has no clip, the default clip. An alert without a clip cannot be put on air. The target channels are all eligible SPTS streams of the node or a list chosen in the settings.

  3. Update. An update (Update) of the alert on air is applied without a new confirmation. If after the update the alert no longer passes the filters, the channels go back.

  4. End. A cancellation (Cancel) or expiry of the alert returns the channels to their inputs. The operator can also end the alert manually.

Precedence. A more severe alert replaces a less severe CAP alert on air. A CAP alert does not replace an emergency override turned on manually: the alert waits until the operator ends the manual override. The note of a manual override cannot begin with [CAP].

Push security

An alert switches channels, so access to push is closed by default:

  • Allowed senders are addresses, ranges or CIDR blocks, comma separated. An empty list means nobody can send.

  • Token: if set, the sender passes it in the X-CAP-Token header.

  • HTTPS only is on by default: push is accepted only on the web server’s HTTPS port (Web server & accounts).

The sender gets a refusal as an HTTP code: 403 for the address, the token, or HTTP instead of HTTPS; 404 when intake, push or the master switch is off; 413 for a request larger than 1 MB; 429 when the request limit is exceeded.

Warning

Turning off “Wait for an operator’s confirmation” means that every alert that passes the filters will switch the channels without a person. Turn it off only if you trust the sources and the filters completely.