> ## Documentation Index
> Fetch the complete documentation index at: https://undyingterminal.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Server Configuration

> Configure Undying Terminal server behavior and settings

## Configuration File

The server reads configuration from:

```
%PROGRAMDATA%\UndyingTerminal\ut.cfg
```

Typical path: `C:\ProgramData\UndyingTerminal\ut.cfg`

## Configuration Format

INI-style format with key=value pairs:

```ini theme={null}
# Undying Terminal Server Configuration

# Network Settings
port=2022
bind_ip=0.0.0.0

# Logging
verbose=false

# Security (Optional)
shared_key_hex=<your-32-byte-hex-key>
```

## Configuration Options

### Network Settings

#### `port`

**Type**: Integer\
**Default**: `2022`\
**Description**: TCP port for server to listen on

```ini theme={null}
port=2022
```

<Tip>
  Choose a non-standard port (>1024) to avoid conflicts and reduce automated scans.
</Tip>

**Examples**:

```ini theme={null}
port=2022     # Default
port=8022     # Alternative (less likely to conflict)
port=22222    # High port number
```

#### `bind_ip`

**Type**: IP Address\
**Default**: `0.0.0.0`\
**Description**: IP address to bind server listener

```ini theme={null}
bind_ip=0.0.0.0
```

| Value          | Behavior                                     |
| -------------- | -------------------------------------------- |
| `0.0.0.0`      | Listen on all interfaces (default)           |
| `127.0.0.1`    | Listen only on localhost (local-only access) |
| `192.168.1.10` | Listen on specific interface                 |
| `::`           | Listen on all IPv6 interfaces                |

**Security Considerations**:

* Use `127.0.0.1` for local development
* Use `0.0.0.0` for remote access (combine with firewall rules)
* Use specific IP for multi-NIC servers

### Logging

#### `verbose`

**Type**: Boolean (`true` / `false`)\
**Default**: `false`\
**Description**: Enable verbose logging

```ini theme={null}
verbose=false
```

When `true`, server logs:

* Client connections/disconnections
* Packet types sent/received
* Named pipe events
* Tunnel creation/destruction

**Output**: Written to stdout/stderr

<Info>
  Verbose logging helps diagnose connection issues but increases log volume. Enable temporarily for debugging.
</Info>

### Security

#### `shared_key_hex`

**Type**: 64-character hex string (32 bytes)\
**Default**: None (encryption disabled)\
**Description**: Shared secret for XSalsa20 encryption

```ini theme={null}
shared_key_hex=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
```

**Encryption Details**:

* Algorithm: XSalsa20 (via libsodium)
* Key size: 32 bytes (256-bit)
* Nonce: 24 bytes (auto-incremented per packet)
* Applied to all client ↔ server communication

**Generate a Key**:

<CodeGroup>
  ```powershell PowerShell theme={null}
  # Generate random 32-byte hex key
  $bytes = New-Object byte[] 32
  [Security.Cryptography.RNGCryptoServiceProvider]::Create().GetBytes($bytes)
  $hexKey = -join ($bytes | ForEach-Object { $_.ToString("x2") })
  Write-Output "shared_key_hex=$hexKey"
  ```

  ```bash OpenSSL (MSYS2/Git Bash) theme={null}
  # Generate random 32-byte hex key
  openssl rand -hex 32
  ```
</CodeGroup>

<Warning title="Security Notice">
  * **Enable encryption** for internet-facing servers
  * Encryption provides **confidentiality only** (no authentication/MAC)
  * Passkey is still sent in plaintext during initial handshake
  * Consider using VPN for highly sensitive environments
</Warning>

## Example Configurations

### Development (Local Only)

```ini theme={null}
# Development configuration
# Local-only access, verbose logging, no encryption

port=2022
bind_ip=127.0.0.1
verbose=true
```

### Production (Internet-Facing)

```ini theme={null}
# Production configuration
# All interfaces, minimal logging, encryption enabled

port=2022
bind_ip=0.0.0.0
verbose=false
shared_key_hex=<generated-key-here>
```

### Multi-Server (Development)

When running multiple servers on one machine:

<CodeGroup>
  ```ini Server 1: ut.cfg theme={null}
  port=2022
  bind_ip=0.0.0.0
  verbose=false
  ```

  ```ini Server 2: ut2.cfg theme={null}
  port=2023
  bind_ip=0.0.0.0
  verbose=false
  ```
</CodeGroup>

Then use environment variables:

```powershell theme={null}
# Server 1 (default config, default pipe)
./undying-terminal-server.exe

# Server 2 (different port, different pipe)
$env:UT_PIPE_NAME = "\\\\.\\pipe\\undying-terminal-2023"
./undying-terminal-server.exe --port 2023
```

## Environment Variables

Override configuration at runtime:

### `UT_PIPE_NAME`

**Type**: String (Windows named pipe path)\
**Default**: `\\\\.\\pipe\\undying-terminal`\
**Description**: Override named pipe path

```powershell theme={null}
# Use custom pipe name
$env:UT_PIPE_NAME = "\\\\.\\pipe\\ut-custom"
./undying-terminal-server.exe
```

**Use Cases**:

* Running multiple servers on one machine
* Avoiding pipe name conflicts
* Development/testing isolation

<Note>
  Terminals must use the same `UT_PIPE_NAME` to connect to the correct server.
</Note>

### `UT_DEBUG_HANDSHAKE`

**Type**: Boolean (`1` = enabled)\
**Default**: Not set (disabled)\
**Description**: Enable packet-level debug output

```powershell theme={null}
$env:UT_DEBUG_HANDSHAKE = 1
./undying-terminal-server.exe
```

**Output**: Prints every packet type sent/received

**Example**:

```
[DEBUG] Sent: CONNECT_REQUEST
[DEBUG] Recv: CONNECT_RESPONSE (status=NEW_CLIENT)
[DEBUG] Sent: INITIAL_PAYLOAD
[DEBUG] Recv: INITIAL_RESPONSE
```

## Command-Line Flags

Override config file settings:

### `--port <PORT>`

```powershell theme={null}
./undying-terminal-server.exe --port 8022
```

### `--add-firewall`

Automatically add Windows Firewall rule:

```powershell theme={null}
# Run once to add firewall rule
./undying-terminal-server.exe --add-firewall
```

Creates rule:

* Name: "Undying Terminal Server"
* Direction: Inbound
* Protocol: TCP
* Port: Current port (from config or --port)
* Action: Allow

### `--service`

Run as Windows service:

```powershell theme={null}
# Install service
sc.exe create UndyingTerminalServer `
  binPath= "C:\Program Files\UndyingTerminal\undying-terminal-server.exe --service"

# Start service
sc.exe start UndyingTerminalServer
```

When running as service:

* Uses SYSTEM account
* Starts automatically on boot
* Logs to Windows Event Log
* Handles graceful shutdown

## Configuration Precedence

Settings are applied in this order (later overrides earlier):

1. **Defaults** (hardcoded in binary)
2. **Config file** (`%PROGRAMDATA%\UndyingTerminal\ut.cfg`)
3. **Environment variables** (`UT_PIPE_NAME`, etc.)
4. **Command-line flags** (`--port`, etc.)

**Example**:

```powershell theme={null}
# Config file: port=2022
# Command line: --port 8022
# Result: Server listens on 8022 (CLI wins)
```

## Firewall Configuration

### Windows Defender Firewall

<Tabs>
  <Tab title="Automatic">
    ```powershell theme={null}
    # Run server with --add-firewall once
    ./undying-terminal-server.exe --add-firewall
    ```

    This creates an inbound rule automatically.
  </Tab>

  <Tab title="Manual (PowerShell)">
    ```powershell theme={null}
    # PowerShell (Run as Administrator)
    New-NetFirewallRule `
      -DisplayName "Undying Terminal Server" `
      -Direction Inbound `
      -Protocol TCP `
      -LocalPort 2022 `
      -Action Allow `
      -Profile Any
    ```
  </Tab>

  <Tab title="Manual (GUI)">
    1. Open Windows Defender Firewall
    2. Click "Advanced settings"
    3. Right-click "Inbound Rules" → "New Rule..."
    4. Rule Type: **Port**
    5. Protocol: **TCP**, Port: **2022**
    6. Action: **Allow the connection**
    7. Profile: **All** (Domain, Private, Public)
    8. Name: **Undying Terminal Server**
  </Tab>
</Tabs>

### Third-Party Firewalls

Configure your firewall to allow:

* **Inbound TCP** on configured port (default 2022)
* **Application**: `undying-terminal-server.exe`

## Network Configuration

### Port Forwarding (Router)

To access the server from external networks:

<Steps>
  <Step title="Find Internal IP">
    ```powershell theme={null}
    ipconfig | findstr IPv4
    ```

    Example: `192.168.1.100`
  </Step>

  <Step title="Configure Router">
    In your router's admin panel:

    * **External Port**: `2022`
    * **Internal IP**: `192.168.1.100`
    * **Internal Port**: `2022`
    * **Protocol**: TCP
  </Step>

  <Step title="Test External Access">
    ```powershell theme={null}
    # From external network
    ./undying-terminal.exe --ssh <PUBLIC_IP> -l user
    ```
  </Step>
</Steps>

<Warning>
  **Security**: When exposing to the internet, **always enable encryption** via `shared_key_hex`.
</Warning>

## Performance Tuning

### High-Concurrency Environments

For >100 concurrent sessions:

```ini theme={null}
# Use dedicated network interface
bind_ip=192.168.1.100

# Disable verbose logging
verbose=false

# Enable encryption (adds ~1-2ms latency)
shared_key_hex=<key>
```

**OS Tuning** (Windows):

```powershell theme={null}
# Increase TCP connection limit (if needed)
netsh int tcp set global autotuninglevel=normal
```

### Low-Bandwidth Networks

```ini theme={null}
# Standard settings work well
# Keepalive traffic is minimal (~200 bytes/5s per session)

port=2022
bind_ip=0.0.0.0
verbose=false
```

**Client-Side**: Reduce keepalive frequency (requires recompile)

## Monitoring and Logs

### Check Server Status

```powershell theme={null}
# Verify server is listening
netstat -ano | findstr :2022

# Check process
tasklist | findstr undying-terminal-server
```

### View Logs

When `verbose=true`:

```powershell theme={null}
# Run server with output redirection
./undying-terminal-server.exe > server.log 2>&1

# Tail log file
Get-Content server.log -Wait -Tail 20
```

### Metrics to Monitor

| Metric             | Command                                                   | Normal Range                |
| ------------------ | --------------------------------------------------------- | --------------------------- |
| Active Connections | `netstat -ano \| findstr :2022 \| measure`                | 0-1000s                     |
| Memory Usage       | `tasklist /fi "imagename eq undying-terminal-server.exe"` | \~50MB + (5MB × sessions)   |
| CPU Usage          | Task Manager                                              | \<5% idle, \<20% under load |

## Backup and Recovery

### Backup Configuration

```powershell theme={null}
# Backup config file
Copy-Item "$env:PROGRAMDATA\UndyingTerminal\ut.cfg" `
          "C:\Backups\ut.cfg.$(Get-Date -Format 'yyyy-MM-dd')"
```

### Restore Configuration

```powershell theme={null}
# Restore from backup
Copy-Item "C:\Backups\ut.cfg.2024-01-15" `
          "$env:PROGRAMDATA\UndyingTerminal\ut.cfg"

# Restart server
Restart-Service UndyingTerminalServer
```

## Troubleshooting Configuration

<AccordionGroup>
  <Accordion title="Config file not found">
    **Error**: Server uses default settings

    **Solution**: Create config directory

    ```powershell theme={null}
    New-Item -ItemType Directory -Force -Path "$env:PROGRAMDATA\UndyingTerminal"
    ```
  </Accordion>

  <Accordion title="Invalid configuration value">
    **Error**: Server fails to start or uses default

    **Check**:

    * Valid port number (1-65535, typically >1024)
    * Valid IP address for `bind_ip`
    * 64-character hex string for `shared_key_hex`
    * `true`/`false` for boolean values
  </Accordion>

  <Accordion title="Encryption key mismatch">
    **Error**: Client can't connect (invalid handshake)

    **Cause**: Client and server have different encryption keys

    **Solution**: Ensure both use same `shared_key_hex` value
  </Accordion>

  <Accordion title="Port already in use">
    **Error**: `bind: address already in use`

    **Check what's using the port**:

    ```powershell theme={null}
    netstat -ano | findstr :2022
    ```

    **Solutions**:

    * Change port in config
    * Stop conflicting service
    * Use `--port` flag to override
  </Accordion>
</AccordionGroup>

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Encryption" icon="lock">
    * Enable `shared_key_hex` for production
    * Generate strong random keys (32 bytes)
    * Store keys securely
    * Rotate keys periodically
  </Card>

  <Card title="Network Isolation" icon="network-wired">
    * Use `bind_ip=127.0.0.1` for local-only
    * Use firewall rules to restrict access
    * Use VPN for sensitive environments
    * Avoid exposing to public internet
  </Card>

  <Card title="Access Control" icon="shield">
    * Use strong random passkeys
    * Limit who knows passkeys
    * Monitor active sessions
    * Audit connections regularly
  </Card>

  <Card title="Operational Security" icon="user-shield">
    * Run as Windows service (not user account)
    * Disable verbose logging in production
    * Monitor server logs
    * Keep software updated
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Client Options" icon="desktop" href="/config/client-options">
    Configure client behavior
  </Card>

  <Card title="Environment Variables" icon="code" href="/config/environment-variables">
    Runtime configuration options
  </Card>

  <Card title="Windows Service Guide" icon="windows" href="/guides/windows-service">
    Run server as a service
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/troubleshooting/common-issues">
    Solve configuration issues
  </Card>
</CardGroup>