# How to Set Up TLS Encryption for Switchyard-Server Production Deployment

> Secure your Switchyard server production deployment with TLS encryption. Easily enable HTTPS by providing your TLS cert and key files to the binary for robust security.

- Repository: [NVIDIA-NeMo/Switchyard](https://github.com/NVIDIA-NeMo/Switchyard)
- Tags: how-to-guide
- Published: 2026-08-15

---

**Enable HTTPS on the Switchyard server by passing `--tls-cert` and `--tls-key` PEM files to the binary; the server automatically wraps its Axum router with rustls when these flags are present.**

The **switchyard-server** binary supports production-grade TLS encryption out of the box through the `axum-server` crate with the `tls-rustls` feature. This guide walks through the complete setup process based on the actual implementation in the NVIDIA-NeMo/Switchyard repository.

## How TLS Works in Switchyard-Server

TLS support is implemented directly in [`crates/switchyard-server/src/lib.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-server/src/lib.rs). When the server starts, it checks the `ServerRunOptions.tls` field (lines 302–391). If TLS options are present, it calls `serve_tls`; otherwise, it falls back to plain HTTP.

The `serve_tls` function constructs a `RustlsConfig` using `RustlsConfig::from_pem_file`, then wraps the TCP listener with `axum_server::from_tcp_rustls` to serve HTTPS traffic.

The command-line interface enforces mutual dependency between the two TLS flags in [`crates/switchyard-server/src/cli.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-server/src/cli.rs):

- `--tls-cert`: Path to the PEM-encoded certificate
- `--tls-key`: Path to the PEM-encoded private key

Both flags must be provided together, or the CLI will reject the invocation.

## Generating TLS Certificates for Production

### Option 1: Self-Signed Certificate (Development/Testing)

```bash
openssl req -newkey rsa:2048 -nodes -keyout key.pem \
  -x509 -days 365 -out cert.pem -subj "/CN=my-switchyard"

```

### Option 2: CA-Signed Certificate (Production)

Obtain a certificate from your organization's certificate authority or a public CA like Let's Encrypt. Ensure the final files are:
- **PEM-encoded** (base64 ASCII with `BEGIN CERTIFICATE` headers)
- Unencrypted private key (or remove passphrase before deployment)

## Securing and Deploying Certificate Files

Store certificates in a protected directory with restricted permissions:

```bash
sudo mkdir -p /etc/switchyard
sudo cp cert.pem /etc/switchyard/
sudo cp key.pem /etc/switchyard/
sudo chmod 600 /etc/switchyard/key.pem
sudo chown switchyard:switchyard /etc/switchyard/*.pem

```

## Starting Switchyard-Server with TLS

Launch the server with both TLS flags and your desired bind address:

```bash
switchyard-server \
    --addr 0.0.0.0:443 \
    --tls-cert /etc/switchyard/cert.pem \
    --tls-key /etc/switchyard/key.pem \
    --config /etc/switchyard/config.toml

```

The server will listen on HTTPS and terminate TLS before routing requests to the Axum handler stack.

## Systemd Integration for Production

The repository includes a sample systemd unit at `dev-server/switchyard.service` (lines 5–6) with TLS flags already configured:

```ini
[Unit]
Description=Switchyard Server
After=network.target

[Service]
Type=notify
ExecStart=/usr/local/bin/switchyard-server \
    --addr 0.0.0.0:443 \
    --tls-cert /etc/switchyard/cert.pem \
    --tls-key /etc/switchyard/key.pem \
    --config /etc/switchyard/config.toml
Restart=on-failure

[Install]
WantedBy=multi-user.target

```

Deploy and enable the service:

```bash
sudo cp dev-server/switchyard.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now switchyard.service

```

## Complete Deployment Example

```bash

# 1. Generate certificates

openssl req -newkey rsa:2048 -nodes -keyout server.key \
  -x509 -days 365 -out server.crt -subj "/CN=switchyard.example.com"

# 2. Install with proper permissions

sudo install -d -m 750 -o switchyard -g switchyard /etc/switchyard
sudo install -m 644 -o switchyard -g switchyard server.crt /etc/switchyard/cert.pem
sudo install -m 600 -o switchyard -g switchyard server.key /etc/switchyard/key.pem

# 3. Verify configuration

switchyard-server \
  --tls-cert /etc/switchyard/cert.pem \
  --tls-key /etc/switchyard/key.pem \
  --config /etc/switchyard/config.toml \
  --dry-run

# 4. Start via systemd

sudo systemctl start switchyard.service

```

## Key Source Files

| File | Purpose |
|------|---------|
| [`crates/switchyard-server/src/lib.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-server/src/lib.rs) | Core TLS implementation: `TlsOptions` struct, `serve_tls` function |
| [`crates/switchyard-server/src/cli.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-server/src/cli.rs) | CLI flag definitions: `--tls-cert`, `--tls-key` with mutual requirement |
| `dev-server/switchyard.service` | Production systemd unit template |
| [`docs/cli_reference.md`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/docs/cli_reference.md) | Complete CLI documentation |

## Summary

- **TLS is opt-in**: Pass `--tls-cert` and `--tls-key` to enable HTTPS; omit both for HTTP
- **Rustls backend**: Uses `axum-server` with `tls-rustls`—no OpenSSL dependency
- **PEM format required**: Both certificate and key must be PEM-encoded
- **Production hardening**: Restrict key file permissions, use systemd for process management, prefer CA-signed certificates

## Frequently Asked Questions

### Does Switchyard support TLS 1.3?

Yes. The underlying `rustls` crate enables TLS 1.3 by default when using the `tls-rustls` feature in `axum-server`. No additional configuration is required.

### Can I use an encrypted private key with a passphrase?

No. The `RustlsConfig::from_pem_file` method used in [`crates/switchyard-server/src/lib.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-server/src/lib.rs) expects an unencrypted key file. Remove the passphrase before deployment: `openssl rsa -in encrypted.key -out unencrypted.key`.

### What happens if I provide only one TLS flag?

The CLI will exit with an error. The `clap` configuration in [`crates/switchyard-server/src/cli.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-server/src/cli.rs) specifies `requires = "tls_key"` on `--tls-cert` and vice versa, enforcing mutual presence.

### Does Switchyard support mutual TLS (mTLS) for client authentication?

Not in the current implementation. The `TlsOptions` struct and `serve_tls` function only configure server-side TLS. Client certificate verification would require extending the `RustlsConfig` builder in [`crates/switchyard-server/src/lib.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-server/src/lib.rs).