========================
Dying Gasp enabler (DGe)
========================

.. sidebar:: Contents

  .. contents::
      :depth: 2
      :local:

This chapter covers some aspects related to the :osdx:cfg:`service external-dying-gasp`,
which allows you to configure a **Dying Gasp enabler (DGe)** in OSDx.

.. image:: dge.png

A **DGe** is an energy-storing device meant to be used as backup for Teldat network devices
for a short period of time (order of seconds) when a power failure occurs.

If the DGe is attached to a network device and the dying-gasp service is active, when a power failure
occurs, the DGe sends a signal to the device through the local console port and the device
reacts to that signal initiating a system close. It then self-reboots safely and waits
for the power supply to fully discharge.

.. caution::

  If the cable that is plugged into the console port has a **DGe** label on one end, this end must
  be plugged into the Dying Gasp enabler, otherwise the signal sent by the DGe will not be detected
  by the router.


Configuration
=============

To connect and use a Dying Gasp enabler, you must first set the OSDx device's console port to
**dying-gasp** mode. You can do this using the :osdx:cfg:`service external-dying-gasp` command
from a Telnet or SSH session:

.. code-block:: none

  set service external-dying-gasp

Once committed, this will allow the OSDx device to monitor the console port while the service
is set.

.. caution::

  You will not be able to manage your OSDx device by connecting to the **console port** while
  this mode is enabled. Therefore, an **alternative method** must be established to access
  the device's Command Line Interface (CLI), such as **SSH** or **Telnet**, and use
  :osdx:cfg:`service external-dying-gasp` on that session.
  See :doc:`SSH </articles/local_services/ssh/index>` or
  :doc:`Telnet</articles/local_services/telnet/index>` to learn more about
  these services.

To restore the console port's normal operation and use it to regain access to the device's CLI,
execute the `delete` operation on the same :osdx:cfg:`service external-dying-gasp` command.
This will revert the settings and allow CLI access via the console port again:

.. code-block:: none

  delete service external-dying-gasp


Time delay
----------

This command modifies the time, in seconds, it takes for the device to close and reboot once the
DGe signal is detected.
`By default, no delay is configured.`

.. tip::

  The delay can be set in fractions of seconds, i.e. in the order of milliseconds.

This is the syntax to set the value of the :osdx:cfg:`service external-dying-gasp delay *`
configuration in OSDx:

.. code-block:: none

  set service external-dying-gasp delay <value>

For example, this command will set a delay of one second:

.. code-block:: none

  set service external-dying-gasp delay 1.0


Log level
---------

This command selects the logging level of the external-dying-gasp daemon through the journal.
`By default, it is set to notice level.`

This is the syntax to change the logging level for the
:osdx:cfg:`service external-dying-gasp log-level *` configuration in OSDx:

.. code-block:: none

  set service external-dying-gasp log-level <level>

Being <level> one of the following options:

  * **emerg**, emergency messages
  * **alert**, urgent messages
  * **crit**, critical messages
  * **err**, error messages
  * **warning**, warning messages
  * **notice**, messages for further investigation
  * **info**, informational messages
  * **debug**, debug messages

For example, this command will change the logging level to error:

.. code-block:: none

  set service external-dying-gasp log-level err


SNMP management
---------------

.. important::
  To better understand how to configure the **Simple Network Management Protocol (SNMP)** service,
  see :doc:`SNMP documentation </articles/local_services/snmp/index>`.

For the OSDx device to be able to send traps, you will first need to create an SNMP community or user
and establish the `external-dying-gasp` service as target.

After the SNMP service is configured, the sending of traps must be enabled for the DGe by executing
the following command in OSDx:

.. code-block:: none

  set service external-dying-gasp enable-snmp-trap


Examples
========

To enable the `external-dying-gasp` service with default settings:

.. code-block:: none

  set service external-dying-gasp

In this case, the expected behaviour is that, when a power failure occurs, the `external-dying-gasp`
service prints notice level logs indicating that the DGe signal has been detected. The device then
reboots as soon as possible.


To enable the `external-dying-gasp` service with the following settings:

 * Logging level set to warning messages.
 * SNMP traps enabled (SNMP service previously configured).
 * Delay of two and a half seconds.

.. code-block:: none

  set service external-dying-gasp log-level warning
  set service external-dying-gasp enable-snmp-trap
  set service external-dying-gasp delay 2.5

In this case, the expected behaviour is that, when a power failure occurs, the `external-dying-gasp`
service prints warning level logs indicating that the DGe signal has been detected. The device then sends
an SNMP trap and, after 2.5 seconds, it reboots.


Command Summary
===============

.. osdx:cmdtree:: cfg

  service external-dying-gasp