diff --git a/about.rst b/about.rst index f9046864..c3660ca1 100644 --- a/about.rst +++ b/about.rst @@ -37,9 +37,9 @@ environment. .. _legacy monitoring tool: https://www.quest.com/foglight/ .. _credible: https://www.nagios.org/ .. _alternatives: https://www.zabbix.com/ -.. _`The Guardian`: http://www.theguardian.com/ +.. _`The Guardian`: https://www.theguardian.com/international .. _Ganglia metrics: https://github.com/ganglia/monitor-core/wiki .. _`metrics and monitoring system`: https://www.theguardian.com/info/developer-blog/2012/oct/04/winning-the-metrics-battle .. _Guardian developer teams: https://developers.theguardian.com/ -.. _`swimlaned`: http://akfpartners.com/growth-blog/fault-isolative-architectures-or-swimlaning +.. _`swimlaned`: https://akfpartners.com/growth-blog/fault-isolative-architectures-or-swimlaning .. _`riemann-config`: https://github.com/guardian/riemann-config diff --git a/api/alert.rst b/api/alert.rst index cf637318..0384d826 100644 --- a/api/alert.rst +++ b/api/alert.rst @@ -62,7 +62,7 @@ The following alert attributes are populated at source: default) then alerts must have an ``environment`` attribute that is one of either ``Production`` or ``Development`` and it must define a ``service`` attribute. For more information on configuring - or disabling this plugin see :ref:`plugin config`. + or disabling this plugin see :ref:`plugin settings`. Attributes added when processing alerts --------------------------------------- @@ -138,7 +138,7 @@ Alert Status Alert Severities ---------------- -The `Alarms in Syslog`_ :RFC:`5674` was referenced when defining +The `Alarms in Syslog`_ `5674 `_ was referenced when defining alert severities. +-------------------+---------------+--------+ @@ -171,7 +171,7 @@ alert severities. | ``unknown`` | 10 | Grey | +-------------------+---------------+--------+ -.. _Alarms in Syslog: http://tools.ietf.org/html/rfc5674#section-2 +.. _Alarms in Syslog: https://datatracker.ietf.org/doc/html/rfc5674#section-2 .. _history: diff --git a/api/query-syntax.rst b/api/query-syntax.rst index c989c5ea..ae61fc66 100644 --- a/api/query-syntax.rst +++ b/api/query-syntax.rst @@ -17,7 +17,7 @@ Queries are supported by the following resource endpoints: * :ref:`heartbeats ` * :ref:`users ` * :ref:`customers ` - * :ref:`oembed ` + * `oEmbed `_ .. _url_query_params: @@ -155,7 +155,7 @@ To search for numbered devices beginning with "net", "netwrk" or "network" use:: there may be subtle differences between `Postgres POSIX regular expressions`_ and `MongoDB PCRE $regex pattern matching`_ in practice. -.. _Postgres POSIX regular expressions: https://www.postgresql.org/docs/9.6/static/functions-matching.html#FUNCTIONS-POSIX-REGEXP +.. _Postgres POSIX regular expressions: https://www.postgresql.org/docs/9.6/functions-matching.html#FUNCTIONS-POSIX-REGEXP .. _MongoDB PCRE $regex pattern matching: https://docs.mongodb.com/manual/reference/operator/query/regex/ Ranges diff --git a/api/reference.rst b/api/reference.rst index c549a206..b82a4dae 100644 --- a/api/reference.rst +++ b/api/reference.rst @@ -42,11 +42,11 @@ Input +-----------------+----------+----------------------------------------------+ | ``environment`` | string | environment, used to namespace the resource | +-----------------+----------+----------------------------------------------+ -| ``severity`` | string | see :ref:`severity_table` table | +| ``severity`` | string | see :ref:`severity table` table | +-----------------+----------+----------------------------------------------+ | ``correlate`` | list | list of related event names | +-----------------+----------+----------------------------------------------+ -| ``status`` | string | see :ref:`status_table` table | +| ``status`` | string | see :ref:`status table` table | +-----------------+----------+----------------------------------------------+ | ``service`` | list | list of effected services | +-----------------+----------+----------------------------------------------+ @@ -331,7 +331,7 @@ Input +-----------------+----------+----------------------------------------------+ | Name | Type | Description | +=================+==========+==============================================+ -| ``action`` | string | **Required** Action from ``ack``, ``unack``` | +| ``action`` | string | **Required** Action from ``ack``, ``unack`` | | | | ``shelve``, ``unshelve``, ``close`` | +-----------------+----------+----------------------------------------------+ | ``text`` | string | reason for action | @@ -485,30 +485,30 @@ filter results. Parameters ++++++++++ -+------------------+----------+----------------------------------------------+ -| Name | Type | Description | -+==================+==========+==============================================+ -| ```` | string | any alert attribute. eg. ``status=open`` | -+------------------+----------+----------------------------------------------+ -| ``q`` (*) | string | query string :ref:`query syntax ` | -| | | eg. ``service:Web OR resource:web`` | -+------------------+----------+----------------------------------------------+ -| ``from-date`` | datetime | ``lastReceiveTime`` > ``from-date`` | -+------------------+----------+----------------------------------------------+ -| ``to-date`` | datetime | ``lastReceiveTime`` <= ``to-date`` (now) | -+------------------+----------+----------------------------------------------+ -| ``sort-by`` | string | attr to sort by (default:``lastReceiveTime``)| -+------------------+----------+----------------------------------------------+ -| ``reverse`` | boolean | change direction of default sort order | -+------------------+----------+----------------------------------------------+ -| ``page`` | integer | number between 1 and total pages (default: 1)| -+------------------+----------+----------------------------------------------+ -| ``page-size`` | integer | default: 1000 (set ``DEFAULT_PAGE_SIZE`` ) | -+------------------+----------+----------------------------------------------+ -| ``show-raw-data``| boolean | show raw data | -+------------------+----------+----------------------------------------------+ -| ``show-history`` | boolean | show alert history | -+------------------+----------+----------------------------------------------+ ++-------------------+----------+----------------------------------------------+ +| Name | Type | Description | ++===================+==========+==============================================+ +| ```` | string | any alert attribute. eg. ``status=open`` | ++-------------------+----------+----------------------------------------------+ +| ``q`` (*) | string | query string :ref:`query syntax ` | +| | | eg. ``service:Web OR resource:web`` | ++-------------------+----------+----------------------------------------------+ +| ``from-date`` | datetime | ``lastReceiveTime`` > ``from-date`` | ++-------------------+----------+----------------------------------------------+ +| ``to-date`` | datetime | ``lastReceiveTime`` <= ``to-date`` (now) | ++-------------------+----------+----------------------------------------------+ +| ``sort-by`` | string | attr to sort by (default:``lastReceiveTime``)| ++-------------------+----------+----------------------------------------------+ +| ``reverse`` | boolean | change direction of default sort order | ++-------------------+----------+----------------------------------------------+ +| ``page`` | integer | number between 1 and total pages (default: 1)| ++-------------------+----------+----------------------------------------------+ +| ``page-size`` | integer | default: 1000 (set ``DEFAULT_PAGE_SIZE`` ) | ++-------------------+----------+----------------------------------------------+ +| ``show-raw-data`` | boolean | show raw data | ++-------------------+----------+----------------------------------------------+ +| ``show-history`` | boolean | show alert history | ++-------------------+----------+----------------------------------------------+ .. deprecated:: 6.3 @@ -517,7 +517,7 @@ Parameters Postgres backends. For more information see :ref:`API Query String Syntax `. -.. _Mongo-style query: http://docs.mongodb.org/manual/reference/operator/query/ +.. _Mongo-style query: https://docs.mongodb.com/manual/reference/operator/query/ .. _Lucene query syntax: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax Example Request @@ -794,11 +794,21 @@ Parameters +=================+==========+==============================================+ | ```` | string | | +-----------------+----------+----------------------------------------------+ -| ``q`` | dict | mongo query see `Mongo Query Operators`_ | +| ``q`` (*) | dict | | +-----------------+----------+----------------------------------------------+ | ``group-by`` | string | any valid alert attribute. Default:``event`` | +-----------------+----------+----------------------------------------------+ +.. deprecated:: 6.3 + + The ``q`` parameter using `Mongo-style query`_ format has been replaced with + a query format based on `Lucene query syntax`_ supported by both MongoDB and + Postgres backends. + For more information see :ref:`API Query String Syntax `. + +.. _Mongo-style query: https://docs.mongodb.com/manual/reference/operator/query/ +.. _Lucene query syntax: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax + Example Request +++++++++++++++ @@ -1209,6 +1219,342 @@ Example Request $ curl -XDELETE http://localhost:8080/blackout/c17832d4-c477-4eb1-b2d5-662e7a3600be \ -H 'Authorization: Key demo-key' + +.. _filters: + +Filters +------- + +Create a filter +~~~~~~~~~~~~~~~ + +Creates a filter + +:: + + POST /filter + +Input ++++++ + + ++-----------------+----------+----------------------------------------------+ +| Name | Type | Description | ++=================+==========+==============================================+ +| ``environment`` | string | **Required** | ++-----------------+----------+----------------------------------------------+ +| ``resource`` | string | | ++-----------------+----------+----------------------------------------------+ +| ``service`` | list | | ++-----------------+----------+----------------------------------------------+ +| ``event`` | string | | ++-----------------+----------+----------------------------------------------+ +| ``group`` | string | | ++-----------------+----------+----------------------------------------------+ +| ``tags`` | list | | ++-----------------+----------+----------------------------------------------+ +| ``type`` | string | **Required** name of the filter | ++-----------------+----------+----------------------------------------------+ +| ``attributes`` | dict | **Required** parameters used by filter | ++-----------------+----------+----------------------------------------------+ + +Example Request ++++++++++++++++ + +.. code-block:: bash + + curl -XPOST http://localhost:8080/filter \ + -H 'Authorization: Key demo-key' \ + -H 'Content-type: application/json' \ + -d '{ + "environment": "Production", + "service": ["example.com"], + "type": "delay", + "attributes": { + "timeout": 60 + } + }' + +Example Request ++++++++++++++++ + +:: + + 201 CREATED + +.. code-block:: json + + { + "filter": { + "createTime": "2021-11-26T07:53:03.946Z", + "customer": null, + "environment": "Production", + "event": null, + "attributes": { + "timeout": "300" + }, + "type": "delay", + "group": null, + "href": "http://localhost:8080/filter/03b5b392-7faf-44a3-a239-741ae2107b6f", + "id": "03b5b392-7faf-44a3-a239-741ae2107b6f", + "priority": 3, + "resource": null, + "service": [ + "example.com" + ], + "tags": [], + "text": null, + "user": "admin@alerta.io" + }, + "id": "03b5b392-7faf-44a3-a239-741ae2107b6f", + "status": "ok" + } + +.. _get_filters: + +List all filters +~~~~~~~~~~~~~~~~~ + +Returns a list of filters + +:: + + GET /filters + +Example Request ++++++++++++++++ + +.. code-block:: bash + + $ curl http://localhost:8080/filters \ + -H 'Authorization: Key demo-key' + +Example Response +++++++++++++++++ + +:: + + 200 OK + +.. code-block:: json + + { + "filters": [ + { + "createTime": "2021-11-26T07:53:03.946Z", + "customer": null, + "environment": "Production", + "event": null, + "attributes": { + "timeout": "300" + }, + "type": "delay", + "group": null, + "href": "http://localhost:8080/filter/03b5b392-7faf-44a3-a239-741ae2107b6f", + "id": "03b5b392-7faf-44a3-a239-741ae2107b6f", + "priority": 3, + "resource": null, + "service": [ + "example.com" + ], + "tags": [], + "text": null, + "user": "admin@alerta.io" + } + ], + "more": false, + "page": 1, + "pageSize": 10000, + "pages": 1, + "status": "ok", + "total": 1 + } + +.. _search_filters: + +Search filters +~~~~~~~~~~~~~~ + +Returns a filtered list of filters. See :ref:`query syntax ` + +:: + + GET /filters + +Example Request ++++++++++++++++ + +.. code-block:: bash + + $ curl http://localhost:8080/filters?q=type:delay \ + -H 'Authorization: Key demo-key' + +Example Response +++++++++++++++++ + +:: + + 200 OK + +.. code-block:: json + + { + "filters": [ + { + "createTime": "2021-11-26T07:53:03.946Z", + "customer": null, + "environment": "Production", + "event": null, + "attributes": { + "timeout": "300" + }, + "type": "delay", + "group": null, + "href": "http://localhost:8080/filter/03b5b392-7faf-44a3-a239-741ae2107b6f", + "id": "03b5b392-7faf-44a3-a239-741ae2107b6f", + "priority": 3, + "resource": null, + "service": [ + "example.com" + ], + "tags": [], + "text": null, + "user": "admin@alerta.io" + } + ], + "more": false, + "page": 1, + "pageSize": 10000, + "pages": 1, + "status": "ok", + "total": 1 + } + +.. _update_filters: + +Update a filter +~~~~~~~~~~~~~~~ + +Update a filter + +:: + + PUT /alert/:id + +Input ++++++ + ++-----------------+----------+----------------------------------------------+ +| Name | Type | Description | ++=================+==========+==============================================+ +| ``environment`` | string | **Required** | ++-----------------+----------+----------------------------------------------+ +| ``resource`` | string | | ++-----------------+----------+----------------------------------------------+ +| ``service`` | list | | ++-----------------+----------+----------------------------------------------+ +| ``event`` | string | | ++-----------------+----------+----------------------------------------------+ +| ``group`` | string | | ++-----------------+----------+----------------------------------------------+ +| ``tags`` | list | | ++-----------------+----------+----------------------------------------------+ +| ``type`` | string | **Required** name of the filter | ++-----------------+----------+----------------------------------------------+ +| ``attributes`` | dict | | ++-----------------+----------+----------------------------------------------+ + +Example Request ++++++++++++++++ + +.. code-block:: bash + + $ curl -XPUT http://localhost:8080/filter/03b5b392-7faf-44a3-a239-741ae2107b6f \ + -H 'Authorization: Key demo-key' \ + -H 'Content-type: application/json' \ + -d '{ + "environment": "Production", + "service": ["example.com"], + "tags": ["dc1", "dc2"], + "type": "delay", + "attributes": { + "timeout": 30 + } + }' + +Example Response +++++++++++++++++ + +:: + + 200 OK + +.. code-block:: json + + { + "filter": { + "createTime": "2021-11-26T07:53:03.946Z", + "customer": null, + "environment": "Production", + "event": null, + "attributes": { + "timeout": 30 + }, + "type": "delay", + "group": null, + "href": "http://localhost:8080/filter/03b5b392-7faf-44a3-a239-741ae2107b6f", + "id": "03b5b392-7faf-44a3-a239-741ae2107b6f", + "priority": 3, + "resource": null, + "service": [ + "example.com" + ], + "tags": [ + "dc1", + "dc2" + ], + "text": null, + "user": "admin@alerta.io" + }, + "status": "ok" + } + + + + + +.. _delete_filters: + +Delete a filter +~~~~~~~~~~~~~~~~ + +Deletes a filter + +:: + + DELETE /filter/:id + +Example Request +++++++++++++++++ + +.. code-block:: bash + + $ curl -XDELETE http://localhost:8080/filter/4f8f477a-a51e-4a1f-a033-fea0cd500812 \ + -H 'Authorization: Key demo-key' + +Example Response ++++++++++++++++++ + +:: + + 200 OK + +.. code-block:: json + + { + "status": "ok" + } + .. _heartbeats: Heartbeats @@ -1276,32 +1622,32 @@ Example Response { "heartbeat": { "attributes": { - "environment": "Production", - "group": "Network", + "environment": "Production", + "group": "Network", "service": [ - "Core", + "Core", "HA" - ], + ], "severity": "major" - }, - "createTime": "2020-06-07T20:31:58.244Z", - "customer": null, - "href": "http://localhost:8080/heartbeat/ea2f41e3-16c4-412f-aaf2-874e3c4c771b", - "id": "ea2f41e3-16c4-412f-aaf2-874e3c4c771b", - "latency": 0, - "maxLatency": 2000, - "origin": "cluster05", - "receiveTime": "2020-06-07T20:31:58.244Z", - "since": 0, - "status": "ok", + }, + "createTime": "2020-06-07T20:31:58.244Z", + "customer": null, + "href": "http://localhost:8080/heartbeat/ea2f41e3-16c4-412f-aaf2-874e3c4c771b", + "id": "ea2f41e3-16c4-412f-aaf2-874e3c4c771b", + "latency": 0, + "maxLatency": 2000, + "origin": "cluster05", + "receiveTime": "2020-06-07T20:31:58.244Z", + "since": 0, + "status": "ok", "tags": [ - "db05", + "db05", "dc2" - ], - "timeout": 120, + ], + "timeout": 120, "type": "Heartbeat" - }, - "id": "ea2f41e3-16c4-412f-aaf2-874e3c4c771b", + }, + "id": "ea2f41e3-16c4-412f-aaf2-874e3c4c771b", "status": "ok" } @@ -1334,32 +1680,32 @@ Example Response { "heartbeat": { "attributes": { - "environment": "Production", - "group": "Network", + "environment": "Production", + "group": "Network", "service": [ - "Core", + "Core", "HA" - ], + ], "severity": "major" - }, - "createTime": "2020-06-07T20:31:58.244Z", - "customer": null, - "href": "http://localhost:8080/heartbeat/ea2f41e3-16c4-412f-aaf2-874e3c4c771b", - "id": "ea2f41e3-16c4-412f-aaf2-874e3c4c771b", - "latency": 0, - "maxLatency": 2000, - "origin": "cluster05", - "receiveTime": "2020-06-07T20:31:58.244Z", - "since": 91, - "status": "ok", + }, + "createTime": "2020-06-07T20:31:58.244Z", + "customer": null, + "href": "http://localhost:8080/heartbeat/ea2f41e3-16c4-412f-aaf2-874e3c4c771b", + "id": "ea2f41e3-16c4-412f-aaf2-874e3c4c771b", + "latency": 0, + "maxLatency": 2000, + "origin": "cluster05", + "receiveTime": "2020-06-07T20:31:58.244Z", + "since": 91, + "status": "ok", "tags": [ - "db05", + "db05", "dc2" - ], - "timeout": 120, + ], + "timeout": 120, "type": "Heartbeat" - }, - "status": "ok", + }, + "status": "ok", "total": 1 } @@ -1395,33 +1741,33 @@ Example Response "heartbeats": [ { "attributes": { - "environment": "Production", - "group": "Network", + "environment": "Production", + "group": "Network", "service": [ - "Core", + "Core", "HA" - ], + ], "severity": "major" - }, - "createTime": "2020-06-07T20:31:58.244Z", - "customer": null, - "href": "http://localhost:8080/heartbeat/ea2f41e3-16c4-412f-aaf2-874e3c4c771b", - "id": "ea2f41e3-16c4-412f-aaf2-874e3c4c771b", - "latency": 0, - "maxLatency": 2000, - "origin": "cluster05", - "receiveTime": "2020-06-07T20:31:58.244Z", - "since": 136, - "status": "expired", + }, + "createTime": "2020-06-07T20:31:58.244Z", + "customer": null, + "href": "http://localhost:8080/heartbeat/ea2f41e3-16c4-412f-aaf2-874e3c4c771b", + "id": "ea2f41e3-16c4-412f-aaf2-874e3c4c771b", + "latency": 0, + "maxLatency": 2000, + "origin": "cluster05", + "receiveTime": "2020-06-07T20:31:58.244Z", + "since": 136, + "status": "expired", "tags": [ - "db05", + "db05", "dc2" - ], - "timeout": 120, + ], + "timeout": 120, "type": "Heartbeat" } - ], - "status": "ok", + ], + "status": "ok", "total": 1 } diff --git a/auth/customers.rst b/auth/customers.rst new file mode 100644 index 00000000..e69de29b diff --git a/auth/introduction.rst b/auth/introduction.rst new file mode 100644 index 00000000..139597f9 --- /dev/null +++ b/auth/introduction.rst @@ -0,0 +1,2 @@ + + diff --git a/auth/ldap.rst b/auth/ldap.rst new file mode 100644 index 00000000..e69de29b diff --git a/auth/openid.rst b/auth/openid.rst new file mode 100644 index 00000000..e69de29b diff --git a/auth/proxy.rst b/auth/proxy.rst new file mode 100644 index 00000000..e69de29b diff --git a/auth/roles.rst b/auth/roles.rst new file mode 100644 index 00000000..e69de29b diff --git a/authentication.rst b/authentication.rst index efb30b7d..07af08b5 100644 --- a/authentication.rst +++ b/authentication.rst @@ -4,8 +4,7 @@ Authentication ============== By default, authentication is not enabled, however there are some features -that are :ref:`not available ` unless users login such as -watching alerts. +that are not available unless users login such as watching alerts. Alerta supports five main authentication strategies: @@ -158,7 +157,7 @@ SAML 2.0 To use SAML as the authentication provider for Alerta, install `PySAML2`_ on the Alerta server and follow the configuration steps below. -.. _PySAML2: https://pysaml2.readthedocs.io +.. _PySAML2: https://pysaml2.readthedocs.io/en/latest/ :: @@ -197,9 +196,9 @@ Bare-minimum config example:: Refer to pysaml2 documentation and source code if you need additional options: - https://pysaml2.readthedocs.io/en/latest/howto/config.html -- https://github.com/rohe/pysaml2/blob/master/src/saml2/config.py +- https://github.com/IdentityPython/pysaml2/blob/master/src/saml2/config.py -Note: entityid and service provider endpoints are configured by default based on your BASE_URL value which is mandatory if you use SAML (see :ref:`general config`) +Note: entityid and service provider endpoints are configured by default based on your BASE_URL value which is mandatory if you use SAML (see :ref:`general_config`) ``ALLOWED_SAML2_GROUPS`` @@ -281,7 +280,7 @@ To use GitHub as the OAuth2 provider for Alerta, login to GitHub and go to *Settings -> Applications -> Register New Application*. - Application Name: Alerta -- Homepage URL: http://alerta.io +- Homepage URL: https://alerta.io/ - Application description (optional): Guardian Alerta monitoring system - Authorization callback URL: http://alerta.example.com @@ -303,7 +302,7 @@ To restrict access to users who are members of particular ALLOWED_GITHUB_ORGS = ['example', 'mycompany'] -.. _`GitHub organisations`: https://github.com/blog/674-introducing-organizations +.. _`GitHub organisations`: https://github.blog/2010-06-29-introducing-organizations/ .. note:: ``ALLOWED_GITHUB_ORGS`` can be an asterisk (``*``) to force login but *not* restrict who can login. @@ -322,7 +321,7 @@ To restrict access to users who are members of particular OIDC Providers -------------- -OpenID Connect authentication is provided by Google_ `OAuth2`_, +OpenID Connect authentication is provided by Google_ `OAuth 2.0`_, GitLab_ `OAuth 2.0`_ or Keycloak_ `OAuth 2.0`_ and configuration is more involved than the Basic Auth setup. @@ -332,10 +331,10 @@ involved than the Basic Auth setup. ensure that only authorised users can access and modify your alerts. -.. _Google: https://developers.google.com/accounts/docs/OpenIDConnect -.. _GitLab: https://docs.gitlab.com/ce/integration/oauth_provider.html +.. _Google: https://developers.google.com/identity/protocols/oauth2/openid-connect +.. _GitLab: https://docs.gitlab.com/ee/integration/oauth_provider.html .. _Keycloak: https://www.keycloak.org/documentation.html -.. _OAuth 2.0: http://tools.ietf.org/html/draft-ietf-oauth-v2-22 +.. _OAuth 2.0: https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-22 .. _OpenID Connect: http://openid.net/connect/ Ensure ``AUTH_REQUIRED`` and ``SECRET_KEY`` are set and that the @@ -354,7 +353,7 @@ To use `Azure Active Directory`_ (now known as `Microsoft identity platform (v2. the OpenID Connect authentication provider for Alerta follow the steps below. #. Login to Azure portal - https://portal.azure.com/ + https://portal.azure.com/Error/UE_404?aspxerrorpath=/ #. Navigate to "Azure Active Directory" service page @@ -404,7 +403,7 @@ the OpenID Connect authentication provider for Alerta follow the steps below. OAUTH2_CLIENT_SECRET = 'jj2cw7~nc1.55l3.UAy8C3O9Ng-.~GYWYp' .. _Azure Active Directory: https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-protocols-oidc -.. _Microsoft identity platform (v2.0): https://docs.microsoft.com/en-us/azure/active-directory/develop/about-microsoft-identity-platform +.. _Microsoft identity platform (v2.0): https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-overview Amazon Cognito ~~~~~~~~~~~~~~ @@ -464,7 +463,7 @@ Google OAuth2 To use Google as the OAuth2 provider for Alerta, login to the `Google Developer Console`_ and create a new project for alerta. -.. _Google Developer Console: https://console.developers.google.com +.. _Google Developer Console: https://accounts.google.com/ServiceLogin?service=cloudconsole&passive=1209600&osid=1&continue=https://console.developers.google.com/&followup=https://console.developers.google.com/ - Project Name: alerta - Project ID: (automatically assigned) @@ -514,11 +513,13 @@ To restrict access to users with particular `Google apps domains`_ use:: ALLOWED_EMAIL_DOMAINS = ['example.org', 'mycompany.com'] -.. _`Google apps domains`: https://www.google.co.uk/intx/en_au/work/apps/business/ +.. _`Google apps domains`: https://workspace.google.com/index.html .. note:: ``ALLOWED_EMAIL_DOMAINS`` can be an asterisk (``*``) to force login but *not* restrict who can login. +.. _keycloak oauth2: + Keycloak OAuth2 ~~~~~~~~~~~~~~~ @@ -527,7 +528,7 @@ to *Clients -> Create*. - Client ID: alerta-ui - Client protocol: openid-connect -- Root URL: http://alerta.example.org +- Root URL: http://alerta.example.com After the client is created, edit it and change the following properties: @@ -570,7 +571,7 @@ To restrict access to users who are associated with a particular `Keycloak role` ALLOWED_KEYCLOAK_ROLES = ['role1', 'role2'] -.. _`Keycloak role`: https://keycloak.gitbooks.io/documentation/server_admin/topics/roles.html +.. _`Keycloak role`: https://www.keycloak.org/docs/latest/server_admin/#assigning-permissions-and-access-using-roles-and-groups .. note:: ``ALLOWED_KEYCLOAK_ROLES`` can be an asterisk (``*``) to force login but *not* restrict who can login. @@ -596,7 +597,7 @@ the command-line tool. Keys can be easily generated from the Alerta web UI and can have any scopes associated with them. They are valid for 1 year by default but this period is configurable using ``API_KEY_EXPIRE_DAYS`` in the -:ref:`server configuration `. +:ref:`server configuration `. To use an API key in an API query you must put the key in either an HTTP header or a query parameter. diff --git a/authorization.rst b/authorization.rst index bd08aba7..7fde5e5e 100644 --- a/authorization.rst +++ b/authorization.rst @@ -8,7 +8,7 @@ authorization model is based on `Role-Based Access Control`_ (RBAC) which assigns permissions to functional roles and then users are assigned to one or more of those roles. -.. _`Role-Based Access Control`: http://csrc.nist.gov/groups/SNS/rbac/faq.html +.. _`Role-Based Access Control`: https://csrc.nist.gov/projects/role-based-access-control/faqs This "role-based access" allows for fine-grained control over exactly what resources are accessible to which users and exactly what type of @@ -207,7 +207,7 @@ The following example configuration can be used to log all ``admin``, forward the events to the Loggly_ "logging-as-a-service" endpoint, replacing ``TOKEN`` in the Loggly URL with your customer token. -.. _Loggly: https://www.loggly.com/docs/http-endpoint/ +.. _Loggly: https://documentation.solarwinds.com/en/success_center/loggly/content/admin/http-endpoint.htm?cshid=loggly_http-endpoint .. code:: python diff --git a/cli.rst b/cli.rst index e4e7a468..919947df 100644 --- a/cli.rst +++ b/cli.rst @@ -183,7 +183,7 @@ be set to sensible defaults. default) then alerts must have an ``environment`` attribute that is one of either ``Production`` or ``Development`` and it must define a ``service`` attribute. For more information on configuring - or disabling this plugin see :ref:`plugin config`. + or disabling this plugin see :ref:`plugin settings`. +------------------+-----------------------+ | Attribute | Default | @@ -317,12 +317,12 @@ The following group of commands are related to creating and managing alert suppressions using blackouts. :command:`blackout` - Suppress alerts -+++++++++++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++++++++++ blackout Suppress alerts :command:`blackouts` - List alert suppressions -+++++++++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++++++++++++++++++++++ blackouts List alert suppressions @@ -414,12 +414,12 @@ managing API keys. has. :command:`keys` - List API keys -+++++++++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++++++ keys List API keys :command:`revoke` - Revoke API key -+++++++++++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++++++ revoke Revoke API key @@ -430,12 +430,12 @@ The following group of commands are related to creating and managing users. :command:`user` - Update user -+++++++++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++++ user Update user :command:`users` - List users -+++++++++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++++ users List users @@ -451,12 +451,12 @@ The following group of commands are related to creating and managing roles, permissions and access control. :command:`perm` - Add role-permission lookup -+++++++++++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++++++++++++++++ perm Add role-permission lookup :command:`perms` - List role-permission lookups -+++++++++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++++++++++++++++++++++ perms List role-permission lookups @@ -467,12 +467,12 @@ The following group of commands are related to creating and managing customers. :command:`customer` - Add customer lookup -+++++++++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++++++++++++++++ customer Add customer lookup :command:`customers` - List customer lookups -+++++++++++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++++++++++++++++ customers List customer lookups @@ -482,27 +482,27 @@ Auth Commands The following group of commands are related to authentication. :command:`signup` - Sign-up new user -+++++++++++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++++++++ signup Sign-up new user :command:`login` - Login with user credentials -+++++++++++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++++++++++++++++++ login Login with user credentials :command:`logout` - Clear login credentials -+++++++++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++++++++++++++++++ logout Clear login credentials :command:`whoami` - Display current logged in user -+++++++++++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++++++++++++++++++++++ whoami Display current logged in user :command:`token` - Display current auth token -+++++++++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++++++++++++++++++++ token Display current auth token @@ -511,6 +511,8 @@ Admin Commands The following group of commands are related to administration. +.. _cli_status: + :command:`status` - Display status and metrics ++++++++++++++++++++++++++++++++++++++++++++++ @@ -604,5 +606,5 @@ Bugs Log any issues on `GitHub`_ or submit a `pull request`_. -.. _`github`: https://github.com/alerta/python-alerta/issues -.. _`pull request`: https://github.com/alerta/python-alerta/pulls +.. _`github`: https://github.com/alerta/python-alerta-client/issues +.. _`pull request`: https://github.com/alerta/python-alerta-client/pulls diff --git a/conf.py b/conf.py index fffdb217..0978740c 100644 --- a/conf.py +++ b/conf.py @@ -283,3 +283,16 @@ 'travis_button': False, 'donate_url': 'https://github.com/sponsors/satterly' } + +# -- Options for linkchecker -------------------------------------------------------- + +linkcheck_ignore = [ + r'https?://localhost:\d+/?', + r'https?://alerta.example.com/?', + r'https://github.com/.*#L', + 'https://github.com/alerta/alerta#cloud-deployment', + 'https://github.com/alerta/angular-alerta-webui#deploy-to-the-cloud', + 'https://docs.angularjs.org/guide/module#registration-in-the-config-block', + 'https://github.com/alerta/docker-alerta/blob/master/README.md#environment-variables', + 'https://documentation.solarwinds.com/en/success_center/pingdom/default.htm#cshid=pd-rd_gen' +] diff --git a/configuration.rst b/configuration.rst index 2e205ccd..289ec4ea 100644 --- a/configuration.rst +++ b/configuration.rst @@ -126,7 +126,7 @@ API Settings ``HISTORY_ON_VALUE_CHANGE`` create history entry for duplicate alerts if value changes (default is ``True``) -.. _`ANSI/ISA 18.2 alarm model`: https://www.isa.org/standards-and-publications/isa-publications/intech-magazine/white-papers/pas-understanding-and-applying-ansi-isa-18-2-alarm-management-standard/ +.. _`ANSI/ISA 18.2 alarm model`: https://www.isa.org/getmedia/55b4210e-6cb2-4de4-89f8-2b5b6b46d954/PAS-Understanding-ISA-18-2.pdf .. _search_config: @@ -152,6 +152,7 @@ Database Settings There is a choice of either Postgres or MongoDB as the backend database. .. note:: + Development first began using MongoDB and then Postgres support was added later. At present, new features are tested against Postgres first and then ported to MongoDB. Both backends have extensive tests @@ -161,6 +162,9 @@ There is a choice of either Postgres or MongoDB as the backend database. The database is defined using the standard database connection URL formats. Many database configuration options are supported as connection URL parameters. + +.. _postgres config example: + **Postgres Example** .. code:: python @@ -170,7 +174,9 @@ database configuration options are supported as connection URL parameters. See `Postgres connection strings`_ for more information. -.. _Postgres connection strings: https://www.postgresql.org/docs/9.6/static/libpq-connect.html +.. _Postgres connection strings: https://www.postgresql.org/docs/9.6/libpq-connect.html + +.. _mongodb config example: **MongoDB Example** @@ -182,7 +188,7 @@ See `Postgres connection strings`_ for more information. See `MongoDB connection strings`_ for more information. -.. _MongoDB connection strings: https://docs.mongodb.org/v3.0/reference/connection-string/#standard-connection-string-format +.. _MongoDB connection strings: https://docs.mongodb.com/v3.0/reference/connection-string/#standard-connection-string-format .. index:: DATABASE_URL, DATABASE_NAME, DATABASE_RAISE_ON_ERROR @@ -273,7 +279,9 @@ Auth Provider Settings valid authentication providers are ``basic``, ``ldap``, ``openid``, ``saml2``, ``azure``, ``cognito``, ``github``, ``gitlab``, ``google``, ``keycloak``, and ``pingfederate`` (default is ``basic``) + .. note:: + Any authentication provider that is `OpenID Connect compliant`_ is supported. Set the ``AUTH_PROVIDER`` to ``openid`` and configure the required ``OIDC`` settings :ref:`below `. @@ -369,13 +377,13 @@ SAML 2.0 Auth Settings (no default) ``SAML2_USER_NAME_FORMAT`` Python format string which will be rendered to user's name using SAML - attributes. See :ref:`saml2` (default is ``'{givenName} {surname}'``) + attributes. See :ref:`saml2_auth` (default is ``'{givenName} {surname}'``) ``SAML2_EMAIL_ATTRIBUTE`` (default is ``'emailAddress'``) ``SAML2_CONFIG`` - ``pysaml2`` configuration ``dict``. See :ref:`saml2` (no default) + ``pysaml2`` configuration ``dict``. See :ref:`saml2_auth` (no default) ``ALLOWED_SAML2_GROUPS`` - list of authorised groups a user must belong to. See :ref:`saml2` for + list of authorised groups a user must belong to. See :ref:`saml2_auth` for details (default is ``*``) ``ALLOWED_EMAIL_DOMAINS`` authorised email domains when using email as login (default is ``*``) @@ -500,7 +508,7 @@ HMAC Auth Settings ``HMAC_AUTH_CREDENTIALS`` HMAC credentials -.. _Audit Log config: +.. _Audit Log settings: Audit Log Settings ~~~~~~~~~~~~~~~~~~ @@ -532,7 +540,7 @@ using a POST. ``AUDIT_URL`` forward audit logs to HTTP POST URL (no default) -.. _CORS config: +.. _CORS settings: CORS Settings ~~~~~~~~~~~~~ @@ -552,7 +560,7 @@ CORS Settings ``CORS_ORIGINS`` URL origins that can access the API for Cross-Origin Resource Sharing (CORS) -.. _severity config: +.. _severity settings: Severity Settings ~~~~~~~~~~~~~~~~~ @@ -598,7 +606,7 @@ in which Alerta is deployed. ``COLOR_MAP`` dictionary of severity colors, text and highlight color -.. _timeout config: +.. _timeout settings: Timeout Settings ~~~~~~~~~~~~~~~~ @@ -627,7 +635,7 @@ are important for generating alerts from stale heartbeats. ``SHELVE_TIMEOUT`` timeout period for unshelving alerts in shelved status (default is ``7200`` seconds, ``0`` = do not auto-unshelve) -.. _housekeeping config: +.. _housekeeping settings: Housekeeping Settings ~~~~~~~~~~~~~~~~~~~~~ @@ -648,7 +656,7 @@ Housekeeping Settings .. note:: Ensure to set ``DEFAULT_INFORM_SEVERITY`` to the "informational" severity that should be deleted. -.. _email config: +.. _email settings: Email Settings ~~~~~~~~~~~~~~ @@ -692,7 +700,7 @@ email address before they can login. ``SMTP_PASSWORD`` application-specific password for ``MAIL_FROM`` or ``SMTP_USERNAME`` (no default) -.. _webui config: +.. _webui settings: Web UI Settings ~~~~~~~~~~~~~~~ @@ -773,7 +781,7 @@ Alert Status Indicator Settings ``ASI_QUERIES`` list of alert queries applied to filter status indicators (see example for default) -.. _plugin config: +.. _plugin settings: Plugin Settings ~~~~~~~~~~~~~~~~ @@ -887,7 +895,7 @@ Alerts and actions can be forwarded to other Alerta servers to create a $ date | md5 | base64 <= create HMAC "secret" MzVlMzQ5NWYzYWE2YTgxYTUyYmIyNDY0ZWE2ZWJlYTMK -.. _webhook config: +.. _webhook settings: Webhook Settings ~~~~~~~~~~~~~~~~ @@ -918,20 +926,20 @@ General Settings ~~~~~~~~~~~~~~~~ :envvar:`DEBUG` - :ref:`see above ` + :ref:`see above ` :envvar:`BASE_URL` - :ref:`see above ` + :ref:`see above ` :envvar:`USE_PROXYFIX` - :ref:`see above ` + :ref:`see above ` :envvar:`SECRET_KEY` - :ref:`see above ` + :ref:`see above ` Database Settings ~~~~~~~~~~~~~~~~~ :envvar:`DATABASE_URL` - used by both :ref:`Postgres ` and - :ref:`MongoDB ` for database connection strings + used by both :ref:`Postgres ` and + :ref:`MongoDB ` for database connection strings :envvar:`DATABASE_NAME` database name can be used to override default database defined in ``DATABASE_URL`` @@ -952,7 +960,7 @@ MongoDB Settings :envvar:`MONGO_PORT` automatically set when deploying `Alerta to a Docker`_ linked mongo container -.. _Heroku MongoHQ: https://devcenter.heroku.com/articles/mongohq +.. _Heroku MongoHQ: https://devcenter.heroku.com/articles/ormongo .. _Heroku MongoLab: https://devcenter.heroku.com/articles/mongolab .. _Alerta to a Docker: https://github.com/alerta/docker-alerta @@ -960,81 +968,81 @@ Authentication Settings ~~~~~~~~~~~~~~~~~~~~~~~ :envvar:`AUTH_REQUIRED` - :ref:`see above ` + :ref:`see above ` :envvar:`AUTH_PROVIDER` - :ref:`see above ` + :ref:`see above ` :envvar:`ADMIN_USERS` - :ref:`see above ` + :ref:`see above ` :envvar:`SIGNUP_ENABLED` - :ref:`see above ` + :ref:`see above ` :envvar:`CUSTOMER_VIEWS` - :ref:`see above ` + :ref:`see above ` :envvar:`OAUTH2_CLIENT_ID` - :ref:`see above ` + :ref:`see above ` :envvar:`OAUTH2_CLIENT_SECRET` - :ref:`see above ` + :ref:`see above ` :envvar:`ALLOWED_EMAIL_DOMAINS` - :ref:`see above ` + :ref:`see above ` :envvar:`AZURE_TENANT` - :ref:`see above ` + :ref:`see above ` :envvar:`GITHUB_URL` - :ref:`see above ` + :ref:`see above ` :envvar:`ALLOWED_GITHUB_ORGS` - :ref:`see above ` + :ref:`see above ` :envvar:`GITLAB_URL` - :ref:`see above ` + :ref:`see above ` :envvar:`ALLOWED_GITLAB_GROUPS` - :ref:`see above ` + :ref:`see above ` :envvar:`KEYCLOAK_URL` - :ref:`see above ` + :ref:`see above ` :envvar:`KEYCLOAK_REALM` - :ref:`see above ` + :ref:`see above ` :envvar:`ALLOWED_KEYCLOAK_ROLES` - :ref:`see above ` + :ref:`see above ` :envvar:`LDAP_BIND_PASSWORD` - :ref:`see above ` + :ref:`see above ` :envvar:`OIDC_ISSUER_URL` - :ref:`see above ` + :ref:`see above ` :envvar:`ALLOWED_OIDC_ROLES` - :ref:`see above ` + :ref:`see above ` Sundry Settings ~~~~~~~~~~~~~~~ :envvar:`CORS_ORIGINS` - :ref:`see above ` + :ref:`see above ` :envvar:`MAIL_FROM` - :ref:`see above ` + :ref:`see above ` :envvar:`SMTP_PASSWORD` - :ref:`see above ` + :ref:`see above ` :envvar:`GOOGLE_TRACKING_ID` - :ref:`see above ` + :ref:`see above ` Housekeeping Settings ~~~~~~~~~~~~~~~~~~~~~ :envvar:`DELETE_EXPIRED_AFTER` - :ref:`see above ` + :ref:`see above ` :envvar:`DELETE_INFO_AFTER` - :ref:`see above ` + :ref:`see above ` Plugin & Webhook Settings ~~~~~~~~~~~~~~~~~~~~~~~~~ :envvar:`PLUGINS` - :ref:`see above ` + :ref:`see above ` :envvar:`BLACKOUT_DURATION` - :ref:`see above ` + :ref:`see above ` :envvar:`NOTIFICATION_BLACKOUT` - :ref:`see above ` + :ref:`see above ` :envvar:`BLACKOUT_ACCEPT` - :ref:`see above ` + :ref:`see above ` :envvar:`ORIGIN_BLACKLIST` - :ref:`see above ` + :ref:`see above ` :envvar:`ALLOWED_ENVIRONMENTS` - :ref:`see above ` + :ref:`see above ` :envvar:`DEFAULT_ENVIRONMENT` - :ref:`see above ` + :ref:`see above ` Dynamic Settings ---------------- diff --git a/deployment.rst b/deployment.rst index 2962692c..496bf374 100644 --- a/deployment.rst +++ b/deployment.rst @@ -19,7 +19,7 @@ a WSGI application. This can be fixed by setting ``WSGIPassAuthorization On`` in the configuration file for the site. -.. _always be deployed: http://flask.pocoo.org/docs/1.0/deploying/ +.. _always be deployed: https://flask.palletsprojects.com/en/1.0.x/deploying/ .. _WSGI: http://www.fullstackpython.com/wsgi-servers.html .. _reverse proxy: @@ -38,7 +38,7 @@ reduce the possibility of `mixed content`_ errors when a web application hosted on a HTTP endpoint tries to access resources on an HTTPS endpoint. -.. _mixed content: https://developer.mozilla.org/en-US/docs/Security/MixedContent/How_to_fix_website_with_mixed_content +.. _mixed content: https://developer.mozilla.org/en-US/docs/Web/Security/Mixed_content/How_to_fix_website_with_mixed_content **Example API configuration (extract)** @@ -96,7 +96,7 @@ is from an `Amazon S3 bucket`_ as a static website. **will not work** unless that domain is listed in the ``CORS_ORIGINS`` Alerta API server configuration settings. -.. _Amazon S3 bucket: http://docs.aws.amazon.com/AmazonS3/latest/dev/website-hosting-custom-domain-walkthrough.html +.. _Amazon S3 bucket: https://docs.aws.amazon.com/AmazonS3/latest/userguide/website-hosting-custom-domain-walkthrough.html .. _auth_ssl: @@ -105,12 +105,14 @@ Authentication & SSL Alerta supports several authentication mechanisms for both the API and the web UI and some key features of the web UI, like -:ref:`watching alerts `, are only available if +watching alerts, are only available if authentication is enabled. The API can be secured using :ref:`API keys` and the web UI can -be secured using :ref:`Basic Auth ` or an :ref:`OAuth ` -provider from either GitHub, GitLab, Google, Keycloak or SAML2. +be secured using :ref:`basic_auth` or an provider from either +:ref:`GitHub `, :ref:`GitLab `, +:ref:`Google `, :ref:`Keycloak ` +or :ref:`SAML 2.0 `. If you plan to make the web UI accessible from a public URL it is strongly advised to :ref:`enforce authentication ` @@ -122,7 +124,7 @@ alert data. Authorisation & Customer Views ------------------------------ -To restrict access to certain features use :ref:`roles ` +To restrict access to certain features use roles and :ref:`customer views `. .. _scalability: @@ -151,7 +153,7 @@ deployed to scale out :ref:`horizontally ` and the database should be deployed as a `replica set`_, if using mongoDB, or configure `replication`_, if using Postgres. -.. _replica set: http://docs.mongodb.org/manual/core/replica-set-high-availability/ +.. _replica set: https://docs.mongodb.com/manual/core/replica-set-high-availability/ .. _replication: https://www.postgresql.org/docs/current/high-availability.html .. _housekeeping: @@ -245,10 +247,10 @@ Below are several different examples of how to run Alerta in production from a Debian `vagrant box`_, an `AWS EC2 instance`_, `Heroku PaaS`_ to a `Docker container`_. -.. _vagrant box: https://docs.vagrantup.com/v2/boxes.html +.. _vagrant box: https://www.vagrantup.com/docs/boxes .. _AWS EC2 instance: https://aws.amazon.com/ec2/ .. _Heroku PaaS: https://www.heroku.com/platform -.. _Docker container: https://www.docker.com/whatisdocker +.. _Docker container: https://www.docker.com/why-docker * Vagrant_ - deploy Alerta stand-alone or with Nagios, Zabbix, Riemann, Sensu or Kibana * Heroku_ - deploy the Alerta API and the `web ui to Heroku`_ PaaS @@ -262,13 +264,13 @@ from a Debian `vagrant box`_, an `AWS EC2 instance`_, * Puppet_ - Alerta recipe on top of `cfweb `_ module .. _Vagrant: https://github.com/alerta/vagrant-try-alerta -.. _Heroku: https://github.com/alerta/alerta#deploy-to-the-cloud +.. _Heroku: https://github.com/alerta/alerta#cloud-deployment .. _web UI to Heroku: https://github.com/alerta/angular-alerta-webui#deploy-to-the-cloud .. _AWS EC2: https://github.com/alerta/alerta-cloudformation .. _Docker: https://github.com/alerta/docker-alerta .. _Docker Alpine: https://github.com/bl1nk/docker-alpine-alerta .. _Packer: https://github.com/alerta/packer-templates -.. _Flask deploy: http://flask.pocoo.org/docs/0.10/quickstart/#deploying-to-a-web-server +.. _Flask deploy: https://flask.palletsprojects.com/en/2.0.x/quickstart/#deploying-to-a-web-server .. _Ansible: https://github.com/ramshankarjaiswal/ansible/tree/master/roles/alerta .. _Terraform: https://github.com/aka7/alerta-terraform .. _Puppet: https://github.com/codingfuture/puppet-cfwebapp diff --git a/design.rst b/design.rst index 6178ed28..2bf678b3 100644 --- a/design.rst +++ b/design.rst @@ -25,7 +25,7 @@ for a telco you might want to use the six `ISO perceived severity levels`_ or alternatively, if you are pushing application alerts you might want to consider using the ``debug`` and ``trace`` severity levels. -.. _`ISO perceived severity levels`: http://www.itu.int/rec/T-REC-X.733/en +.. _`ISO perceived severity levels`: https://www.itu.int/rec/T-REC-X.733/en Robust alert reception ---------------------- @@ -38,7 +38,7 @@ however the benefits of following a standard :ref:`convention ` for such attributes as ``environment``, ``service``, ``event`` and ``resource`` (as internally defined by and useful to you) are many. -.. _`robustness principle`: http://en.wikipedia.org/wiki/Robustness_principle +.. _`robustness principle`: https://en.wikipedia.org/wiki/Robustness_principle Self-clearing alerts -------------------- diff --git a/development.rst b/development.rst index b529369c..6ec5a3a7 100644 --- a/development.rst +++ b/development.rst @@ -73,13 +73,6 @@ For more details, visit the `Alerta Python SDK page`_. .. _Alerta Python SDK page: https://github.com/alerta/python-alerta-client -Ruby SDK --------- - -The Ruby SDK is a work-in-progress. For more details, visit the `Alerta Ruby SDK page`_. - -.. _Alerta Ruby SDK page: https://github.com/alerta/alerta-ruby - Haskell SDK ----------- diff --git a/faq.rst b/faq.rst index 09b33871..2cc6a960 100644 --- a/faq.rst +++ b/faq.rst @@ -22,11 +22,11 @@ To fix this you can either serve the web UI from the `same origin`_ as the API using a web server to :ref:`reverse proxy ` the web UI or ensure that the API server `allows the origin`_ where the web UI is hosted by adding it to the :envvar:`CORS_ORIGINS` :ref:`server -configuration ` setting. +configuration ` setting. .. _CORS: https://en.wikipedia.org/wiki/Cross-origin_resource_sharing .. _same origin: https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy -.. _allows the origin: https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Access-Control-Allow-Origin +.. _allows the origin: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#access-control-allow-origin Why do I need to set an ``environment`` and ``service`` when they are not mandatory? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -43,7 +43,7 @@ attribute is for) and so that the web console can organise by ``environemnt`` and filter alerts by ``service``. However, one of the principles of Alerta is not to enforce its view of the -world on users so the plugin can be :ref:`easily configured `, +world on users so the plugin can be :ref:`easily configured `, :ref:`modified ` or completely disabled. It's up to you. Can I define custom severity codes and levels? @@ -101,7 +101,7 @@ What's this MongoDB "ServerSelectionTimeoutError"? With the update to PyMongo 3.x multiprocessing_ applications "parent process and each child process must create their own instances of MongoClient". -.. _multiprocessing: https://api.mongodb.com/python/current/faq.html#multiprocessing +.. _multiprocessing: https://pymongo.readthedocs.io/en/stable/faq.html?highlight=multiprocessing#using-pymongo-with-multiprocessing For Apache WSGI applications, an example Apache "vhost" configuration for the Alerta API would look like this:: @@ -122,10 +122,10 @@ Full examples are available on GitHub_ and more information on why this is necessary is available on stackoverflow_ and the PyMongo where they discussion PyMongo in relation to forking_ and mod_wsgi_ site. -.. _GitHub: https://github.com/search?q=org%3Aalerta+WSGIApplicationGroup&type=Code -.. _stackoverflow: http://stackoverflow.com/questions/31030307/why-is-pymongo-3-giving-serverselectiontimeouterror -.. _forking: https://api.mongodb.com/python/current/faq.html#is-pymongo-fork-safe -.. _mod_wsgi: http://api.mongodb.com/python/current/examples/mod_wsgi.html +.. _GitHub: https://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fsearch%3Fq%3Dorg%253Aalerta%2BWSGIApplicationGroup%26type%3DCode +.. _stackoverflow: https://stackoverflow.com/questions/31030307/why-is-pymongo-3-giving-serverselectiontimeouterror +.. _forking: https://pymongo.readthedocs.io/en/stable/faq.html?highlight=fork#is-pymongo-fork-safe +.. _mod_wsgi: https://pymongo.readthedocs.io/en/stable/examples/mod_wsgi.html#pymongo-and-mod-wsgi Does Alerta support Python 2.7 or Python 3? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -139,7 +139,7 @@ for new production environments and existing installations should be switched to Python 3 well before 1 January, 2020 when Python 2.7 becomes End-of-Life_. .. _last version: https://github.com/alerta/alerta/issues/480 -.. _created: https://github.com/alerta/nagios3-alerta +.. _created: https://github.com/alerta/nagios-alerta .. _many: https://github.com/alerta/alerta/tree/master/alerta/plugins .. _plugins: https://github.com/alerta/alerta-contrib/tree/master/plugins .. _integrations: https://github.com/alerta/alerta-contrib/tree/master/integrations diff --git a/federated.rst b/federated.rst index 9cf1d8b3..17023a72 100644 --- a/federated.rst +++ b/federated.rst @@ -25,7 +25,7 @@ Alerta can be configured to send some or all of the following: .. note:: Forwarding heartbeats is not currently possible but may be supported in a future release. -.. _forwarding_configuration +.. _forwarding configuration: Configuration ------------- @@ -65,7 +65,7 @@ Example ] -.. _forwarding_loops +.. _forwarding loops: Forwarding Loops ---------------- @@ -92,7 +92,7 @@ be skipped. https://qmail.mivzakim.net/qmail-manual-html/misc/RFCLOOPS.html -.. _forwarding_auth +.. _forwarding auth: Authentication -------------- @@ -123,7 +123,7 @@ On macOs, run:: $ date | md5 | base64 <= create HMAC "secret" MzVlMzQ5NWYzYWE2YTgxYTUyYmIyNDY0ZWE2ZWJlYTMK -.. _forwarding_filters +.. _forwarding filters: Forwarding Filters ------------------ @@ -145,7 +145,7 @@ Examples ['alerts', 'ack', 'unack', 'close', 'delete'] ['alerts', 'delete'] -.. _non_alerta_forwarding +.. _non alerta forwarding: Non-Alerta Forwarding --------------------- diff --git a/gettingstarted/tutorial-1-deploy-alerta.rst b/gettingstarted/tutorial-1-deploy-alerta.rst index e234e0bd..ac61a8da 100644 --- a/gettingstarted/tutorial-1-deploy-alerta.rst +++ b/gettingstarted/tutorial-1-deploy-alerta.rst @@ -29,7 +29,7 @@ Customisation will involve defining a new alert severity called environment called "Code" in addition to "Production" and "Development". .. _`Ubuntu 18.04 LTS (Bionic Beaver)`: https://wiki.ubuntu.com/BionicBeaver/ReleaseNotes -.. _uWsgi: https://uwsgi-docs.readthedocs.io +.. _uWsgi: https://uwsgi-docs.readthedocs.io/en/latest/ .. _nginx: https://www.nginx.com Prerequisites @@ -127,13 +127,14 @@ Create a ``systemd`` configuration file for the uwsgi server:: WantedBy=multi-user.target Start the uwsgi server, check the current status and enable it to start -on reboot:: +on reboot + +:: $ sudo service start uwsgi $ sudo service status uwsgi $ sudo service enable uwsgi -:: Configure nginx to serve Alerta as a uWsgi application on ``/api`` and the web console as static assets. diff --git a/gettingstarted/tutorial-10-docker.rst b/gettingstarted/tutorial-10-docker.rst index 54e5d60b..74b891bb 100644 --- a/gettingstarted/tutorial-10-docker.rst +++ b/gettingstarted/tutorial-10-docker.rst @@ -18,7 +18,6 @@ Docker_. * `Step 4: Install additional plugins or webhooks`_ * `Step 5: Complex setups`_ * `Production deployments`_ - * `Debugging and Troubleshooting`_ Overview -------- @@ -320,7 +319,7 @@ Now launch both Alerta and Postgres at the same time using:: $ docker-compose up -And verify by browsing to http://localhost:8080 as before. +And verify by browsing to http://localhost:8080/ as before. You can replace ``environment:`` with ``volumes:`` if you want or need to mount a configuration file into the container, like so: @@ -418,7 +417,7 @@ Now build the new image and run it using:: $ docker-compose up --build -Once again you should be able to browse to http://localhost:8080 and log +Once again you should be able to browse to http://localhost:8080/ and log in to the web console. To verify that the MS Teams webhook is now available, use curl to send a @@ -442,7 +441,7 @@ Step 5: Complex setups Alerta, just like any web service, can be deployed in numerous different ways to suit your environment. Most commonly, it will be deployed behind a reverse proxy (which would be responsible for SSL termination) and perhaps -on a sub-path such as ``/alerta`` (eg. https://monitoring.example.com/alerta/ui) +on a sub-path such as ``/alerta`` (eg. https://alerta.example.com/alerta/ui) It is beyond the scope of this introductory tutorial to step you through every possible scenario however, below is a list of example ``docker-compose`` diff --git a/gettingstarted/tutorial-11-kubernetes.rst b/gettingstarted/tutorial-11-kubernetes.rst index 2f562136..f96c9223 100644 --- a/gettingstarted/tutorial-11-kubernetes.rst +++ b/gettingstarted/tutorial-11-kubernetes.rst @@ -12,13 +12,13 @@ Kubernetes_. * Overview_ * Prerequisites_ - * `Step 1: Run the container`_ - * `Step 2: Customise configuration`_ - * `Step 3: Run using docker-compose`_ - * `Step 4: Install additional plugins or webhooks`_ - * `Step 5: Complex setups`_ - * `Step 6: Production deployments (Bonus)`_ - * `Debugging and Troubleshooting`_ + * Step 1: Run the container + * Step 2: Customise configuration + * Step 3: Run using docker-compose + * Step 4: Install additional plugins or webhooks + * Step 5: Complex setups + * Step 6: Production deployments (Bonus) + * Debugging and Troubleshooting Overview -------- @@ -49,8 +49,8 @@ Prerequisites To follow this tutorial you will need to `install Minikube`_, the "single-node Kubernetes cluster in a virtual machine on your personal computer" which you -will need to complete `Step 6`_ where you mimic deploying to production. +will need to complete Step 6 where you mimic deploying to production. -.. _install Minikube: https://kubernetes.io/docs/tasks/tools/install-minikube/ +.. _install Minikube: https://minikube.sigs.k8s.io/docs/start/ diff --git a/gettingstarted/tutorial-3-plugins.rst b/gettingstarted/tutorial-3-plugins.rst index 184f88a4..0aa0a00f 100644 --- a/gettingstarted/tutorial-3-plugins.rst +++ b/gettingstarted/tutorial-3-plugins.rst @@ -101,7 +101,7 @@ The `base class for plugins`_ has three methods that **must** be implemented and the ``__init__()`` method can optionally be implemented as well as long as the Super class is also called. -.. _base class for plugins: http://docs.openstack.org/developer/stevedore/tutorial/creating_plugins.html#a-plugin-base-class +.. _base class for plugins: https://docs.openstack.org/stevedore/latest/user/tutorial/creating_plugins.html#example-plugin-set .. code-block:: python diff --git a/gettingstarted/tutorial-4-alerts.rst b/gettingstarted/tutorial-4-alerts.rst index 3f467d29..d09abde4 100644 --- a/gettingstarted/tutorial-4-alerts.rst +++ b/gettingstarted/tutorial-4-alerts.rst @@ -97,7 +97,7 @@ The most important part of the above commands were the option is short for "--correlate" and informs the Alerta server that alerts with these events should be correlated together. -Interestingly the de-duplication logic demonstrated in :ref:`Step 1 <>` +Interestingly the de-duplication logic demonstrated in :ref:`Step 1 ` above can be used to produce similar results as this simple correlation. diff --git a/gettingstarted/tutorial-6-auth.rst b/gettingstarted/tutorial-6-auth.rst index e2bbf0c8..67f280d5 100644 --- a/gettingstarted/tutorial-6-auth.rst +++ b/gettingstarted/tutorial-6-auth.rst @@ -19,9 +19,9 @@ This tutorial will ... * Overview_ * Prerequisites_ * `Step 1: Enable Authentication`_ - * `Step 2: Configure Administrators`_ - * `Step 3: Customisation`_ - * `Next Steps`_ + * `Step 2: Basic Auth Configuration`_ + * `Step 3: GitHub Configuration`_ + * `Step 4: API Keys`_ Overview -------- @@ -48,12 +48,6 @@ define roles map users to roles - -Step 4: API Keys ----------------- - - - Step 3: GitHub Configuration ---------------------------- @@ -61,3 +55,7 @@ define admin users define allowed github orgs define roles for orgs + +Step 4: API Keys +---------------- + diff --git a/gettingstarted/tutorial-7-cusomter-views.rst b/gettingstarted/tutorial-7-cusomter-views.rst index 05698465..da502a4c 100644 --- a/gettingstarted/tutorial-7-cusomter-views.rst +++ b/gettingstarted/tutorial-7-cusomter-views.rst @@ -10,15 +10,13 @@ This tutorial will ... * Overview_ * Prerequisites_ * `Step 1: Install Packages`_ - * `Step 2: Configuration`_ - * `Step 3: Customisation`_ - * `Next Steps`_ Overview -------- Customer views and web UI... + Prerequisites ------------- @@ -26,5 +24,4 @@ Prerequisites Step 1: Install Packages ------------------------ - - blackout periods by customer diff --git a/gettingstarted/tutorial-8-integration-nagios.rst b/gettingstarted/tutorial-8-integration-nagios.rst index ef4cc8a7..a53fb378 100644 --- a/gettingstarted/tutorial-8-integration-nagios.rst +++ b/gettingstarted/tutorial-8-integration-nagios.rst @@ -12,9 +12,6 @@ This tutorial will ... * Overview_ * Prerequisites_ * `Step 1: Install Packages`_ - * `Step 2: Configuration`_ - * `Step 3: Customisation`_ - * `Next Steps`_ Overview -------- diff --git a/gettingstarted/tutorial-8-webhooks.rst b/gettingstarted/tutorial-8-webhooks.rst index 63f0a3ce..e5300d9b 100644 --- a/gettingstarted/tutorial-8-webhooks.rst +++ b/gettingstarted/tutorial-8-webhooks.rst @@ -7,7 +7,8 @@ Webhooks * Overview_ * Prerequisites_ - * `Step 1: ` + * `Step 1: Install Packages`_ + * `Next Steps`_ Overview @@ -15,11 +16,14 @@ Overview Integrate Prometheus using webhook. + Prerequisites ------------- -Step 1: ----------------------- + +Step 1: Install Packages +------------------------ + Next Steps ---------- diff --git a/gettingstarted/tutorial-9-troubleshooting.rst b/gettingstarted/tutorial-9-troubleshooting.rst index c30d21dc..9c7698ea 100644 --- a/gettingstarted/tutorial-9-troubleshooting.rst +++ b/gettingstarted/tutorial-9-troubleshooting.rst @@ -20,5 +20,4 @@ Overview * :ref:`Customer Views ` * :ref:`Site-specific bespoke monitoring ` * :ref:`Suppress alerts using Blackouts ` - * :ref:`Web console and command-line tool ` * :ref:`Troubleshooting ` diff --git a/index.rst b/index.rst index b24b73b7..db06af6a 100644 --- a/index.rst +++ b/index.rst @@ -15,8 +15,7 @@ monitoring_ tools_ and it is easy to add your own using the :ref:`API ` directly, the :ref:`Python SDK ` or the same command-line tool to :ref:`send alerts `. Access to the API and command-line tool can be restricted using :ref:`API keys ` and to the web console using -:ref:`Basic Auth ` or :ref:`OAuth2 ` providers Google, -GitHub and GitLab. +:ref:`basic_auth` or OAuth2 providers :ref:`Google `, GitHub and :ref:`GitLab `. .. _popular: https://www.pingdom.com .. _monitoring: https://www.nagios.com @@ -90,7 +89,7 @@ Contribute Support ------- -* Slack: https://slack.alerta.dev +* Slack: https://alerta.slack.com/join/shared_invite/zt-o2p396lz-VYc5zCOdS4pTwIy3hAW0KQ * :ref:`Frequently Asked Questions ` * Issue Tracker: https://github.com/alerta/alerta/issues diff --git a/integrations.rst b/integrations.rst index 9fcd45f6..eb363ef4 100644 --- a/integrations.rst +++ b/integrations.rst @@ -10,7 +10,6 @@ Chronograf Grafana Graylog - Hipchat Kapacitor Nagios Oembed @@ -30,24 +29,24 @@ tools like Nagios_, Zabbix_ and Sensu_ make use of the Alerta API and demonstrat how to build integrations with other monitoring tools. .. _Nagios: https://www.nagios.com -.. _Zabbix: http://www.zabbix.com +.. _Zabbix: https://www.zabbix.com/ .. _Sensu: https://sensuapp.org Secondly, there are built-in :ref:`webhooks ` for `AWS Cloudwatch `_, `Pingdom `_, `PagerDuty `_, -`Google Stackdriver `_, -`Prometheus Alertmanager `_ +`Google Stackdriver `_, +`Prometheus Alertmanager `_ and more which provide 'out-of-the-box' integrations for some of the most popular monitoring systems available. Thirdly, :ref:`alert severity indicators ` or widgets can be placed on any web page using oEmbed_ for easy integration with existing dashboards. -.. _oEmbed: http://oembed.com/ +.. _oEmbed: https://oembed.com/ -Lastly, :ref:`plugins ` can be used to quickly and easily forward alerts -to or notify other systems like Slack or Hipchat. +Lastly, :ref:`plug-ins` can be used to quickly and easily forward alerts +to or notify other systems like Slack. .. contents:: Contents :local: @@ -72,9 +71,9 @@ it is to get alerts or events from other tools into Alerta. They are: * `Kibana Logging`_ - log alerts to Elasticsearch for historical visualisation of alert trends .. _Nagios Event Broker: https://github.com/alerta/nagios-alerta -.. _InfluxData Kapacitor: https://docs.influxdata.com/kapacitor/latest/nodes/alert_node/#alerta +.. _InfluxData Kapacitor: https://docs.influxdata.com/kapacitor/v1.6/nodes/alert_node/#alerta .. _Zabbix Alert Script: https://github.com/alerta/zabbix-alerta -.. _Sensu Plugin: https://github.com/alerta/sensu-alerta +.. _Sensu Plugin: https://github.com/alerta/sensu-alerta-handler .. _Riemann Plugin: https://github.com/alerta/riemann-alerta .. _Kibana Logging: https://github.com/alerta/kibana-alerta @@ -90,18 +89,19 @@ be useful. They are: * Pinger_ - generate ping alerts from list of network resources being pinged * `SNMP Trap`_ - generate alerts from SNMPv1 and SNMPv2 sources * Supervisor_ - trigger alerts and heartbeats based on process deamon events -* `Syslog Forwarder`_ - receive :RFC:`5424`, :RFC:`3164` syslog and Cisco_ syslog messages +* `Syslog Forwarder`_ - receive `5424 `_, `3164 `_ syslog and Cisco_ syslog messages * `URL monitor`_ - trigger alerts from web service query responses .. _contrib: https://github.com/alerta/alerta-contrib .. _Amazon SQS: https://github.com/alerta/alerta-contrib/tree/master/integrations/sqs +.. _AMQP: https://github.com/alerta/alerta-contrib/tree/master/plugins/amqp .. _E-mail: https://github.com/alerta/alerta-contrib/tree/master/integrations/mailer .. _Opsweekly: https://github.com/alerta/alerta-contrib/tree/master/integrations/opsweekly .. _Pinger: https://github.com/alerta/alerta-contrib/tree/master/integrations/pinger .. _SNMP Trap: https://github.com/alerta/alerta-contrib/tree/master/integrations/snmptrap .. _Supervisor: https://github.com/alerta/alerta-contrib/tree/master/integrations/supervisor .. _Syslog Forwarder: https://github.com/alerta/alerta-contrib/tree/master/integrations/syslog -.. _Cisco: http://www.cisco.com/c/en/us/td/docs/routers/access/wireless/software/guide/SysMsgLogging.html +.. _Cisco: https://www.cisco.com/c/en/us/td/docs/routers/access/wireless/software/guide/SysMsgLogging.html .. _URL monitor: https://github.com/alerta/alerta-contrib/tree/master/integrations/urlmon External @@ -114,7 +114,7 @@ Some third-party monitoring tools have built-in support for Alerta. They are: * `Tick Stack`_ - designed to handle metrics and events using Telegraf, InfluxDB, Chronograf, and Kapacitor .. _elastalert: https://elastalert.readthedocs.io/en/latest/ruletypes.html#alerta -.. _netdata: https://github.com/firehol/netdata/wiki/Alerta-monitoring-system +.. _netdata: https://github.com/netdata/netdata/wiki/ .. _Tick Stack: https://docs.influxdata.com/kapacitor/v1.5/event_handlers/alerta/ .. _bidirection integ: @@ -179,7 +179,7 @@ to the Alerta server API when an event occurs. .. Note:: If authentication is enforced, then an API key is needed to access the alerta API programatically and use the webhooks. - Please follow this page for more information on how to pass your api-key : https://docs.alerta.io/en/latest/authentication.html#api-keys + Please follow this page for more information on how to pass your :ref:`API Keys` AWS CloudWatch ~~~~~~~~~~~~~~ @@ -199,7 +199,7 @@ HTTP/HTTPS Endpoints`_ page and in the `Endpoint` input box append :file:`https://alerta.example.com/api/webhooks/cloudwatch?api-key=xxxxx` -.. _Sending Amazon SNS Messages to HTTP/HTTPS Endpoints: http://docs.aws.amazon.com/sns/latest/dg/SendMessageToHttp.html +.. _Sending Amazon SNS Messages to HTTP/HTTPS Endpoints: https://docs.aws.amazon.com/sns/latest/dg/sns-http-https-endpoint-as-subscriber.html Grafana ~~~~~~~ @@ -210,7 +210,7 @@ endpoint to the Notification Channels. For details on how to set this up see `Grafana webhook`_ page and in the `Endpoint URL` input box append :file:`/webhooks/grafana` to the Alerta API URL. -.. _Grafana webhook: http://docs.grafana.org/alerting/notifications/#webhook +.. _Grafana webhook: https://grafana.com/docs/grafana/next/alerting/old-alerting/notifications/#webhook **Example Grafana Webhook URL** @@ -255,15 +255,15 @@ change to the ``status`` or ``assigned_to_user`` of an incident will cause an outgoing message to be sent. For details on how to set this up see the `PagerDuty webhook`_ page and where it -requires the webhook URL append :file:`/webhooks/pagerduty` to the Alerta API URL. +requires the webhook URL append ``/webhooks/pagerduty`` to the Alerta API URL. **Example PagerDuty Webhook URL** -:file:`https://alerta.example.com/api/webhooks/pagerduty` +``https://alerta.example.com/api/webhooks/pagerduty`` **Example PagerDuty Webhook URL with authentication** -:file:`https://alerta.example.com/api/webhooks/pagerduty?api-key=xxxxx` +``https://alerta.example.com/api/webhooks/pagerduty?api-key=xxxxx`` .. _PagerDuty webhook: https://developer.pagerduty.com/documentation/rest/webhooks @@ -274,17 +274,17 @@ Alerta can be configured to receive Pingdom URL check alerts by adding a webhook alerting endpoint that calls the Alerta API. For details on how to set this up see the `Pingdom webhook`_ page and in the -`webhook URL` input box append :file:`/webhooks/pingdom` to the Alerta API URL. +`webhook URL` input box append ``/webhooks/pingdom`` to the Alerta API URL. **Example Pingdom Webhook URL** -:file:`https://alerta.example.com/api/webhooks/pingdom` +``https://alerta.example.com/api/webhooks/pingdom`` **Example Pingdom Webhook URL with authentication** -:file:`https://alerta.example.com/api/webhooks/pingdom?api-key=xxxx` +``https://alerta.example.com/api/webhooks/pingdom?api-key=xxxx`` -.. _Pingdom webhook: https://support.pingdom.com/Knowledgebase/Article/View/94/0/users-and-alerting-end-points +.. _Pingdom webhook: https://documentation.solarwinds.com/en/success_center/pingdom/default.htm#cshid=pd-rd_gen Prometheus Alertmanager ~~~~~~~~~~~~~~~~~~~~~~~ @@ -320,7 +320,7 @@ endpoint to the Notification Preferences. For details on how to set this up see `SeverDensity webhook`_ page and in the `Endpoint URL` input box append :file:`/webhooks/serverdensity` to the Alerta API URL. -.. _SeverDensity webhook: https://support.serverdensity.com/hc/en-us/articles/201017737-Setting-up-webhooks +.. _SeverDensity webhook: https://support.serverdensity.com/hc/en-us/articles/360001067183 **Example SeverDensity Webhook URL** @@ -361,6 +361,7 @@ Alerta can be configured to receive `Telegram callback queries`_ from the inline buttons in the `Telegram Bot`_ plugin. .. _Telegram callback queries: https://core.telegram.org/bots/api#callbackquery +.. _Telegram Bot: https://github.com/alerta/alerta-contrib/tree/master/plugins/telegram For details on how to set this up see `Telegram Bot`_ page and for the ``TELEGRAM_WEBHOOK_URL`` setting append :file:`/webhooks/telegram` to the Alerta API URL. diff --git a/plugins.rst b/plugins.rst index 93b33cf6..4df529b6 100644 --- a/plugins.rst +++ b/plugins.rst @@ -1,4 +1,4 @@ -.. _plugins: +.. _plug-ins: Plug-ins ======== @@ -38,7 +38,6 @@ of the most popular are: * Cachet_ - create incidents for display on Cachet status page * Enhance_ - add new information to an alert based on existing information * `GeoIP Location`_ - use remote IP address to submitted alert to add location data -* HipChat_ - send alerts to HipChat room * InfluxDB_ - send alerts to InfluxDB for graphing with Grafana * `Logstash/Kibana`_ - send alerts to logstash agent after processing * `Normalise`_ - ensure alerts a formatted in a consistent manner @@ -55,7 +54,6 @@ of the most popular are: .. _Cachet: https://github.com/alerta/alerta-contrib/tree/master/plugins/cachet .. _Enhance: https://github.com/alerta/alerta-contrib/tree/master/plugins/enhance .. _`GeoIP Location`: https://github.com/alerta/alerta-contrib/tree/master/plugins/geoip -.. _HipChat: https://github.com/alerta/alerta-contrib/tree/master/plugins/hipchat .. _InfluxDB: https://github.com/alerta/alerta-contrib/tree/master/plugins/influxdb .. _Logstash/Kibana: https://github.com/alerta/alerta-contrib/tree/master/plugins/logstash .. _Normalise: https://github.com/alerta/alerta-contrib/tree/master/plugins/normalise diff --git a/quick-start.rst b/quick-start.rst index 040f8f83..1c100c42 100644 --- a/quick-start.rst +++ b/quick-start.rst @@ -17,11 +17,11 @@ If ``apt-get`` can't locate the "mongodb-org" metapackage package then follow `these steps`_ to add MongoDB package repository to apt sources list. -.. _these steps: https://docs.mongodb.com/manual/tutorial/install-mongodb-on-ubuntu/#using-deb-packages-recommended +.. _these steps: https://docs.mongodb.com/manual/tutorial/install-mongodb-on-ubuntu/ For other operating systems, see the installation_ steps on the MongoDB web site. -.. _installation: https://docs.mongodb.com/master/installation/#tutorials +.. _installation: https://docs.mongodb.com/upcoming/installation/ Install the Alerta Server ------------------------- @@ -62,9 +62,9 @@ To send an alert to the server:: $ alerta send -r web01 -e NodeDown -E Production -S Website -s major -t "Web server is down." -v ERROR The alert should appear almost immediately in the console. If it doesn't it's -either a :ref:`CORS issues ` or a bug_. +either a CORS issues or a bug_. -.. _bug: https://github.com/alerta/alerta-docs/issues/new +.. _bug: https://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Falerta%2Falerta-docs%2Fissues%2Fnew What's next? ------------ diff --git a/release-notes.rst b/release-notes.rst index c17c8101..68bf3aac 100644 --- a/release-notes.rst +++ b/release-notes.rst @@ -155,7 +155,7 @@ Release 5.0.0 (07-10-2017) * WSGI import has changed from `from alerta.app import app` to simply `from alerta import app` * Plugins import has changed from `from alerta.app import app` to `from alerta.plugins import app` * Blackout is now a plugin so it can be disabled and replaced with a custom blackout handler -* Switched to using wheels for distribution via PyPI See http://pythonwheels.com/ +* Switched to using wheels for distribution via PyPI See https://pythonwheels.com/ * Alerta API now supports multiple roles for BasicAuth (though not supported in the web UI yet) * Alert format: `value` is now always cast to a string. * Added `/management/housekeeping` URL to replace `housekeepingAlerts.js` cron job script @@ -171,8 +171,8 @@ Release 4.10 (27-07-2017) * Prometheus webhook updated to support version 4 * Plugin result chaining for tags and attributes -.. _RBAC: http://csrc.nist.gov/groups/SNS/rbac/ -.. _SAML2: https://tools.ietf.org/html/rfc7522 +.. _RBAC: https://csrc.nist.gov/projects/role-based-access-control +.. _SAML2: https://datatracker.ietf.org/doc/html/rfc7522 .. _release_4_9: @@ -184,7 +184,7 @@ Release 4.9 (16-03-2017) * Pingdom webhook changed to use new "State change" webhook .. _Keycloak: https://www.keycloak.org/ -.. _MongoDB SSL: http://api.mongodb.com/python/current/examples/tls.html +.. _MongoDB SSL: https://pymongo.readthedocs.io/en/stable/examples/tls.html .. _release_4_8: @@ -205,7 +205,7 @@ Release 4.8 (05-09-2016) .. _Riemann: http://riemann.io/ .. _Telegram: https://telegram.org/ .. _related plugin: https://github.com/alerta/alerta-contrib/tree/master/plugins/telegram -.. _Grafana: http://grafana.org/ +.. _Grafana: https://grafana.com/ .. _release_4_7: @@ -222,8 +222,8 @@ Release 4.7 (24-01-2016) * Send email confirmation for Basic Auth sign-ups * Removed support for Twitter OAuth1 -.. _Prometheus: http://prometheus.io/docs/alerting/alertmanager/ -.. _Google Stackdriver: https://cloud.google.com/stackdriver/ +.. _Prometheus: https://prometheus.io/docs/alerting/latest/alertmanager/ +.. _Google Stackdriver: https://cloud.google.com/products/operations .. _release_4_6: diff --git a/resources.rst b/resources.rst index 0b9bbe5f..c0621ed3 100644 --- a/resources.rst +++ b/resources.rst @@ -8,7 +8,7 @@ Webinars & Slides `How to avoid failing at failure detection `_ by `Alex Tavgen, Technical Architect at Playtech `_ -`Winning the metrics battle (finally) `_ `[Slides] `_ at `Velocity Europe 2012 `_ +`Winning the metrics battle (finally) `_ `[Slides] `_ at `Velocity Europe 2012 `_ Articles -------- @@ -17,21 +17,21 @@ Articles `Never fail twice `_ by `Alex Tavgen `_ -`Make better use of Prometheus with Grafana, Telegraf, and Alerta [$] `_ by `Martin Loschwitz, Linux Magazin [DE] `_ +`Make better use of Prometheus with Grafana, Telegraf, and Alerta [$] `_ by `Martin Loschwitz, Linux Magazin [DE] `_ -`Grafana, Telegraf, Alerta – Prometheus besser nutzen (in German) [$] `_ by `Martin Loschwitz, Linux Magazin [DE] `_ +`Grafana, Telegraf, Alerta – Prometheus besser nutzen (in German) [$] `_ by `Martin Loschwitz, Linux Magazin [DE] `_ `Riemann Learnings `_ by Antonio Terreno, CTO The Labrador Papers ------ -`Frankenstack: Toward Real-time Red Team Feedback `_ by +`Frankenstack: Toward Real-time Red Team Feedback `_ by `Markus Kont, Mauno Pihelgas, Bernhards Blumbergs of NATO Cooperative Cyber Defence Centre of Excellence `_ and `Kaie Maennel and Toomas Lepik of the Tallinn University of -Technology `_ at `2017 IEEE Military Communications Conference `_ +Technology `_ at `2017 IEEE Military Communications Conference `_ -`EVE and ADAM: Situation Awareness Tools for NATO CCDCOE Cyber Exercises `_ by `Francisco Jesús Rubio Melón of Ingeniería de Sistemas para la Defensa de España `_, `Teemu Uolevi Väisänen of VTT Technical Research Centre of Finland `_ and `Mauno Pihelgas of NATO Cooperative Cyber +`EVE and ADAM: Situation Awareness Tools for NATO CCDCOE Cyber Exercises `_ by Francisco Jesús Rubio Melón of Ingeniería de Sistemas para la Defensa de España (\https://www.isdefe.es), `Teemu Uolevi Väisänen of VTT Technical Research Centre of Finland `_ and `Mauno Pihelgas of NATO Cooperative Cyber Defence Centre of Excellence `_ References @@ -39,4 +39,6 @@ References `Event Correlation Engine [Master's Thesis] `_ by Andreas Müller (2009) at Institut für Technische Informatik und Kommunikationsnetze -`ANSI/ISA 18.2 Management of Alarm Systems for the Process Industries `_ by `American National Standards Institute `_ +`ANSI/ISA 18.2 Management of Alarm Systems for the Process Industries `_ by `American National Standards Institute `_ + +`Understanding and Applying the ANSI/ISA 18.2 Alarm Management Standard `_ by `American National Standards Institute `_ diff --git a/server.rst b/server.rst index f4d9d38c..1ef1c308 100644 --- a/server.rst +++ b/server.rst @@ -7,8 +7,8 @@ The Alerta API receives alerts from multiple sources, :ref:`correlates ` or :ref:`suppresses ` them, and makes the alerts available via a RESTful_ JSON_ API. -.. _RESTful: http://apigee.com/about/resources/webcasts/restful-api-design-second-edition -.. _JSON: http://developers.squarespace.com/what-is-json/ +.. _RESTful: https://cloud.google.com/apigee +.. _JSON: https://developers.squarespace.com/what-is-json/ Alerts can be intercepted as they are received to modify, enhance or reject them using :ref:`pre-receive hooks `. Alerts can also be @@ -44,6 +44,8 @@ way: Each of the above actions are explained in more detail in the following sections. +.. _about_plugins: + Plugins ------- @@ -53,7 +55,7 @@ is achieved by registering *pre-receive hooks* for transformers, *post-receive hooks* for external notification and *status change hooks* for bi-directional integration. -.. _Plugins: https://en.wikipedia.org/wiki/Plug-in_(computing) +.. _plug-in: https://en.wikipedia.org/wiki/Plug-in_(computing) .. _prereceive: @@ -84,15 +86,14 @@ External Notification Using post-receive hooks, plugin integrations can be used to provide downstream systems with alerts in realtime for external notification. For example, pushing alerts onto an `AWS SNS topic`_, `AMQP queue`_, logging to a `Logstash/Kibana`_ -stack, or sending notifications to `HipChat`_, `Slack`_ or `Twilio`_ and many +stack, or sending notifications to `Slack`_ or `Twilio`_ and many more. .. _AWS SNS topic: https://github.com/alerta/alerta-contrib/tree/master/plugins/sns .. _AMQP queue: https://github.com/alerta/alerta-contrib/tree/master/plugins/amqp .. _Logstash/Kibana: https://github.com/alerta/alerta-contrib/tree/master/plugins/logstash -.. _HipChat: https://github.com/alerta/alerta-contrib/blob/master/plugins/hipchat -.. _Slack: https://github.com/alerta/alerta-contrib/blob/master/plugins/slack -.. _Twilio: https://github.com/alerta/alerta-contrib/blob/master/plugins/twilio +.. _Slack: https://github.com/alerta/alerta-contrib/tree/master/plugins/slack +.. _Twilio: https://github.com/alerta/alerta-contrib/tree/master/plugins/twilio .. _take_action: @@ -119,7 +120,7 @@ UI then a status change hook could silence_ the `corresponding alert in Alertman This requires that external systems provide enough information in the alert created in Alerta for that alert to be uniquely identified at a later date. -.. _silence: https://prometheus.io/docs/alerting/alertmanager/#silences +.. _silence: https://prometheus.io/docs/alerting/latest/alertmanager/#silences .. _corresponding alert in Alertmanager: https://github.com/alerta/alerta-contrib/tree/master/plugins/prometheus More information about bi-directional integration and real-world examples @@ -177,6 +178,16 @@ Alerts are sorted in the Alerta web UI by ``lastReceiveTime`` by default so that the most recent alerts will be displayed at the top regardless of whether they were new alerts or de-duplicated alerts. +.. _about_filters: + +Filters +------- + +An receieved alert is checked against a set of rules. If a alert matches it +will be filtered for futher use by :ref:`plugins`. +Matching for filters is done in the same fashion :ref:`blackout periods` do. +Filter type are specified with optional parameters for plugins to use. + .. _correlation: Simple Correlation @@ -197,9 +208,9 @@ With Alerta, there are two ways alerts can be correlated, namely: events with **any** severity, then the alert is correlated. .. _complex correlation: https://en.wikipedia.org/wiki/Complex_event_processing -.. _much: http://www.espertech.com/ +.. _much: https://www.espertech.com/ .. _more: http://riemann.io/ -.. _involved: http://www.drools.org/ +.. _involved: https://www.drools.org/ In both cases, this means that information from the correlated alert is used to update key attributes of the existing alert (like ``severity``, diff --git a/tutorials.rst b/tutorials.rst index 4661070a..e3e5b975 100644 --- a/tutorials.rst +++ b/tutorials.rst @@ -5,6 +5,8 @@ Getting Started The following tutorials are designed to get you started deploying and using Alerta in common scenarios. +.. _tutorials: + Tutorials --------- @@ -18,7 +20,7 @@ Tutorials .. note:: If you require help with any of the above tutorials post a question on Slack_. -.. _Slack: https://slack.alerta.dev +.. _Slack: https://alerta.slack.com/join/shared_invite/zt-o2p396lz-VYc5zCOdS4pTwIy3hAW0KQ How-to Guides ------------- diff --git a/webhooks.rst b/webhooks.rst index bac502d4..cd35a2b2 100644 --- a/webhooks.rst +++ b/webhooks.rst @@ -1,4 +1,4 @@ -.. _webhooks: +.. _custom webhooks: Custom Webhooks diff --git a/webui.rst b/webui.rst index 34aa5a31..1a9b5087 100644 --- a/webui.rst +++ b/webui.rst @@ -10,7 +10,7 @@ attention of operators. The following sections explain how to get the most of out the Alerta web UI. -* :ref:`Local and remote configuration ` +* :ref:`Local and remote configuration ` * :ref:`Authentication methods ` * :ref:`Alert Summary List, Details & History ` * :ref:`Getting the most out of Heartbeats ` @@ -23,4 +23,4 @@ the Alerta web UI. .. note:: If you require help with any of the above information post a question on Slack_. -.. _Slack: https://slack.alerta.dev \ No newline at end of file +.. _Slack: https://alerta.slack.com/join/shared_invite/zt-o2p396lz-VYc5zCOdS4pTwIy3hAW0KQ diff --git a/webui/alerts.rst b/webui/alerts.rst index ae33584b..74ffd8c7 100644 --- a/webui/alerts.rst +++ b/webui/alerts.rst @@ -11,7 +11,7 @@ Alert Summary List - env tabs, ALL Alert Summary Indicators (ASI) ---------------------------- +------------------------------ - panels, default and custom queries (3 diff query types) diff --git a/webui/configuration.rst b/webui/configuration.rst index 0ea44fdc..8dc88c86 100644 --- a/webui/configuration.rst +++ b/webui/configuration.rst @@ -1,4 +1,4 @@ -.. _webui config: +.. _webui configuration: Configuration ------------- @@ -10,7 +10,7 @@ that is supplied with the web application. It uses simple JSON syntax. The Alerta web UI previously used an `AngularJS configuration block`_ for configuration settings which has now been deprecated. -.. _AngularJS configuration block: https://docs.angularjs.org/guide/module#configuration-blocks +.. _AngularJS configuration block: https://docs.angularjs.org/guide/module#registration-in-the-config-block The three main areas for configuration are: @@ -113,39 +113,11 @@ shown below that. Client Settings ~~~~~~~~~~~~~~~ -Full list of API server settings that can be used to configure clients. - -``AUTH_REQUIRED`` - -``CUSTOMER_VIEWS`` - -``AUTH_PROVIDER`` - -``SIGNUP_ENABLED`` - -``OAUTH2_CLIENT_ID`` - -``GITHUB_URL`` - -``GITLAB_URL`` - -``KEYCLOAK_URL`` - -``KEYCLOAK_REALM`` - -``PINGFEDERATE_URL`` - -``COLOR_MAP`` - -``SEVERITY_MAP`` - -``GOOGLE_TRACKING_ID`` - -``AUTO_REFRESH_INTERVAL`` - -.. note:: It is not currently possible to configure dates or audio. +Full list of API server settings that can be used to configure clients can be found +at :ref:`webui settings`. .. raw:: html + Severity Colors diff --git a/webui/settings.rst b/webui/settings.rst index debd77ff..01a14ac0 100644 --- a/webui/settings.rst +++ b/webui/settings.rst @@ -3,26 +3,24 @@ User Preferences ---------------- +**Application Settings** + * Dark theme + * play notification sounds -Application Settings -- Dark theme -- play notification sounds +**Language Settings** + * English + * French + * German -Language Settings -- English -- French -- German - -Date and Time Settings -= Long date format -= Medium date format -= Short time format -= Time display mode - - Use local date & time - - Use UTC - -Alert summary settings -- rows per page -- refresh interval -- default shelve timeout +**Date and Time Settings** + * Long date format + * Medium date format + * Short time format + * Time display mode + * Use local date & time + * Use UTC +**Alert summary settings** + * rows per page + * refresh interval + * default shelve timeout