247 lines
6.5 KiB
Markdown
247 lines
6.5 KiB
Markdown
# 📱 NTFY Quick Reference
|
|
|
|
*Quick reference guide for NTFY notification system usage*
|
|
|
|
## Basic Usage
|
|
|
|
### Send Simple Message
|
|
```bash
|
|
curl -d "Hello World" https://ntfy.vish.gg/topic-name
|
|
```
|
|
|
|
### Send with Authentication
|
|
```bash
|
|
curl -u username:password -d "Authenticated message" https://ntfy.vish.gg/topic-name
|
|
```
|
|
|
|
### Send with Title
|
|
```bash
|
|
curl -H "Title: Alert Title" -d "Message body" https://ntfy.vish.gg/topic-name
|
|
```
|
|
|
|
## Priority Levels
|
|
|
|
### Set Message Priority
|
|
```bash
|
|
# Low priority (1-2)
|
|
curl -H "Priority: 1" -d "Debug message" https://ntfy.vish.gg/topic-name
|
|
|
|
# Normal priority (3) - default
|
|
curl -d "Normal message" https://ntfy.vish.gg/topic-name
|
|
|
|
# High priority (4-5)
|
|
curl -H "Priority: 5" -d "CRITICAL ALERT" https://ntfy.vish.gg/topic-name
|
|
```
|
|
|
|
### Priority Reference
|
|
- **1 (Min)**: 🔕 Silent, debugging
|
|
- **2 (Low)**: 🔔 Quiet notification
|
|
- **3 (Default)**: 🔔 Normal notification
|
|
- **4 (High)**: 📢 Important, loud
|
|
- **5 (Max)**: 🚨 Critical, emergency
|
|
|
|
## Tags and Emojis
|
|
|
|
### Common Tags
|
|
```bash
|
|
# Success notifications
|
|
curl -H "Tags: white_check_mark,success" -d "Backup completed" https://ntfy.vish.gg/backups
|
|
|
|
# Warning notifications
|
|
curl -H "Tags: warning,yellow_circle" -d "High CPU usage" https://ntfy.vish.gg/alerts
|
|
|
|
# Error notifications
|
|
curl -H "Tags: x,red_circle" -d "Service failed" https://ntfy.vish.gg/alerts
|
|
|
|
# Info notifications
|
|
curl -H "Tags: information_source,blue_circle" -d "System update" https://ntfy.vish.gg/info
|
|
```
|
|
|
|
### Popular Emoji Tags
|
|
- **✅ Success**: `white_check_mark`, `heavy_check_mark`
|
|
- **⚠️ Warning**: `warning`, `yellow_circle`
|
|
- **❌ Error**: `x`, `red_circle`, `no_entry`
|
|
- **🔥 Critical**: `fire`, `rotating_light`
|
|
- **📊 Monitoring**: `bar_chart`, `chart_with_upwards_trend`
|
|
- **🔧 Maintenance**: `wrench`, `hammer_and_wrench`
|
|
- **💾 Backup**: `floppy_disk`, `package`
|
|
|
|
## Actions and Buttons
|
|
|
|
### Add Action Buttons
|
|
```bash
|
|
curl -H "Actions: view, Open Dashboard, https://grafana.local" \
|
|
-d "Check system metrics" \
|
|
https://ntfy.vish.gg/monitoring
|
|
```
|
|
|
|
### Multiple Actions
|
|
```bash
|
|
curl -H "Actions: view, Dashboard, https://grafana.local; http, Restart, https://portainer.local/restart" \
|
|
-d "Service needs attention" \
|
|
https://ntfy.vish.gg/alerts
|
|
```
|
|
|
|
## Common Homelab Topics
|
|
|
|
### System Topics
|
|
- **`homelab-alerts`** - Critical system alerts
|
|
- **`homelab-monitoring`** - Monitoring notifications
|
|
- **`homelab-backups`** - Backup status
|
|
- **`homelab-updates`** - System updates
|
|
- **`homelab-security`** - Security alerts
|
|
|
|
### Service Topics
|
|
- **`plex-alerts`** - Plex Media Server
|
|
- **`arr-suite`** - Sonarr/Radarr/Lidarr
|
|
- **`gitea-notifications`** - Git events
|
|
- **`portainer-alerts`** - Container alerts
|
|
|
|
## Authentication
|
|
|
|
### User Credentials
|
|
```bash
|
|
# Set credentials for session
|
|
export NTFY_USER="monitoring"
|
|
export NTFY_PASS="REDACTED_PASSWORD"
|
|
|
|
# Use in curl commands
|
|
curl -u "$NTFY_USER:$NTFY_PASS" -d "Message" https://ntfy.vish.gg/topic
|
|
```
|
|
|
|
### Topic Permissions
|
|
- **Read (r)**: Subscribe and receive messages
|
|
- **Write (w)**: Publish messages to topic
|
|
- **Read-Write (rw)**: Full access to topic
|
|
|
|
## Scheduling and Delays
|
|
|
|
### Delayed Messages
|
|
```bash
|
|
# Send in 30 minutes
|
|
curl -H "At: $(date -d '+30 minutes' '+%Y-%m-%dT%H:%M:%S')" \
|
|
-d "Scheduled maintenance reminder" \
|
|
https://ntfy.vish.gg/maintenance
|
|
```
|
|
|
|
### Recurring Reminders
|
|
```bash
|
|
# Daily backup reminder (use with cron)
|
|
0 9 * * * curl -d "Daily backup check" https://ntfy.vish.gg/reminders
|
|
```
|
|
|
|
## Monitoring Integration Examples
|
|
|
|
### Prometheus AlertManager
|
|
```bash
|
|
# In alertmanager webhook
|
|
curl -u alerts:password \
|
|
-H "Title: {{ .GroupLabels.alertname }}" \
|
|
-H "Priority: 4" \
|
|
-H "Tags: fire,prometheus" \
|
|
-d "{{ range .Alerts }}{{ .Annotations.summary }}{{ end }}" \
|
|
https://ntfy.vish.gg/REDACTED_NTFY_TOPIC
|
|
```
|
|
|
|
### Uptime Kuma
|
|
```bash
|
|
# Service down notification
|
|
curl -u monitoring:password \
|
|
-H "Title: Service Down: Plex" \
|
|
-H "Priority: 5" \
|
|
-H "Tags: rotating_light,down" \
|
|
-d "Plex Media Server is not responding" \
|
|
https://ntfy.vish.gg/homelab-monitoring
|
|
```
|
|
|
|
### Backup Scripts
|
|
```bash
|
|
#!/bin/bash
|
|
# backup-notify.sh
|
|
if [ "$1" = "success" ]; then
|
|
curl -u backup:password \
|
|
-H "Title: Backup Completed" \
|
|
-H "Tags: white_check_mark,backup" \
|
|
-d "Daily backup completed successfully at $(date)" \
|
|
https://ntfy.vish.gg/homelab-backups
|
|
else
|
|
curl -u backup:password \
|
|
-H "Title: Backup Failed" \
|
|
-H "Priority: 4" \
|
|
-H "Tags: x,backup,warning" \
|
|
-d "Daily backup failed: $2" \
|
|
https://ntfy.vish.gg/homelab-backups
|
|
fi
|
|
```
|
|
|
|
## Client Subscription
|
|
|
|
### Command Line
|
|
```bash
|
|
# Subscribe to topic
|
|
ntfy subscribe https://ntfy.vish.gg/REDACTED_NTFY_TOPIC
|
|
|
|
# Subscribe with authentication
|
|
ntfy subscribe --user monitoring:password https://ntfy.vish.gg/REDACTED_NTFY_TOPIC
|
|
|
|
# Subscribe to multiple topics
|
|
ntfy subscribe https://ntfy.vish.gg/REDACTED_NTFY_TOPIC,homelab-backups
|
|
```
|
|
|
|
### Mobile Apps
|
|
1. **Install NTFY app** (Android/iOS)
|
|
2. **Add server**: `https://ntfy.vish.gg`
|
|
3. **Subscribe to topics**: Enter topic names
|
|
4. **Set credentials**: Username/password if required
|
|
|
|
## Troubleshooting
|
|
|
|
### Test Connectivity
|
|
```bash
|
|
# Basic connectivity test
|
|
curl -I https://ntfy.vish.gg
|
|
|
|
# Test topic publishing
|
|
curl -d "Test message" https://ntfy.vish.gg/test
|
|
|
|
# Test authentication
|
|
curl -u username:password -d "Auth test" https://ntfy.vish.gg/test
|
|
```
|
|
|
|
### Debug Message Delivery
|
|
```bash
|
|
# Check message history
|
|
curl -s https://ntfy.vish.gg/topic-name/json
|
|
|
|
# Monitor real-time messages
|
|
curl -N -H "Accept: text/event-stream" https://ntfy.vish.gg/topic-name/sse
|
|
```
|
|
|
|
### Common Error Codes
|
|
- **401 Unauthorized**: Invalid credentials
|
|
- **403 Forbidden**: No permission for topic
|
|
- **404 Not Found**: Topic doesn't exist
|
|
- **429 Too Many Requests**: Rate limit exceeded
|
|
|
|
## Best Practices
|
|
|
|
### Topic Naming
|
|
- Use **kebab-case**: `homelab-alerts`
|
|
- Be **descriptive**: `plex-transcoding-alerts`
|
|
- Group by **service**: `arr-suite-downloads`
|
|
- Include **environment**: `prod-database-alerts`
|
|
|
|
### Message Content
|
|
- **Clear titles**: Describe the issue/event
|
|
- **Actionable messages**: Include next steps
|
|
- **Consistent formatting**: Use templates
|
|
- **Appropriate priority**: Don't overuse high priority
|
|
|
|
### Security
|
|
- **Unique credentials**: Different users for different services
|
|
- **Minimal permissions**: Grant only necessary access
|
|
- **Regular rotation**: Change passwords periodically
|
|
- **Monitor usage**: Track message patterns
|
|
|
|
---
|
|
**Quick Access**: `https://ntfy.vish.gg` | **Admin**: monitoring:password | **Critical**: homelab-alerts |