Install and run as systemd service (Linux)

[stephbu]

Summary

Create a Linux systemd-compatible service host for the DNS server, complementing the Windows Service support in #5.

Background

Issue #5 covers Windows NT Service support. This issue tracks the parallel effort for Linux deployments using systemd, which is the standard service manager on most modern Linux distributions.

Requirements

Service Host Project

• New project dns-service-systemd targeting net8.0
• Use Microsoft.Extensions.Hosting.Systemd for systemd integration
• Implement IHostedService pattern (shared with Install and run as NT Service #5 refactoring work)

Configuration

• Support config path resolution: CLI arg --config → env var DNS_SERVER_CONFIG_PATH → default /etc/dns-server/appsettings.json
• Environment variables settable via systemd unit file

Installation Assets

• Sample .service unit file (dns-server.service)
• Installation script (install.sh) that:
  • Copies binary to /usr/local/bin/ or /opt/dns-server/
  • Creates config directory /etc/dns-server/
  • Installs and enables the systemd unit file
  • Creates a dedicated service user (optional, for security)

Documentation

• Installation and configuration instructions
• Troubleshooting guide (journalctl, systemctl commands)
• Uninstall procedure

Depends On

• Phase 1 of Install and run as NT Service #5: Core refactoring to IHostedService pattern (shared infrastructure)

Acceptance Criteria

• dns-service-systemd project builds and runs on Linux
• Service starts/stops correctly via systemctl start/stop dns-server
• Service auto-starts on boot when enabled
• Logs visible via journalctl -u dns-server
• Clean install/uninstall via provided scripts
• Documentation added to README

References

• Microsoft.Extensions.Hosting.Systemd
• systemd.service manual

[stephbu]

Implementation Plan

Phase 1: Core Refactoring for Hosting (Shared Infrastructure)

This phase is shared with #5 (Windows Service) and should be completed first. It extracts the server lifecycle into IHostedService so it integrates cleanly with Microsoft.Extensions.Hosting.

Task	Description	Files
1.1	Create DnsHostedService implementing IHostedService that wraps the DNS server lifecycle (zone provider, resolver, DNS server, HTTP server)	Dns/Hosting/DnsHostedService.cs
1.2	Create extension method AddDnsServer(IServiceCollection, IConfiguration) for clean DI registration	Dns/Hosting/ServiceCollectionExtensions.cs
1.3	Refactor Dns/Program.cs - remove the monolithic Run() method, keep helper methods for service setup	Dns/Program.cs
1.4	Update dns-cli to use HostBuilder + IHostedService pattern (maintains existing console behavior)	dns-cli/Program.cs
1.5	Add hosted service lifecycle tests	dnstest/HostedServiceTests.cs
1.6	Verify all existing tests pass	CI

Phase 2: systemd Service Project

Task	Description	Files
2.1	Create project targeting net8.0 with Microsoft.Extensions.Hosting.Systemd	dns-service-systemd/dns-service-systemd.csproj
2.2	Implement Program.cs with Host.CreateDefaultBuilder().UseSystemd()	dns-service-systemd/Program.cs
2.3	Add config path resolution (CLI arg → env var → /etc/dns-server/appsettings.json)	dns-service-systemd/Program.cs
2.4	Add project to solution	csharp-dns-server.sln
2.5	Add sample appsettings.json for service deployment	dns-service-systemd/appsettings.json

Phase 3: Installation Assets

Task	Description	Files
3.1	Create systemd unit file with proper dependencies, user, and restart policies	dns-service-systemd/install/dns-server.service
3.2	Create installation script (copy binary, create dirs, install unit, create user)	dns-service-systemd/install/install.sh
3.3	Create uninstallation script	dns-service-systemd/install/uninstall.sh

Phase 4: Documentation & Testing

Task	Description	Files
4.1	Document systemd installation, configuration, and troubleshooting	README.md
4.2	Update AGENTS.md with new project description	AGENTS.md
4.3	Create detailed task doc with manual test procedures	docs/tasks/issue-35-systemd-service.md

---

Technical Details

systemd Unit File

# dns-server.service
[Unit]
Description=C# DNS Server
After=network.target
Wants=network-online.target

[Service]
Type=notify
ExecStart=/opt/dns-server/dns-service-systemd --config /etc/dns-server/appsettings.json
WorkingDirectory=/opt/dns-server
Restart=on-failure
RestartSec=10
User=dns-server
Group=dns-server

# Security hardening
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/log/dns-server

# Environment
Environment=DOTNET_ENVIRONMENT=Production
EnvironmentFile=-/etc/dns-server/environment

[Install]
WantedBy=multi-user.target

Installation Script Overview

#!/bin/bash
# install.sh

# 1. Create dns-server user/group (no login shell)
# 2. Create directories:
#    - /opt/dns-server/          (binary)
#    - /etc/dns-server/          (config)
#    - /var/log/dns-server/      (logs, if file logging enabled)
# 3. Copy binary and dependencies to /opt/dns-server/
# 4. Copy default config to /etc/dns-server/appsettings.json (if not exists)
# 5. Install unit file to /etc/systemd/system/dns-server.service
# 6. systemctl daemon-reload
# 7. systemctl enable dns-server (optional, prompt user)
# 8. Print next steps (systemctl start dns-server)

Folder Structure

dns-service-systemd/
├── dns-service-systemd.csproj
├── Program.cs                  # Entry point with Host builder
├── appsettings.json            # Default config template
└── install/
    ├── dns-server.service      # systemd unit file
    ├── install.sh              # Installation script
    └── uninstall.sh            # Uninstallation script

Config Path Resolution

// Priority order:
// 1. --config <path> argument
// 2. DNS_SERVER_CONFIG_PATH environment variable  
// 3. /etc/dns-server/appsettings.json (default)

string configPath = args.GetConfigPath() 
    ?? Environment.GetEnvironmentVariable("DNS_SERVER_CONFIG_PATH")
    ?? "/etc/dns-server/appsettings.json";

---

systemd Integration Features

Feature	How It Works
Service Notification	UseSystemd() sends READY=1 to systemd when host starts
Graceful Shutdown	Host responds to SIGTERM from systemctl stop
Watchdog	Optional: configure WatchdogSec= and call sd_notify("WATCHDOG=1")
Logging	Logs to stdout/stderr, captured by journald automatically
Status	Type=notify allows systemd to track actual readiness

---

Dependencies

• Microsoft.Extensions.Hosting.Systemd (for UseSystemd())

Estimated Effort

• Phase 1: ~4-6 hours (shared with Install and run as NT Service #5, may already be done)
• Phase 2: ~2-3 hours (systemd service project)
• Phase 3: ~2-3 hours (installation scripts and unit file)
• Phase 4: ~1-2 hours (documentation)

Testing Checklist

• Build on Linux (Ubuntu/Debian)
• install.sh creates user, directories, and installs service
• systemctl start dns-server starts successfully
• systemctl status dns-server shows "active (running)"
• journalctl -u dns-server shows logs
• systemctl stop dns-server stops gracefully
• systemctl restart dns-server restarts cleanly
• Service auto-starts after reboot (when enabled)
• uninstall.sh cleanly removes service