FAQ

​

General Questions

​

What is Undying Terminal?

• Automatic reconnection with exponential backoff
• Sequence-based packet recovery (no data loss)
• 64MB recovery buffer per direction
• Keepalive heartbeat (every 5 seconds)

​

How is this different from SSH?

• Working from unstable networks (WiFi, mobile, VPN)
• Running long processes that can’t be interrupted
• Frequently switching networks
• Need persistent port forwarding

• Network is stable
• Quick one-off commands
• Need features not yet supported by Undying Terminal

​

Is this production-ready?

• Session persistence and recovery
• Port forwarding (forward and reverse)
• SSH bootstrap
• Jumphost support
• Optional encryption (XSalsa20)

• Windows-only

​

Can I use this on Linux or macOS?

• Use RDP/Remote Desktop into a Windows machine and run the client there
• Run a Windows VM and run the client there

​

What does “undying” mean?

• Disconnects → Automatic reconnect
• Laptop sleep → Recovers on wake
• VPN switch → Seamless transition
• Network change → Transparent recovery

​

Installation & Setup

​

Which Windows version do I need?

[System.Environment]::OSVersion.Version

• Windows 10 (1809+)
• Windows 11
• Windows Server 2019+

​

Do I need administrator rights?

• Windows Service installation
• Firewall rule creation (can use --add-firewall)
• System-wide PATH modification

​

How do I install as a Windows service?

# PowerShell (Run as Administrator)

# 1. Install service
sc.exe create UndyingTerminalServer `
  binPath= "C:\Program Files\UndyingTerminal\undying-terminal-server.exe --service" `
  start= auto `
  DisplayName= "Undying Terminal Server"

# 2. Start service
sc.exe start UndyingTerminalServer

# 3. Verify
sc.exe query UndyingTerminalServer

​

Can I run multiple servers on one machine?

# Server 1 (default)
./undying-terminal-server.exe

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

​

Connection & Usage

​

Why won’t my client connect?

1. Server running?
   Copy

   netstat -ano | findstr :2022
   
2. Correct client ID and passkey?
   • Must match terminal output exactly
   • Passkey is case-sensitive hex string
3. Firewall blocking?
   Copy

   # Add firewall rule
   ./undying-terminal-server.exe --add-firewall
   
4. Network reachable?
   Copy

   Test-NetConnection -ComputerName <HOST> -Port 2022
   
5. Encryption mismatch?
   • Server and client must both use same shared_key_hex
   • Or both have no encryption

$env:UT_DEBUG_HANDSHAKE = 1
./undying-terminal.exe --connect ...

​

How do I know if my session is alive?

1. Keepalive packets (automatic)
   • Client sends every 5 seconds
   • Server echoes back
   • If 3 missed → triggers reconnect
2. Send a command:
   Copy

   # In session
   echo "test"
   
   If output appears, session is alive.
3. Check server logs (if verbose=true):
   Copy

   [INFO] Client abc123 connected
   [INFO] Keepalive received from abc123
   

​

What happens when I disconnect?

1. Disconnect detected
   • Client notices (socket error or 3 missed keepalives)
   • Server keeps terminal alive
2. Reconnect attempts
   • Client: Exponential backoff (100ms → 2000ms)
   • Tries until successful
3. Recovery handshake
   • Exchange sequence numbers
   • Resend missed packets (up to 64MB)
   • Resume normal operation
4. User experience
   • Session continues where it left off
   • Recent output replayed (catchup)
   • New output streams normally

​

Can I reconnect from a different computer?

1. Copy client ID and passkey to new machine
2. Connect with same credentials
3. Server treats it as the same session

​

How do I disconnect safely?

• Client disconnects
• Server keeps session alive
• Terminal continues running
• Can reconnect anytime

# DON'T DO THIS:
exit           # Terminates terminal process
Ctrl+D         # Sends EOF (may exit shell)

• Shell exits
• Terminal process terminates
• Session ends
• Must restart terminal

​

Security

​

How secure is the encryption?

• Confidentiality (data is encrypted)
• No authentication (no MAC/AEAD)
• Passkey sent in plaintext initially

• Enable for internet-facing servers
• Use strong random keys (not passphrases)
• Combine with firewall rules
• Consider VPN for highly sensitive environments

• Government/military secrets
• Compliance-driven environments (use VPN)
• Scenarios requiring authentication

​

Should I expose this to the internet?

1. Enable encryption:
   Copy

   # ut.cfg
   shared_key_hex=<random-32-byte-hex>
   
2. Firewall rules:
   • Restrict by source IP if possible
   • Use non-standard port
   • Monitor failed connection attempts
3. Strong passkeys:
   • Use long random hex strings
   • Rotate periodically
   • Don’t share
4. Consider VPN:
   • For sensitive environments
   • Adds defense-in-depth
   • Better authentication

bind_ip=127.0.0.1  # Only accessible via VPN

​

How do I rotate encryption keys?

1. Generate new key:
   Copy

   $bytes = New-Object byte[] 32
   [Security.Cryptography.RNGCryptoServiceProvider]::Create().GetBytes($bytes)
   $newKey = -join ($bytes | ForEach-Object { $_.ToString("x2") })
   
2. Update server config:
   Copy

   # ut.cfg
   shared_key_hex=<NEW_KEY>
   
3. Restart server:
   Copy

   Restart-Service UndyingTerminalServer
   # OR
   # Kill and restart manually
   
4. Update all clients:
   • Existing sessions will disconnect
   • Clients must use new key to reconnect

​

Performance

​

What’s the latency overhead?

• Framing: ~0.5ms
• Sequence tracking: ~0.5ms
• Encryption (if enabled): ~0.5-1ms
• Network: (varies)

• SSH: 0.5-1ms overhead
• Mosh: 1-3ms (with prediction)

​

How much bandwidth does it use?

• Keepalive: ~200 bytes every 5 seconds
• ~40 bytes/second (~320 bps)

• Same as raw terminal output
• No compression (sent as-is)

• Same as direct TCP connection
• No additional overhead

​

How many concurrent sessions can I run?

• ~1000 concurrent sessions
• Limited by:
  • Thread count (1 thread per client + terminal)
  • Memory (~5MB per session)
  • Network bandwidth

• Monitor memory usage
• Scale vertically (more RAM/CPU)
• Not designed for horizontal scaling

​

Troubleshooting

​

Server won’t start - port already in use

netstat -ano | findstr :2022
# Note the PID, then:
tasklist | findstr <PID>

1. Change port in config:
   Copy

   port=2023
   
2. Kill conflicting process:
   Copy

   Stop-Process -Id <PID> -Force
   
3. Use command-line override:
   Copy

   ./undying-terminal-server.exe --port 2023
   

​

Session is very slow

1. Network latency:
   Copy

   ping <server-host>
   # Check latency
   
2. Packet loss:
   • High packet loss triggers frequent catchup
   • Check network quality
3. Large recovery buffer:
   • Replaying 64MB on reconnect takes time
   • Wait for catchup to complete
4. Server overload:
   • Check CPU/memory on server
   • Reduce concurrent sessions

$env:UT_DEBUG_HANDSHAKE = 1
# Watch for excessive catchup messages

​

Terminal output is garbled

1. Terminal resize mismatch:
   • Resize client window
   • Terminal should auto-adjust
2. Shell encoding issues:
   • Ensure UTF-8 encoding
   • Check $OutputEncoding in PowerShell
3. ConPTY issues:
   • Restart terminal process
   • Update Windows (ConPTY bugs fixed in newer builds)

cls     # CMD
clear   # PowerShell

​

Advanced Topics

​

Can I modify the keepalive interval?

constexpr auto kKeepaliveInterval = std::chrono::seconds(5);
// Change to desired interval

​

How does the recovery buffer work?

• BackedWriter: Last 64MB of sent packets
• BackedReader: Sequence number tracker
• Catchup: Resend missed packets on reconnect

• 64MB per direction (128MB total)
• FIFO queue (oldest packets dropped)

​

Can I run the client on Linux?

​

Roadmap

​

How can I contribute?

• 🐛 Report bugs
• 📝 Improve documentation
• 💻 Submit pull requests
• 🧪 Test on different Windows versions
• 💬 Help triage GitHub issues

​

Getting Help

​

Where can I get support?

1. Check this FAQ
2. Search existing issues
3. Enable debug logging ($env:UT_DEBUG_HANDSHAKE=1)

• Windows version
• Undying Terminal version
• Error messages (full output)
• Steps to reproduce