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

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. 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:

• --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)

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:

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:

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:

[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:

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

Complete Deployment Example

# 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	Core TLS implementation: TlsOptions struct, serve_tls function
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	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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}