Skip to content

session-restore.md

Latest commit

 

History

History
318 lines (235 loc) · 8.31 KB

session-restore.md

File metadata and controls

318 lines (235 loc) · 8.31 KB

Feature: Session Restore

Automatically restore all active azlin VM sessions with new terminal windows.

Overview

The azlin restore command provides one-command restoration of ALL running VM sessions. It automatically detects yer platform, finds all active VMs, and launches appropriate terminal windows with SSH connections.

Key Features

1. Smart Platform Detection

Automatically detects operating system and selects appropriate terminal:

  • macOS: Terminal.app
  • Windows: Windows Terminal (wt.exe)
  • WSL: Windows Terminal with WSL integration
  • Linux: gnome-terminal (fallback to xterm)

2. Multi-Tab Support (Windows Terminal)

Opens all sessions efficiently:

  • Single window mode: All VMs as tabs in one Windows Terminal window
  • Multi-window mode: Separate window fer each VM (configurable)

3. Automatic Session Management

Connects to existing tmux sessions or creates new ones:

  • Attaches to existing session if available
  • Creates new session with configured name if not
  • Supports custom session name mappings per VM

4. Dry-Run Mode

Preview restore operations without launching terminals:

azlin restore --dry-run

Shows:

  • Platform detection results
  • VMs that would be restored
  • Terminal commands that would execute
  • Session mappings and SSH keys

5. Flexible Configuration

Configure behavior via ~/.azlin/config.toml:

  • Override terminal launcher
  • Set session name mappings
  • Configure timeouts
  • Enable/disable multi-tab mode

6. Multi-Session Per VM

Each tmux session runnin' on a VM gets its own terminal tab or window. If a VM has multiple tmux sessions (say, one fer yer dev server and another fer tailing logs), azlin restore opens a separate tab fer each one — no sessions left behind in Davy Jones' locker.

  • One tab per session: Every active tmux session on a VM spawns its own terminal tab/window
  • Safety limit: A maximum of 20 sessions per VM (MAX_SESSIONS_PER_VM) prevents a rogue VM from openin' a broadside of tabs across yer screen
  • Warning on limit: When a VM exceeds the 20-session limit, ye'll see a warning like: 
    Warning: frontend-vm has 34 tmux sessions, only restoring first 20 (MAX_SESSIONS_PER_VM)

Use Cases

Morning Routine - Restore Work Environment

After system reboot or disconnection:

azlin restore

Instantly reopens all development VMs with proper sessions.

Multi-Project Development

Restore only specific resource group:

azlin restore --resource-group frontend-rg
azlin restore --resource-group backend-rg

Network Recovery

After VPN reconnection or network disruption:

azlin restore

Re-establishes all SSH connections with preserved tmux sessions.

Multi-Monitor Workflow

Disable multi-tab to spread sessions across monitors:

azlin restore --no-multi-tab

Example Workflows

Workflow 1: Development Team Morning Standup

# Team member arrives
azlin list  # Shows 3 VMs running from yesterday

# One command restores all sessions
azlin restore

# Output:
# ✓ frontend-vm → session: react-dev
# ✓ frontend-vm → session: webpack
# ✓ backend-vm → session: api-server
# ✓ backend-vm → session: logs
# ✓ database-vm → session: psql

# All sessions preserved from yesterday — every last one of 'em

Workflow 2: Multi-Environment Testing

# Preview environments
azlin restore --dry-run

# Restore dev environment
azlin restore --resource-group dev-rg

# Restore staging (in separate windows)
azlin restore --resource-group staging-rg --no-multi-tab

# Each environment isolated in its own terminals

Workflow 3: After Laptop Sleep/Resume

# Laptop wakes from sleep
# SSH connections dropped

# Single command reconnects everything
azlin restore

# All sessions back online
# No manual reconnection needed

Architecture Integration

Platform Detection Layer

User Command
    ↓
Platform Detector (PlatformDetector.detect_platform())
    ↓
Terminal Launcher Factory (TerminalLauncher.get_launcher())
    ↓
Platform-Specific Launcher
    ↓
Terminal Windows

Session Configuration Flow

User Config (~/.azlin/config.toml)
    ↓
Config Manager (load_config())
    ↓
VM Manager (list_vms())
    ↓
Session Config Builder (RestoreSessionConfig)
    ↓
Terminal Launcher (launch_all_sessions())
    ↓
SSH Connections + Tmux Attachment

Security Considerations

All connections use:

  • SSH key authentication (no passwords)
  • Per-VM SSH keys (optional)
  • Standard SSH security options:
    • StrictHostKeyChecking=no (for dynamic IPs)
    • UserKnownHostsFile=/dev/null (avoids conflicts)

See Security Review fer complete analysis.

Performance Characteristics

Scenario Sessions Time Method
macOS 3 VMs ~2-3s Sequential launch
Windows (multi-tab) 5 VMs ~1-2s Single window
Windows (separate) 5 VMs ~3-5s Multiple windows
WSL 3 VMs ~3-5s Cross-boundary launch
Linux 3 VMs ~2-3s Sequential launch

Note: Times include platform detection, VM discovery, and terminal launch. Actual SSH connection time varies by network.

Configuration Examples

Minimal Configuration

# Use defaults fer everything
default_resource_group = "my-rg"

Full Configuration

# Override terminal detection
terminal_launcher = "windows_terminal"
terminal_multi_tab = true
restore_timeout = 60

# Custom session names
[session_names]
"frontend-vm" = "react-dev"
"backend-vm" = "api-server"
"database-vm" = "postgres"

# Per-VM SSH keys
[vm_ssh_keys]
"production-vm" = "~/.ssh/prod_key"

Platform-Specific Configurations

See Configuration Reference fer complete examples.

Error Handling

The command provides clear error messages fer common issues:

No VMs Found

Error: No running VMs found
→ Run 'azlin list' to see available VMs

Terminal Launch Failed

Error: Terminal launch failed fer 2/3 VMs
→ Check terminal configuration in config.toml
→ See troubleshooting guide

SSH Connection Issues

Warning: Could not connect to VM 'dev-vm-1'
→ Check SSH key: ~/.ssh/id_rsa
→ Verify VM is accessible: ssh azureuser@10.0.1.4

Comparison with Manual Workflow

Before azlin restore

# Manual restore (4-5 minutes)
azlin list  # Check VMs
azlin connect dev-vm-1  # First VM
# Wait fer connection...
# Open new terminal
azlin connect test-vm-2  # Second VM
# Wait fer connection...
# Open new terminal
azlin connect prod-vm-3  # Third VM
# Wait fer connection...
# Total: 3 separate commands, 4-5 minutes

With azlin restore

# Automated restore (5-10 seconds)
azlin restore
# All VMs connected simultaneously
# Total: 1 command, 5-10 seconds

Time Savings: 85-90% reduction fer 3+ VMs

Limitations

  1. Terminal Required: Must have compatible terminal installed
  2. Tmux Dependency: VMs must have tmux installed fer session management
  3. Platform-Specific: Behavior varies by platform (multi-tab only on Windows Terminal)
  4. Network Required: Active network connection to Azure
  5. Session Limit: Maximum of 20 tmux sessions restored per VM (MAX_SESSIONS_PER_VM). Any sessions beyond that be left on the dock with a warning.

Future Enhancements

Potential improvements (not yet implemented):

  • Custom terminal profiles per VM
  • Automatic VM startup before restore
  • Session layout configuration (split panes, window arrangement)
  • Terminal window positioning (coordinates, monitor selection)

Documentation

Complete documentation available:

See Also