Administrator Guide (radm)

Controller-Level SMTP Configuration (radm)¶

This guide is intended for platform/system administrators with radm access. It covers initial SMTP setup during platform deployment (Day 0) and updating SMTP configuration post-deployment (Day 2).

Controller-level SMTP defines the platform-wide default email settings. These settings apply to all partners and organizations unless overridden at the partner or organization level. See SMTP Configuration for details on the override hierarchy.

Prerequisites¶

Access to your controller's deployment configuration (config.yaml)
A valid SMTP provider (e.g., SendGrid, Gmail, Mailgun)
SMTP credentials (password must be base64-encoded — see Step 1 below)

Day 0 — Initial SMTP Setup¶

Step 1: Base64 Encode Your SMTP Password¶

Before configuring SMTP, encode your plain-text SMTP password in base64:

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

Copy the output and use it in the next step.

Step 2: Update config.yaml¶

In your controller configuration file (config.yaml), add or update the smtp block:

smtp:
  enabled: true
  smtp_address: "smtp.example.com"   # SMTP server hostname
  port: 587                          # 587 for STARTTLS, 465 for SSL
  username: "your-smtp-username"     # SMTP login username
  password: "BASE64_ENCODED_PASSWORD"
  insecure: false                    # Set true to skip TLS verification (not recommended)

Example: SendGrid¶

smtp:
  enabled: true
  smtp_address: "smtp.sendgrid.net"
  port: 587
  username: "apikey"
  password: "U3VwZXJTZWNyZXQxMjMh"   # base64-encoded API key
  insecure: false

Example: Gmail¶

Gmail requires an App Password — basic authentication is blocked by default.

Go to your Google Account Security settings
Enable 2-Step Verification
Navigate to App passwords and create a new entry (e.g., "Rafay Controller")
Copy the 16-character app password (remove spaces): e.g., ckshciayrnftesxq
Base64-encode it:
```
echo -n 'ckshciayrnftesxq' | base64
```

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

Step 3: Deploy with radm¶

Run the following radm commands in order to apply the configuration:

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

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

radm will apply the SMTP settings and handle all required service configurations.

Day 2 — Updating SMTP Configuration¶

To update SMTP settings after the platform has been deployed:

Update the smtp block in config.yaml with the new values (re-encode the password in base64 if it has changed).

Re-run the radm deployment commands:

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

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

radm will apply the updated SMTP settings and handle all required service configurations and restarts.

Note: Incorrect SMTP values will silently prevent email delivery. After applying, validate the configuration using the Send Test Email option in the Ops Console or Web Console.

Disabling SMTP¶

To disable SMTP, update config.yaml and reapply using radm:

smtp:
  enabled: false

Run the radm deployment commands:

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

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