Grafana Install Role

Overview

This role installs and configures Grafana on RedHat-based systems. It adds the official Grafana repository, installs the Grafana package, configures HTTPS with SSL certificates, sets up SMTP for email alerts via Gmail, deploys Synology SNMP MIB files, and enables the grafana-server service to start on boot.

Purpose

Automated Installation: Install Grafana from official repository
HTTPS Configuration: Secure web interface with SSL/TLS
Email Alerts: Configure SMTP for sending alert notifications
SNMP Monitoring: Deploy MIB files for Synology NAS monitoring
Service Management: Enable and start Grafana server
Centralized Visualization: Dashboard platform for metrics and logs

Requirements

Ansible 2.9 or higher
Collection: community.general (for ini_file module)
RedHat-based system (RHEL, CentOS, Rocky Linux, AlmaLinux)
SSL certificates deployed (see deploy_ssl_certificates role)
Internet access to rpm.grafana.com
For email alerts: Gmail account with app password
Proper sudo/root permissions

What is Grafana?

Grafana is an open-source analytics and visualization platform that:

Creates dashboards to visualize time-series data
Connects to multiple data sources (InfluxDB, Prometheus, MySQL, etc.)
Provides alerting and notification capabilities
Offers rich visualization options (graphs, tables, heatmaps, etc.)
Supports user management and permissions
Enables dashboard sharing and collaboration

Role Variables

Optional Variables

Variable	Default	Description
`grafana_install_protocol`	`https`	Web interface protocol (http or https)
`grafana_install_http_addr`	Auto-detected	IP address to bind web interface
`grafana_install_cert_file`	`/etc/pki/tls/certs/grafana.crt`	SSL certificate path
`grafana_install_cert_key`	`/etc/pki/tls/private/grafana.key`	SSL private key path
`grafana_install_smtp_enabled`	`true`	Enable SMTP for email alerts
`grafana_install_smtp_host`	`smtp.gmail.com:587`	SMTP server and port
`grafana_install_smtp_user`	From vault	SMTP username (Gmail email)
`grafana_install_smtp_password`	From vault	SMTP password (Gmail app password)
`grafana_install_smtp_from_address`	`admin@example.com`	From email address
`grafana_install_smtp_from_name`	`Grafana Alerts`	From name in emails
`grafana_install_smtp_starttls_policy`	`OpportunisticStartTLS`	StartTLS policy
`grafana_install_mibs_dest_dir`	`/usr/share/snmp/mibs/`	SNMP MIB files directory

Variable Details

grafana_install_protocol

Protocol for Grafana web interface.

Options:

https (default, recommended)
http (not recommended for production)

Example:

grafana_install_protocol: https

grafana_install_http_addr

IP address where Grafana binds its web interface. Auto-detected from inventory.

Default:

grafana_install_http_addr: "{{ hostvars['grafana']['ip_vlan10'] }}"

Custom example:

grafana_install_http_addr: "192.168.x.x"

Special values:

0.0.0.0: Listen on all interfaces
127.0.0.1: Localhost only
Specific IP: Bind to specific interface

grafana_install_cert_file and grafana_install_cert_key

SSL certificate and private key paths for HTTPS.

Default:

grafana_install_cert_file: /etc/pki/tls/certs/grafana.crt
grafana_install_cert_key: /etc/pki/tls/private/grafana.key

Note: Certificates must be deployed before running this role (see deploy_ssl_certificates role).

SMTP Configuration Variables

Required for email alert notifications.

Gmail App Password Setup:

Enable 2-Step Verification on your Google account
Go to https://myaccount.google.com/apppasswords
Generate app password for “Mail”
Store in Ansible Vault

Vault variables:

vault_grafana_smtp_user: "admin@example.com"
vault_grafana_smtp_password: "abcd efgh ijkl mnop"  # 16-character app password

SMTP configuration:

grafana_install_smtp_enabled: true
grafana_install_smtp_host: smtp.gmail.com:587
grafana_install_smtp_from_address: "admin@example.com"
grafana_install_smtp_from_name: "Grafana Homelab"
grafana_install_smtp_starttls_policy: "OpportunisticStartTLS"

StartTLS Policies:

OpportunisticStartTLS: Try TLS, fallback to plain (recommended for Gmail)
MandatoryStartTLS: Require TLS, fail if unavailable
NoStartTLS: Disable TLS (not recommended)

grafana_install_mibs_dest_dir

Directory for SNMP MIB files (used for monitoring Synology NAS via SNMP datasource).

Default: /usr/share/snmp/mibs/

Dependencies

This role requires:

deploy_ssl_certificates role (to deploy SSL certificates before Grafana installation)
SSL certificates placed at configured paths
Gmail account with app password (for SMTP alerts)
Ansible Vault for storing SMTP credentials

Example Playbook

Basic Usage

---
- name: Install Grafana
  hosts: grafana
  become: true

  roles:
    - grafana_install

With Custom Configuration

---
- name: Install Grafana with Custom Settings
  hosts: grafana
  become: true

  vars:
    grafana_install_protocol: https
    grafana_install_http_addr: "192.168.x.x"
    grafana_install_smtp_from_address: "monitoring@example.com"
    grafana_install_smtp_from_name: "Production Monitoring"

  roles:
    - grafana_install

HTTP Only (Development)

---
- name: Install Grafana with HTTP
  hosts: grafana_dev
  become: true

  vars:
    grafana_install_protocol: http

  roles:
    - grafana_install

Complete Infrastructure Playbook

---
- name: Deploy Grafana Infrastructure
  hosts: grafana
  become: true

  roles:
    - deploy_ssl_certificates  # Deploy certs first
    - grafana_install           # Install and configure Grafana
    - grafana_datasource_create # Create datasources
    - grafana_dashboards_restore # Import dashboards

What This Role Does

Adds Grafana YUM repository
- URL: https://rpm.grafana.com
- Enables GPG verification
- Configures SSL certificate verification
Installs Grafana package via dnf/yum
- Latest stable version from official repository
Enables and starts grafana-server service
- systemctl enable grafana-server
- systemctl start grafana-server
- Service starts on boot automatically
Configures server settings in /etc/grafana/grafana.ini:
- Protocol (HTTP or HTTPS)
- Bind address (IP)
- SSL certificate paths (if HTTPS)
- Creates backup of config file before changes
Configures SMTP settings for email alerts:
- Gmail SMTP server (smtp.gmail.com:587)
- Authentication credentials
- From address and name
- StartTLS encryption
Creates SNMP MIB directory (/usr/share/snmp/mibs/)
Copies Synology MIB files for SNMP monitoring
Restarts grafana-server if configuration changed (via handler)

Grafana Configuration File

The role modifies /etc/grafana/grafana.ini:

Server Section

[server]
protocol = https
http_addr = 192.168.x.x
cert_file = /etc/pki/tls/certs/grafana.crt
cert_key = /etc/pki/tls/private/grafana.key

SMTP Section

[smtp]
enabled = true
host = smtp.gmail.com:587
user = admin@example.com
password = app-password-here
from_address = admin@example.com
from_name = Grafana Alerts
startTLS_policy = OpportunisticStartTLS

Post-Installation Access

Default Credentials

First login:

URL: https://grafana-ip:3000
Username: admin
Password: admin
Change password immediately after first login

Service Management

# Check status
systemctl status grafana-server

# Start service
systemctl start grafana-server

# Stop service
systemctl stop grafana-server

# Restart service
systemctl restart grafana-server

# View logs
journalctl -u grafana-server -f

# Check config
grafana-cli admin settings

HTTPS Configuration

Certificate Requirements

Grafana requires:

Valid SSL certificate at configured path
Private key at configured path
Correct file permissions (readable by grafana user)

File permissions:

# Certificate (public)
-rw-r--r-- 1 root root grafana.crt

# Private key (restricted)
-rw-r----- 1 root grafana grafana.key

Verify HTTPS

# Test HTTPS access
curl -I https://grafana-ip:3000/login

# Should return: HTTP/1.1 200 OK

# Check certificate
openssl s_client -connect grafana-ip:3000 -showcerts

SMTP Email Alerts

Testing Email Configuration

Via Grafana UI:

Log into Grafana
Go to Alerting → Contact points
Click “New contact point”
Name: Email Test
Integration: Email
Addresses: your-email@example.com
Click “Test” button
Check your email for test message

Via Configuration Test:

# Check SMTP config in grafana.ini
grep -A 10 "\[smtp\]" /etc/grafana/grafana.ini

# Test SMTP manually
telnet smtp.gmail.com 587
# Should connect and show SMTP banner

Gmail App Password

Why app password is required:

Gmail blocks “less secure apps” by default
App passwords provide secure access without compromising main password
Works with 2-Step Verification enabled

Create app password:

Enable 2-Step Verification: https://myaccount.google.com/security
Generate app password: https://myaccount.google.com/apppasswords
Select app: “Mail”, device: “Other (Custom name)”
Name: “Grafana Alerts”
Copy 16-character password
Store in Ansible Vault

Synology MIB Files

Purpose

MIB (Management Information Base) files define SNMP objects for Synology NAS monitoring.

Enables monitoring of:

Disk status and health
System temperature
Network interfaces
Volume capacity
Service status

File Location

Role copies MIB files from:

roles/grafana_install/files/synology_mib_files/

To:

/usr/share/snmp/mibs/

Usage in Grafana

Install SNMP datasource plugin
Configure SNMP datasource with Synology NAS IP
MIB files automatically available for OID resolution
Create dashboards querying SNMP data

Firewall Configuration

Grafana listens on port 3000 (TCP):

# Open firewall port
firewall-cmd --permanent --add-port=3000/tcp
firewall-cmd --reload

# Verify
firewall-cmd --list-ports

Security Considerations

HTTPS: Role configures HTTPS by default (encrypted traffic)
Default Password: Change admin password immediately after installation
SMTP Password: Stored securely with no_log: true
Certificate Verification: Repository GPG keys verified
File Permissions: grafana.ini readable only by root and grafana group (mode 0640)
Private Key: Restricted to root:grafana
Config Backups: Role creates backup before modifying grafana.ini
Bind Address: Can restrict to specific interface (not 0.0.0.0)

Notes

Role supports RedHat-based systems only (uses dnf/yum)
Default port: 3000 (not configurable via this role)
Configuration changes trigger service restart via handler
SMTP is optional (disable with grafana_install_smtp_enabled: false)
Synology MIB files are homelab-specific
Role creates backup of grafana.ini before modifications
Grafana data directory: /var/lib/grafana/
Grafana logs: /var/log/grafana/

Troubleshooting

”Failed to download metadata for repo ‘grafana’”

Cause: Network connectivity issue or repository unavailable

Solution:

# Test repository access
curl -I https://rpm.grafana.com/

# Check DNS
nslookup rpm.grafana.com

# Verify GPG key
curl https://rpm.grafana.com/gpg.key

# Clear dnf cache
dnf clean all

“Cannot start grafana-server: certificate not found”

Cause: SSL certificate files missing or incorrect path

Solution:

# Verify certificate exists
ls -l /etc/pki/tls/certs/grafana.crt
ls -l /etc/pki/tls/private/grafana.key

# Check Grafana can read files
sudo -u grafana cat /etc/pki/tls/private/grafana.key

# Deploy certificates first
ansible-playbook site.yml --tags ssl

“Connection refused” when accessing Grafana

Cause: Service not running or firewall blocking

Solution:

# Check service status
systemctl status grafana-server

# Start if stopped
systemctl start grafana-server

# Check if listening
netstat -tlnp | grep 3000
# Should show: grafana-server listening on configured IP:3000

# Check firewall
firewall-cmd --list-ports
firewall-cmd --add-port=3000/tcp --permanent
firewall-cmd --reload

Email alerts not sending

Cause: SMTP configuration incorrect or Gmail blocking

Solution:

# Check SMTP config
grep -A 10 "\[smtp\]" /etc/grafana/grafana.ini

# Check Grafana logs for SMTP errors
tail -f /var/log/grafana/grafana.log | grep -i smtp

# Test Gmail credentials manually
curl --url 'smtps://smtp.gmail.com:465' \
  --ssl-reqd --mail-from 'admin@example.com' \
  --mail-rcpt 'test@example.com' \
  --user 'admin@example.com:app-password'

# Verify app password is correct (16 characters, no spaces)

“Bad Gateway” or 502 errors

Cause: Grafana backend not responding

Solution:

# Check Grafana logs
journalctl -u grafana-server -n 100

# Check disk space
df -h /var/lib/grafana

# Check database lock
lsof /var/lib/grafana/grafana.db

# Restart service
systemctl restart grafana-server

SSL certificate errors in browser

Cause: Self-signed certificate or CA not trusted

Solution:

Accept certificate exception in browser (temporary)
Add CA certificate to browser trust store (permanent)
Use certificate from trusted CA (Let’s Encrypt, etc.)

Check certificate:

openssl x509 -in /etc/pki/tls/certs/grafana.crt -text -noout

Testing After Installation

Verify Service Running

# Check service active
systemctl is-active grafana-server
# Should output: active

# Check service enabled
systemctl is-enabled grafana-server
# Should output: enabled

# Check process
ps aux | grep grafana-server

Test Web Interface

# Test HTTP(S) access
curl -k -I https://grafana-ip:3000/login

# Should return: HTTP/1.1 200 OK

# Test from browser
# Open: https://grafana-ip:3000
# Should see Grafana login page

Verify Configuration

# Check server section
grep -A 5 "\[server\]" /etc/grafana/grafana.ini

# Check SMTP section
grep -A 10 "\[smtp\]" /etc/grafana/grafana.ini

# Check MIB files deployed
ls -l /usr/share/snmp/mibs/ | grep -i synology

Test SMTP

Log into Grafana (admin/admin)
Change admin password
Go to Alerting → Contact points
Create email contact point
Click “Test” button
Check email inbox

Performance Considerations

Memory: Grafana uses 50-200 MB RAM typically
CPU: Low CPU usage when idle, spikes during dashboard rendering
Disk: ~50 MB for application, variable for database (dashboards, users)
Database: SQLite by default (suitable for small/medium deployments)
Concurrent Users: SQLite supports ~10-20 concurrent users

For larger deployments, consider:

External database (PostgreSQL, MySQL)
Increased memory allocation
SSD storage for faster dashboard loading

Best Practices

Change default password immediately after installation
Use HTTPS in production (already configured by role)
Configure SMTP for alert notifications
Regular backups of /var/lib/grafana/grafana.db
Use SSL certificates from trusted CA (Let’s Encrypt, etc.)
Restrict bind address to management network
Enable firewall with port 3000 only open to necessary networks
Monitor disk space for Grafana data directory
Update regularly for security patches
Use strong admin password (not default)

Upgrading Grafana

Check Current Version

grafana-cli --version
# Or check web UI: Help → About Grafana

Upgrade Process

# Backup database
cp /var/lib/grafana/grafana.db /var/lib/grafana/grafana.db.backup

# Backup config
cp /etc/grafana/grafana.ini /etc/grafana/grafana.ini.backup

# Update package
dnf update grafana

# Restart service
systemctl restart grafana-server

# Verify version
grafana-cli --version

Or via Ansible:

# Re-run role (will install latest from repository)
ansible-playbook site.yml --tags grafana

This role is often used with:

deploy_ssl_certificates: Deploy SSL certificates before Grafana installation
grafana_datasource_create: Create datasources in Grafana
grafana_dashboards_backup: Backup Grafana dashboards
grafana_dashboards_restore: Restore dashboards from backup
grafana_alerts_backup: Backup alert rules
influxdb: Install InfluxDB as datasource
telegraf_agent: Send metrics to InfluxDB for Grafana visualization

License

MIT

Author

Created for homelab infrastructure management.

Grafana Install

Grafana Install Role

Overview

Purpose

Requirements

What is Grafana?

Role Variables

Optional Variables

Variable Details

grafana_install_protocol

grafana_install_http_addr

grafana_install_cert_file and grafana_install_cert_key

SMTP Configuration Variables

grafana_install_mibs_dest_dir

Dependencies

Example Playbook

Basic Usage

With Custom Configuration

HTTP Only (Development)

Complete Infrastructure Playbook

What This Role Does

Grafana Configuration File

Server Section

SMTP Section

Post-Installation Access

Default Credentials

Service Management

HTTPS Configuration

Certificate Requirements

Verify HTTPS

SMTP Email Alerts

Testing Email Configuration

Gmail App Password

Synology MIB Files

Purpose

File Location

Usage in Grafana

Firewall Configuration

Security Considerations

Tags

Notes

Troubleshooting

”Failed to download metadata for repo ‘grafana’”

“Cannot start grafana-server: certificate not found”

“Connection refused” when accessing Grafana

Email alerts not sending

“Bad Gateway” or 502 errors

SSL certificate errors in browser

Testing After Installation

Verify Service Running

Test Web Interface

Verify Configuration

Test SMTP

Performance Considerations

Best Practices

Upgrading Grafana

Check Current Version

Upgrade Process

Related Roles

License

Author