Skip to content

SMTP Email Configuration

This guide explains how to configure SMTP email functionality in an on-premises controller. This configuration is useful for testing email alerts, user onboarding, password resets, and other email-driven workflows.

Prerequisites

  • Access to your controller's deployment config (config.yaml)
  • A valid SMTP provider (e.g., SendGrid, Gmail SMTP, Mailgun, etc.)
  • SMTP username and password (base64-encoded password)

Step 1: Base64 Encode Your SMTP Password

Before adding the SMTP config, base64 encode your plain-text password:

echo -n 'your-smtp-password' | base64

Copy the output and use it in the next step.

Step 2: Update Your SMTP Configuration

In your controller config (config.yaml), update or add the following block:

smtp:
  enabled: true                          # Enable SMTP
  smtp_address: "smtp.sendgrid.net"      # Your SMTP server address
  port: 587                              # 587 for TLS, 465 for SSL
  username: "apikey"                     # SMTP username (or email)
  password: "U3VwZXJTZWNyZXQxMjMh"       # Base64 encoded password
  insecure: false                        # Set true to skip TLS verification (not recommended)

Configuration Examples

Gmail SMTP Configuration

Gmail blocks basic auth for most accounts. Use App Passwords for better security.

  1. Go to https://myaccount.google.com/security
  2. Enable 2-Step Verification
  3. Go to App passwords
  4. Set App Name as "Mail" or "Other (Custom name)" (e.g., "Rafay Controller")
  5. Copy the 16-character app password without the spaces

Example: Password - cksh ciay rnft esxq → ckshciayrnftesxq

Step 2: Base64 Encode the App Password

echo -n 'ckshciayrnftesxq' | base64

Step 3: Configure SMTP in config.yaml

smtp:
  enabled: true
  smtp_address: "smtp.gmail.com"
  port: 587
  username: "your.email@gmail.com"
  password: "YWJjZCBkZWYgZ2hpIGprbCBtbg=="   # base64-encoded app password
  insecure: false

SendGrid SMTP Configuration

smtp:
  enabled: true
  smtp_address: "smtp.sendgrid.net"
  port: 587
  username: "apikey"
  password: "U3VwZXJTZWNyZXQxMjMh"
  insecure: false

Step 3: Apply the Configuration

For Day 0 (Initial Deployment)

Re-deploy your controller with the updated values file:

sudo ./radm dependency --config config.yaml
sudo ./radm application --config config.yaml

For Day 2 (Existing Controller)

If you need to apply SMTP configuration on an existing controller, update the config.yaml with the above configuration and run:

sudo ./radm application --config config.yaml

Disabling SMTP (Optional)

To disable SMTP, update the config as follows and reapply:

smtp:
  enabled: false

Then run:

sudo ./radm application --config config.yaml

Troubleshooting

  • Authentication Failed: Verify your SMTP credentials and ensure the password is correctly base64 encoded
  • Connection Timeout: Check your firewall settings and ensure the SMTP port is accessible
  • TLS Issues: If you encounter TLS certificate issues, you can temporarily set insecure: true for testing (not recommended for production)

Security Considerations

  • Always use base64 encoding for passwords in configuration files
  • Use App Passwords for Gmail instead of your main account password
  • Avoid setting insecure: true in production environments
  • Regularly rotate your SMTP credentials