# 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](https://docs.rafay.co/selfhosted/smtp_config/) 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](https://docs.rafay.co/selfhosted/smtp_config_admin/#day-0-initial-smtp-setup) 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.

1. Go to your [Google Account Security settings](https://myaccount.google.com/security)
2. Enable **2-Step Verification**
3. Navigate to **App passwords** and create a new entry (e.g., "Rafay Controller")
4. Copy the 16-character app password (remove spaces): e.g., `ckshciayrnftesxq`
5. 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:

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

2. 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
```