Skip to content

Commit

Permalink
Merge pull request ceph#43901 from pcuzner/snmp-notifier
Browse files Browse the repository at this point in the history 
mgr/cephadm: Add snmp-gateway service support

Reviewed-by: Adam King <[email protected]>
Reviewed-by: Sebastian Wagner <[email protected]>
  • Loading branch information
@sebastian-philipp
sebastian-philipp authored Dec 16, 2021
2 parents 76ed5e3 + c2f5e10 commit 2459728
Show file tree
Hide file tree
Showing 16 changed files with 1,407 additions and 35 deletions.
27 changes: 14 additions & 13 deletions doc/cephadm/services/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ for details on individual services:
iscsi
custom-container
monitoring
snmp-gateway

Service Status
==============
Expand All @@ -25,8 +26,8 @@ Service Status
To see the status of one
of the services running in the Ceph cluster, do the following:

#. Use the command line to print a list of services.
#. Locate the service whose status you want to check.
#. Use the command line to print a list of services.
#. Locate the service whose status you want to check.
#. Print the status of the service.

The following command prints a list of services known to the orchestrator. To
Expand Down Expand Up @@ -78,7 +79,7 @@ system name:
.. prompt:: bash #

ceph orch ps --daemon_type osd --daemon_id 0

.. _orchestrator-cli-service-spec:

Service Specification
Expand Down Expand Up @@ -147,7 +148,7 @@ the Services Specification, we suggest exporting the running Service Specificati
following these instructions:

.. prompt:: bash #

ceph orch ls --service-name rgw.<realm>.<zone> --export > rgw.<realm>.<zone>.yaml
ceph orch ls --service-type mgr --export > mgr.yaml
ceph orch ls --export > cluster.yaml
Expand Down Expand Up @@ -515,12 +516,12 @@ Deploying a daemon on a host manually
.. note::

This workflow has a very limited use case and should only be used
in rare circumstances.
in rare circumstances.

To manually deploy a daemon on a host, follow these steps:

Modify the service spec for a service by getting the
existing spec, adding ``unmanaged: true``, and applying the modified spec.
Modify the service spec for a service by getting the
existing spec, adding ``unmanaged: true``, and applying the modified spec.

Then manually deploy the daemon using the following:

Expand All @@ -534,12 +535,12 @@ For example :

ceph orch daemon add mgr --placement=my_host

.. note::
.. note::

Removing ``unmanaged: true`` from the service spec will
Removing ``unmanaged: true`` from the service spec will
enable the reconciliation loop for this service and will
potentially lead to the removal of the daemon, depending
on the placement spec.
on the placement spec.

Removing a daemon from a host manually
--------------------------------------
Expand All @@ -556,13 +557,13 @@ For example:

ceph orch daemon rm mgr.my_host.xyzxyz

.. note::
.. note::

For managed services (``unmanaged=False``), cephadm will automatically
deploy a new daemon a few seconds later.

See also
--------
* See :ref:`cephadm-osd-declarative` for special handling of unmanaged OSDs.

* See :ref:`cephadm-osd-declarative` for special handling of unmanaged OSDs.
* See also :ref:`cephadm-pause`
171 changes: 171 additions & 0 deletions doc/cephadm/services/snmp-gateway.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,171 @@
====================
SNMP Gateway Service
====================

SNMP_ is still a widely used protocol, to monitor distributed systems and devices across a variety of hardware
and software platforms. Ceph's SNMP integration focuses on forwarding alerts from it's Prometheus Alertmanager
cluster to a gateway daemon. The gateway daemon, transforms the alert into an SNMP Notification and sends
it on to a designated SNMP management platform. The gateway daemon is from the snmp_notifier_ project,
which provides SNMP V2c and V3 support (authentication and encryption).

Ceph's SNMP gateway service deploys one instance of the gateway by default. You may increase this
by providing placement information. However, bear in mind that if you enable multiple SNMP gateway daemons,
your SNMP management platform will receive multiple notifications for the same event.

.. _SNMP: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol
.. _snmp_notifier: https://github.com/maxwo/snmp_notifier

Compatibility
=============
The table below shows the SNMP versions that are supported by the gateway implementation

================ =========== ===============================================
SNMP Version Supported Notes
================ =========== ===============================================
V1 ❌ Not supported by snmp_notifier
V2c ✔
V3 authNoPriv ✔ uses username/password authentication, without
encryption (NoPriv = no privacy)
V3 authPriv ✔ uses username/password authentication with
encryption to the SNMP management platform
================ =========== ===============================================


Deploying an SNMP Gateway
=========================
Both SNMP V2c and V3 provide credentials support. In the case of V2c, this is just the community string - but for V3
environments you must provide additional authentication information. These credentials are not supported on the command
line when deploying the service. Instead, you must create the service using a credentials file (in yaml format), or
specify the complete service definition in a yaml file.

Command format
--------------

.. prompt:: bash #

ceph orch apply snmp-gateway <snmp_version:V2c|V3> <destination> [<port:int>] [<engine_id>] [<auth_protocol: MD5|SHA>] [<privacy_protocol:DES|AES>] [<placement>] ...


Usage Notes

- you must supply the ``--snmp-version`` parameter
- the ``--destination`` parameter must be of the format hostname:port (no default)
- you may omit ``--port``. It defaults to 9464
- the ``--engine-id`` is a unique identifier for the device (in hex) and required for SNMP v3 only.
Suggested value: 8000C53F<fsid> where the fsid is from your cluster, without the '-' symbols
- for SNMP V3, the ``--auth-protocol`` setting defaults to **SHA**
- for SNMP V3, with encryption you must define the ``--privacy-protocol``
- you **must** provide a -i <filename> to pass the secrets/passwords to the orchestrator

Deployment Examples
===================

SNMP V2c
--------
Here's an example for V2c, showing CLI and service based deployments

.. prompt:: bash #

ceph orch apply snmp-gateway --port 9464 --snmp_version=V2c --destination=192.168.122.73:162 -i ./snmp_creds.yaml

with a credentials file that contains;

.. code-block:: yaml
---
snmp_community: public
Alternatively, you can create a yaml definition for the gateway and apply it from a single file

.. prompt:: bash #

ceph orch apply -i snmp-gateway.yml

with the file containing the following configuration

.. code-block:: yaml
service_type: snmp-gateway
service_name: snmp-gateway
placement:
count: 1
spec:
credentials:
snmp_community: public
port: 9464
snmp_destination: 192.168.122.73:162
snmp_version: V2c
SNMP V3 (authNoPriv)
--------------------
Deploying an snmp-gateway service supporting SNMP V3 with authentication only, would look like this;

.. prompt:: bash #

ceph orch apply snmp-gateway --snmp-version=V3 --engine-id=800C53F000000 --destination=192.168.122.1:162 -i ./snmpv3_creds.yml

with a credentials file as;

.. code-block:: yaml
---
snmp_v3_auth_username: myuser
snmp_v3_auth_password: mypassword
or as a service configuration file

.. code-block:: yaml
service_type: snmp-gateway
service_name: snmp-gateway
placement:
count: 1
spec:
credentials:
snmp_v3_auth_password: mypassword
snmp_v3_auth_username: myuser
engine_id: 800C53F000000
port: 9464
snmp_destination: 192.168.122.1:162
snmp_version: V3
SNMP V3 (authPriv)
------------------

Defining an SNMP V3 gateway service that implements authentication and privacy (encryption), requires two additional values

.. prompt:: bash #

ceph orch apply snmp-gateway --snmp-version=V3 --engine-id=800C53F000000 --destination=192.168.122.1:162 --privacy-protocol=AES -i ./snmpv3_creds.yml

with a credentials file as;

.. code-block:: yaml
---
snmp_v3_auth_username: myuser
snmp_v3_auth_password: mypassword
snmp_v3_priv_password: mysecret
.. note::

The credentials are stored on the host, restricted to the root user and passed to the snmp_notifier daemon as
an environment file (``--env-file``), to limit exposure.


AlertManager Integration
========================
When an SNMP gateway service is deployed or updated, the Prometheus Alertmanager configuration is automatically updated to forward any
alert that has an OID_ label to the SNMP gateway daemon for processing.

.. _OID: https://en.wikipedia.org/wiki/Object_identifier

Implementing the MIB
======================
To make sense of the SNMP Notification/Trap, you'll need to apply the MIB to your SNMP management platform. The MIB (CEPH-MIB.txt) can
downloaded from the main Ceph repo_

.. _repo: https://github.com/ceph/ceph/tree/master/monitoring/snmp
13 changes: 12 additions & 1 deletion doc/mgr/orchestrator.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -157,11 +157,19 @@ This is an overview of the current implementation status of the orchestrators.
apply nfs ✔ ✔
apply osd ✔ ✔
apply rbd-mirror ✔ ✔
apply rgw ✔ ✔
apply cephfs-mirror ⚪ ✔
apply grafana ⚪ ✔
apply prometheus ❌ ✔
apply alertmanager ❌ ✔
apply node-exporter ❌ ✔
apply rgw ✔ ✔
apply container ⚪ ✔
apply snmp-gateway ❌ ✔
host add ⚪ ✔
host ls ✔ ✔
host rm ⚪ ✔
host maintenance enter ❌ ✔
host maintenance exit ❌ ✔
daemon status ⚪ ✔
daemon {stop,start,...} ⚪ ✔
device {ident,fault}-(on,off} ⚪ ✔
Expand All @@ -171,7 +179,10 @@ This is an overview of the current implementation status of the orchestrators.
nfs add ⚪ ✔
rbd-mirror add ⚪ ✔
rgw add ⚪ ✔
ls ✔ ✔
ps ✔ ✔
status ✔ ✔
upgrade ❌ ✔
=================================== ====== =========

where
Expand Down
Loading

0 comments on commit 2459728

Please sign in to comment.