NCIEX

This tutorial will guide you on how to use the official Ntfy service (https://ntfy.sh/) to configure notification features for Nezha monitoring. This tutorial focuses on providing hands-on configuration.

Ntfy is a simple yet powerful push notification service with the following advantages: completely open-source and free to use, supports self-hosting, no account registration required, multi-platform support (Android, iOS, Web), easy and quick configuration, and supports end-to-end encryption, making it an ideal choice for server monitoring notifications. Its lightweight nature and simple API make it particularly suitable for integration with Nezha monitoring.

In contrast, the free version of Server 酱 has the following limitations:

• Supports only 5 push messages per day; exceeding this requires payment, does not support self-hosting, and relies entirely on third-party services. The messaging channel is singular, supporting only WeChat push. The free version does not support group management of messages and cannot perform advanced operations such as message recall; service availability depends on the WeChat public account platform.

Configuration Instructions#

Basic Information#

• Name: Ntfy

• URL: https://ntfy.sh/

• Request Method: POST

• Type: JSON

• Request Header:

  Copy

  {
    "Content-Type": "application/json"
  }
  

  Note: The Ntfy official service does not require an Authorization header.

• Request Body:

  Copy

  {
    "topic": "Nezha Monitoring",
    "title": "Server Status - #SERVER.NAME#",
    "message": "CPU: #SERVER.CPU#% | Memory: #SERVER.MEM# | Disk: #SERVER.DISK# | Upload: #SERVER.NETOUTSPEED# | Download: #SERVER.NETINSPEED# | Load: #SERVER.LOAD1#/#SERVER.LOAD5#/#SERVER.LOAD15#",
    "priority": 3,
    "tags": ["warning"]
  }
  

  Important: Replace Nezha Monitoring with the topic name you want to subscribe to; it is recommended to use a random string for security.

Steps to Use#

1. Install the ntfy App

   • Install the ntfy app via Google Play or F-Droid (or use the web version at https://ntfy.sh/).
   • Open the app and subscribe to the topic name you set in the request body (e.g., Nezha Monitoring).
   • Please note the topic you chose, as it will be used in subsequent configurations.

2. Add Notification Configuration in Nezha Monitoring Panel

   • Open the Nezha monitoring panel.
   • Go to the notification configuration page.
   • Click "Add Notification."
   • Fill in the information according to the "Configuration Instructions" section.
     • URL: https://ntfy.sh/
     • Request Method: Select POST
     • Type: Select JSON
     • Request Header: Copy and paste the JSON content above.
     • Request Body: Copy and paste the JSON content above, making sure to change topic to the topic you subscribed to in the Ntfy app.
     • Validate TLS: Check this option.

3. Test Notification

   • After saving the configuration, click the "Test" button to send a test notification.
   • Check if your phone or Ntfy app received the notification.

Detailed Explanation#

URL#

• When using the official Ntfy service, the URL is fixed as https://ntfy.sh/, and there is no need to add the topic name in the URL.

Request Header#

• For the official Ntfy service, you only need to set Content-Type to application/json, without the need for Authorization.

Request Body#

• topic: This is the topic you subscribed to in the Ntfy app; ensure this value matches the name you subscribed to in the app, as it is key to receiving notifications.
• title: The title of the notification, #SERVER.NAME# will be replaced with the server's name.
• message: The specific content of the notification, including information about the server's CPU, memory, disk, network speed, and load.
• priority: The priority of the notification, 3 is medium priority.
• tags: Tags can be added as needed; here, "warning" is used.

Variable Explanation#

• #SERVER.NAME#: Server name

• #SERVER.CPU#: CPU usage

• #SERVER.MEM#: Memory usage

• #SERVER.DISK#: Disk usage

• #SERVER.NETINSPEED#: Network inbound speed

• #SERVER.NETOUTSPEED#: Network outbound speed

• For more variable information, please refer to the official Nezha monitoring documentation. https://nezha.wiki/guide/notifications.html

Notes#

• Topic: Ensure that the topic name subscribed to in the Ntfy app matches the value of topic in the request body.
• Validate TLS: The "Validate TLS" option must be checked to ensure secure communication.
• Test: Testing whether the notification is successfully sent is a key step to ensure the configuration is correct.

Frequently Asked Questions#

1. Not receiving notifications:

   • Check if the Ntfy app has subscribed to the correct topic.
   • Check if the topic in the request body matches the subscribed topic.
   • Ensure the "Validate TLS" option is checked.

2. Notification format error:

   • Ensure the JSON format of the request body is correct.
   • Check if Content-Type is set to application/json.

Alert Rule Configuration (Brief)#

• The configuration method for alert rules is consistent with previous documentation, focusing on setting appropriate trigger conditions and notification groups.
• You can set alert rules for various monitoring types such as CPU, memory, disk, network, and offline based on your actual needs.
• For detailed configuration steps, please refer to the official Nezha monitoring documentation and the previous "Alert Rule Configuration" section of this document.

Advanced Instructions#

Self-hosting Ntfy Server Installation#

1. Preparation

   • Ensure Docker and Docker Compose are installed on the server.
   • Prepare a domain name and resolve it to the server (optional but recommended).
   • It is recommended to use Caddy or Nginx as a reverse proxy.

2. Create Docker Compose Configuration

Create a directory and write docker-compose.yml:

mkdir -p /opt/ntfy
cd /opt/ntfy
vim docker-compose.yml

Configuration file content:

version: "3.8"

services:
  ntfy:
    image: binwiederhier/ntfy
    container_name: ntfy
    command:
      - serve
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - ./data:/var/lib/ntfy
      - ./cache:/var/cache/ntfy

    ports:
      - 8080:80

For specific tutorials, see the official documentation: https://ntfy.sh/docs/self-hosting/docker

Using Cloudflare Tunnel for Internal Network Penetration#

If your Ntfy server is deployed in an internal network environment, it is recommended to use Cloudflare Tunnel for secure internal network penetration. This allows you to:

• Avoid opening any ports
• Automatically configure SSL certificates
• Gain DDoS protection
• Support access control

6. Docker Compose Integration with Cloudflare Tunnel

version: "3.8"

services:
  ntfy:
    image: binwiederhier/ntfy
    container_name: ntfy
    command:
      - serve
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - ./data:/var/lib/ntfy
      - ./cache:/var/cache/ntfy
      - ./config.yml:/etc/ntfy/config.yml
    ports:
      - 8080:80

  cloudflared:
    image: cloudflare/cloudflared
    container_name: cloudflared
    command: tunnel run
    environment:
      - TUNNEL_TOKEN=your-tunnel-token
    restart: unless-stopped

This way, you can access it anytime as long as you have a domain on Cloudflare.

Request Header#

• For self-hosted Ntfy services, you need to set Content-Type to application/json, and it is best to set Authorization.

Authorization Token Configuration#

1. Basic Auth Method

{
  "Content-Type": "application/json",
  "Authorization": "Basic base64(username:password)"
}

2. Actual Example

Assuming the username and password are:

• Username: monitor
• Password: ntfy2024

Generate base64 encoding:

# Linux/Mac
echo -n "monitor:ntfy2024" | base64
# Output: bW9uaXRvcjpudGZ5MjAyNA==

# Windows PowerShell
[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("monitor:ntfy2024"))
# Output: bW9uaXRvcjpudGZ5MjAyNA==

3. Complete Request Header Example

{
  "Content-Type": "application/json",
  "Authorization": "Basic bW9uaXRvcjpudGZ5MjAyNA=="
}

Note:

• Please replace username and password with your actual username and password.
• Base64 encoding is not encryption; do not use plaintext passwords in the request header.
• It is recommended to use HTTPS to ensure transmission security.

Example configuration:

{
  "topic": "Nezha Monitoring",
  "title": "Alert - #SERVER.NAME#",
  "message": "CPU usage exceeds 90%: #SERVER.CPU#%",
  "priority": 5,
  "tags": ["warning", "cpu"]
}

1. Custom Message Template

{
  "topic": "Nezha Monitoring",
  "title": "【#SERVER.STATUS#】#SERVER.NAME#",
  "message": "Time: #SERVER.DATE#\nStatus: #SERVER.STATUS#\nDetails: CPU=#SERVER.CPU#% MEM=#SERVER.MEM#\nLocation: #SERVER.LOCATION#",
  "priority": 3,
  "tags": ["status", "#SERVER.STATUS#"],
  "click": "https://your-nezha-monitoring-address"
}

Example configuration:

{
  "topic": "Nezha Monitoring",
  "title": "Alert - #SERVER.NAME#",
  "message": "CPU usage exceeds 90%: #SERVER.CPU#%",
  "priority": 5,
  "tags": ["warning", "cpu"]
}

1. Offline Alert

{
  "topic": "Nezha Monitoring",
  "title": "【Offline Alert】#SERVER.NAME#",
  "message": "⚠️ Server is offline\nHostname: #SERVER.HOST#\nIP: #SERVER.IP#\nOffline Time: #DATETIME#",
  "priority": 5,
  "tags": ["alert", "offline"]
}

2. Resource Alert

{
  "topic": "Nezha Monitoring",
  "title": "【Resource Alert】#SERVER.NAME#",
  "message": "CPU: #SERVER.CPU#% | Memory: #SERVER.MEM#% | Disk: #SERVER.DISK#%\nLoad: #SERVER.LOAD1#/#SERVER.LOAD5#/#SERVER.LOAD15#",
  "priority": 4,
  "tags": ["warning", "resource"]
}

3. Traffic Alert

{
  "topic": "Nezha Monitoring",
  "title": "【Traffic Alert】#SERVER.NAME#",
  "message": "Monthly traffic exceeded\nUpload: #SERVER.TRANSFEROUT#\nDownload: #SERVER.TRANSFERIN#",
  "priority": 3,
  "tags": ["warning", "traffic"]
}

Supported Variables#

The following variables can be used in notification messages:

Notification Configuration Example#

Basic Configuration Items#

Alert Rule Configuration#

1. Offline Monitoring

[
  {
    "Type": "offline",
    "Duration": 300
  }
]

2. Resource Monitoring

[
  {
    "Type": "cpu",
    "Max": 90,
    "Duration": 300
  },
  {
    "Type": "memory",
    "Max": 90,
    "Duration": 300
  }
]

3. Monthly Traffic Monitoring

[
  {
    "Type": "transfer_out_cycle",
    "Max": 1099511627776,
    "Cycle_start": "2024-01-01T00:00:00+08:00",
    "Cycle_interval": 1,
    "Cycle_unit": "month",
    "Cover": 1,
    "Ignore": {"1": true, "2": true}
  }
]

Rule Explanation#

• Duration: Duration (seconds); an alert is triggered only if the threshold is exceeded for this duration.
• Max/Min:
  • Traffic units: bytes (1KB=1024B)
  • CPU/memory/disk: percentage (0-100)
• Cover:
  • 0: Monitor all servers
  • 1: Monitor only specified servers
• Ignore: Monitoring strategy for specified server IDs

Difference Between Alerts and Notifications#

1. Alert Rules

• Used to define trigger conditions (under what circumstances notifications need to be sent)
• Includes specific judgment criteria such as thresholds and durations
• Can set different rules for different servers
• Supports various monitoring types (CPU, memory, disk, etc.)

2. Notification Configuration

• Defines how to send messages (through what method to send notifications)
• Includes message format, receiving methods, etc.
• Can configure multiple notification methods
• Supports custom message templates

Workflow#

1. Alert Trigger Process

• Monitoring data -> Match alert rules -> Trigger notification

2. Rule Matching Logic

• Check monitoring metrics
• Determine if thresholds are exceeded
• Confirm duration
• Verify if it needs to be ignored

3. Notification Sending Process

• Generate notification content
• Apply message template
• Send via configured notification method

Best Practices#

1. Setting Alert Rules

• Set reasonable thresholds based on server performance
• Avoid overly frequent alerts
• Set reasonable durations to avoid false positives
• Set stricter rules for important servers

2. Notification Configuration Recommendations

• Set appropriate notification intervals
• Use different priorities based on alert levels
• Customize clear message formats
• Configure retry mechanisms to handle sending failures

3. Monitoring Maintenance

• Regularly check the effectiveness of rules
• Timely adjust unreasonable thresholds
• Analyze alert history to optimize configurations
• Ensure the availability of notification methods