# Alerting & Reporting Setup Guide

## Introduction

This guide walks you through configuring basic alerting and reporting for your Validator node using the `nodectl` utility. It enables email notifications if your node drops from the cluster (excluding local network outages).

***

| Contents                                        |
| ----------------------------------------------- |
| [Important Limitations](#important-limitations) |
| [Prerequisites](#prerequisites)                 |
| [Configure Alerting](#configure-alerting)       |
| [Test Configuration](#test-configuration)       |
| [Troubleshooting](#troubleshooting)             |

***

## ⚠️ Important Limitations

The nodectl utility's alerting feature depends on your node being reachable. If the VPS goes offline or loses internet access, alerts cannot be transmitted and **will not be delivered**.

***

## :paperclips: Prerequisites

* nodectl must be installed and running on your node.
* A **Gmail account** with:
  * **2-Step Verification enabled**
  * A **dedicated App Password** (email token) created for nodectl

{% hint style="info" %}
This guide will walk you through these steps.
{% endhint %}

***

## :rosette: Configure Alerting

{% stepper %}
{% step %}

### Create or Use a Gmail Account

You can use an existing Gmail account or [create a new one](https://support.google.com/mail/answer/56256?hl=en).
{% endstep %}

{% step %}

### Enable Gmail 2-Step Verification

If not already enabled, activate **2-Step Verification** via your Google Account:

* Go to: **Manage your Google Account**
* Click the **Security** tab
* Follow prompts to enable 2-Step Verification
  {% endstep %}

{% step %}

### Generate an App Password

* In your Google Account > Security > 2-Step Verification section
* Scroll to **App passwords**
* Click the right-arrow (>) to open
* Under *Select app*, choose **Other (Custom name)**
* Enter a name (e.g., `constellation_alerts`)
* Click **Create**
* Copy the generated app password (token) and **store it securely**

{% hint style="danger" %}
⚠️ **This password will only be shown once.** 

If lost, delete and recreate it.
{% endhint %}
{% endstep %}

{% step %}

### Determine Your Timezone

Your VPS uses UTC, but you can configure alerting in your local timezone.

Use [this reference list](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) to look up your **exact timezone string** (e.g., `America/New_York`, `Europe/Zurich`).

Record your timezone string for later.

{% hint style="warning" %}
Do **not** use shortcuts like `EST` or `CET`.
{% endhint %}
{% endstep %}

{% step %}

### Connect to Your Node

### &#x20;[<kbd>How to SSH into your Node</kbd>](https://docs.constellationnetwork.io/run-a-node/references/ssh-remote-access/how-to-ssh-into-vps)&#x20;

```bash
ssh -i /path/to/ssh/private/key nodeadmin@<vps_ip_address>
```

{% endstep %}

{% step %}

### Launch the Configurator

```bash
sudo nodectl configure -e -cb -d
```

{% endstep %}

{% step %}

### Enter Alerting Setup

```
N) Setup Alerting
```

You’ll be prompted for the following details:

<table><thead><tr><th width="188">Prompt</th><th>Description</th></tr></thead><tbody><tr><td><strong>gmail account</strong></td><td>The Gmail address used to send alerts</td></tr><tr><td><strong>token</strong></td><td>The App Password (token) you generated</td></tr><tr><td><strong>send method</strong></td><td>Use <code>multi</code> (recommended) or <code>single</code></td></tr><tr><td><strong>recipient emails</strong></td><td>Comma-separated list of emails (<code>you@gmail.com,alert@example.com</code>)</td></tr><tr><td><strong>time zone</strong></td><td>Your exact timezone string (e.g., <code>America/Los_Angeles</code>)</td></tr><tr><td><strong>begin alerting hour</strong></td><td>Start time for alerts in UTC (e.g., <code>0</code> for always)</td></tr><tr><td><strong>end alerting hour</strong></td><td>End time for alerts in UTC (e.g., <code>0</code> for always)</td></tr><tr><td><strong>send report hour</strong></td><td>Hour (UTC) to receive daily report (e.g., <code>13</code> for 1 PM UTC)</td></tr></tbody></table>
{% endstep %}

{% step %}

### Exit Configurator

```
Q)uit
```

{% endstep %}
{% endstepper %}

***

## :test\_tube: Test Configuration

{% stepper %}
{% step %}

### Test an Alert

```bash
sudo nodectl auto_restart alert_test
```

{% endstep %}

{% step %}

### Handle Spam

Check your inbox. If it ends up in spam, mark it as "**not spam**."

If you are sending alerts to a **mobile provider email**, ( sending an email to your mobile phone number in order to obtain text (SMS/MMS) message alerts ).  It is important to make sure your carrier allows the message through to your phone. Some carriers may silently block messages they flag as suspicious.  This may require contacting your mobile provider support with a request to allow the emails, and remove any flags as non-nefarious.
{% endstep %}

{% step %}

### &#x20;Test a Daily Report

```bash
sudo nodectl auto_restart send_report
```

You should receive a formatted status report via email.
{% endstep %}
{% endstepper %}

***

## 🛠️ Troubleshooting

If you don’t receive emails:

* Confirm your App Password was entered correctly
* Ensure your Gmail account is not blocking outbound activity
* Double-check that your time zone string matches the official naming convention
* Use a secondary email address to confirm if messages are being blocked by your provider

***

Once configured, your Validator node will monitor its cluster participation status and email you alert messages and daily status reports; helping you stay informed, even when you’re away.