Skip to content

CHANGELOG.md

Latest commit

 

History

History
376 lines (304 loc) · 18 KB

CHANGELOG.md

File metadata and controls

376 lines (304 loc) · 18 KB

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

v0.10 — 2026-02-15

Added

  • Instance Removal via SSH: Delete instances using ssh /rm/instance.project@host or ssh /remove/instance.project@host commands

    • Force deletion with /rm-f/ or /remove-force/ to skip confirmation
    • Requires root host user for security
    • Automatically handles ephemeral instance cleanup
    • Shows instance details before confirmation

  • Login String Explanation: New /explain/ command decodes complex login strings

    • Example: ssh /explain/root@myinstance.default@host shows parsed components
    • Helps troubleshooting and onboarding

Improved

  • NixOS Compatibility: SSH authentication now checks /etc/ssh/authorized_keys.d/<user> in addition to ~/.ssh/authorized_keys
  • Non-Root Operation: Auto-detects process owner instead of hardcoding "root" as default host user for authentication
  • Web UI Reliability: Fixed empty instance list display when no containers are running
  • Image Selection: Web UI now supports selecting images from local or remote repositories
  • OS Detection: Enhanced OS detection for better web UI display of instance information
  • Config Viewer: Read-only CodeMirror modal for viewing multi-line configuration values
  • Terminal Font: Bundled monospace nerd font for consistent terminal/editor rendering

Changed

  • Web Dependencies: Updated to latest versions for improved security and features

v0.9 — 2025-12-23

Added

Web-Based User Interface

  • Modern Web Dashboard: New responsive web interface for managing Incus instances
  • Web-Based Terminal: Browser-based terminal emulation for instance shells
    • xterm.js integration with full terminal support
    • Persistent terminal sessions using tmux/screen

Instance Creation Web UI

  • Multi-Step Creation Wizard: Comprehensive 4-step instance creation interface
    • Step 1: Basic configuration (name, project, profile, image, resources)
    • Step 2: Advanced settings (configuration, devices)
    • Step 3: Cloud-init configuration with code editor
    • Step 4: Summary and review before creation
  • Profile-Based Configuration: Full profile integration in web UI
    • Profile selection with cumulative merge strategy (overlays on current config)
    • Applied profiles history tracking with badges
    • Reset button to revert to defaults
  • Device Management: Specialized editors for different device types
    • Proxy device editor with protocol selection (TCP/UDP/Unix), NAT mode, and address configuration
    • Disk device editor for mounting volumes and directories
    • Generic device editor for other device types
  • Cloud-Init Support:
    • Code editor with YAML and shell script syntax highlighting
    • Cloud-init support warning for non-cloud images
  • Image Selection: Searchable image aliases and metadata

Setup Profile Merging Algorithm

  • For Default Profile: Apply completely to all form fields
  • For Non-Default Profiles: Merge on top of current form state
    • Step 1 fields override current values
    • Step 2 config merges additively (profile overrides on key collision)
    • Step 2 devices merge (same device name overwrites, respects type)
    • Step 3 cloud-init overrides if provided

Migration Guide

For Users

  1. New web interface available at http://host:port (when enabled)
  2. Instance creation now possible via web UI without SSH login syntax
  3. Profile selection in web UI uses cumulative merging (not replacement)
  4. Form state auto-saves to browser localStorage

For Admins

  1. Enable web UI with --web|-W flag or web: true in config.yaml
  2. Configure web authentication with --web-auth user1:password1,user2:password2
  3. Set web UI listen address with --web-listen 0.0.0.0:8080 or web_listen: 0.0.0.0:8080 in config.yaml
  4. Instance creation profiles now support device configuration
  5. Cloud-init data can be preloaded from profiles in create-config.yaml

v0.8 — 2025-10-02

Added

Configuration File Support

  • YAML Configuration: New config.yaml file support for persistent server configuration
    • Configuration file loads from current directory, $HOME/.config/ssh2incus/, or /etc/ssh2incus/ (checked in order)
    • All configuration options available as YAML settings with same names as command-line flags
    • All options commented out by default to use system defaults
    • Command-line flags have higher priority than configuration file options
  • Flexible Configuration Management: Simplified server configuration without modifying system service files
    • Each YAML setting maps directly to corresponding command-line flag
    • Easy to enable/disable features by uncommenting configuration options
    • Better configuration organization and documentation

Enhanced Instance Creation Configuration

  • Profile-Based Instance Creation: New %profile syntax allows applying predefined configuration profiles during instance creation
    • Use %profile1+%profile2 in login string (e.g., ssh +instance+%web-server+%database@host)
    • Profiles are applied in order with later profiles overriding earlier ones
    • Direct configuration options always override profile settings
  • File Include Support: Configuration files now support external file includes
    • !include filename.ext syntax for loading file contents into configuration values
    • <@filename.ext alternative syntax for file includes
    • Smart path resolution: first tries relative to config file directory, then current working directory
  • Advanced Configuration Templates: Enhanced create-config.yaml with profile support
    • New profiles section for defining reusable configuration templates
    • Hierarchical configuration resolution: defaults → profiles → direct options
    • Support for complex multi-profile scenarios

Instance Creation Workflow Improvements

  • Configuration Override Hierarchy: Clear precedence order for configuration resolution
    • Base defaults from create-config.yaml
    • Applied profiles in specified order
    • Direct SSH login string options (highest priority)
  • Enhanced Login String Parsing: Improved parsing of complex instance creation syntax
    • Support for multiple profiles: +instance+%profile1+%profile2+options@host
    • Better error handling for malformed login strings
    • Validation of profile existence before instance creation

Built-in SFTP Server Enhancements

  • CHROOT Support: New -c flag enables chrooting to the start directory for enhanced security isolation
  • Directory Control: Enhanced -d flag for setting custom start directories in SFTP sessions
  • Security Improvements: Better privilege separation and directory access control

SSH Banner and Welcome Message Customization

  • Custom Banner Support: Server now looks for banner.txt file to display custom SSH login banners
  • Welcome Message: Optional welcome.txt file provides personalized welcome messages for users
  • Template Variables: Both banner and welcome files support template variables:
    • [INSTANCE_USER]: Current instance user
    • [INSTANCE]: Instance name
    • [PROJECT]: Project name
    • [REMOTE]: Remote server name
    • [HOSTNAME]: System hostname
  • Example Files: Provided banner.txt.example and welcome.txt.example templates in packaging

Improved Login String Parsing

  • Enhanced Parser: Completely refactored login string parsing with better modularity
  • Comprehensive Testing: Extensive test coverage for all login string formats and edge cases
  • Better Error Handling: Improved validation and error reporting for malformed login strings
  • Backward Compatibility: Maintained full compatibility with existing login string formats

Changed

Configuration System

  • Extended CreateConfig Structure: Enhanced configuration file format
    • Added profiles map for named configuration templates
    • Improved validation and error reporting for configuration files
    • Better handling of optional configuration sections
  • Enhanced File Processing: Improved LoadCreateConfig function
    • Added file include processing for both defaults and profile configurations
    • Better error messages for missing include files or invalid paths
    • Support for nested configuration scenarios

SFTP Server Implementation

  • Command-line Flags: Added support for standard OpenSSH SFTP server flags (-c, -d, -R, -e, -u, -l, -h)
  • Security Model: Enhanced security with proper chroot and directory change operations
  • Environment Integration: Better integration with UID/GID environment variables

Login String Processing

  • Modular Architecture: Split parsing logic into focused, testable functions
  • Performance Improvements: Optimized parsing for complex login string formats
  • Code Organization: Better separation of concerns for different login string components

Improved

User Experience

  • Intuitive Profile Usage: Simple syntax for applying complex configurations
    • Example: ssh +web01+%nginx+%ssl+ubuntu/24.04@host applies nginx and SSL profiles with Ubuntu 24.04
  • Flexible Configuration Management: Easy organization of instance templates
    • Separate profile files can be included via file include directives
    • Configuration inheritance allows for base profiles with specialized extensions
  • Better Error Handling: Enhanced error messages for configuration issues
    • Clear indication when profiles are missing or invalid
    • Better path resolution error reporting for file includes
  • Visual Feedback: Custom banners provide better visual identification of servers and instances
  • Personalization: Welcome messages can be customized per deployment
  • Security: SFTP chroot functionality provides better file access isolation

Development & Maintenance

  • Modular Configuration: Profile-based system enables better configuration organization
  • Template Reusability: Profiles can be shared across different instance creation scenarios
  • Configuration Validation: Enhanced validation ensures configuration consistency

Examples

Profile-Based Instance Creation

# Create instance with web-server profile
ssh -p 2222 +web01+%web-server@host

# Create instance with multiple profiles (database settings override web-server)
ssh -p 2222 +app01+%web-server+%database@host

# Override profile settings with direct options
ssh -p 2222 +dev01+%development+m16+c8@host

Configuration File with Profiles

version: 1
defaults:
  image: alpine/edge
  memory: 1
  cpu: 1

profiles:
  web-server:
    image: ubuntu/24.04
    memory: 2
    cpu: 2
    config:
      user.user-data: "!include web-server-init.yaml"

  database:
    memory: 4
    cpu: 2
    config:
      user.user-data: "<@database-setup.sh"

Technical Details

New Configuration Processing

  • File includes processed after YAML unmarshaling but before instance creation
  • Profile merging follows last-wins precedence for conflicting settings
  • Path resolution tries config directory first, then current working directory
  • Enhanced error reporting with specific failure contexts

SFTP Server Flags

  • -c: Enable chroot to start directory
  • -d DIR: Set start directory
  • -R: Read-only mode
  • -e: Debug to stderr
  • -u UMASK: Set explicit umask
  • -l LEVEL: Debug level (ignored for compatibility)
  • -h: Show help

Banner and Welcome File Locations

  • Files are searched in standard configuration directories
  • Template variable substitution occurs at runtime
  • Graceful fallback when files are not present

v0.7 — 2025-09-25

Added

Instance Creation on Demand

  • Dynamic Instance Creation: New syntax using + and ~ prefixes allows creating Incus instances on-demand via SSH login
  • Persistent Instances: Use + prefix (e.g., ssh +test01@host) to create persistent instances that remain until manually deleted
  • Ephemeral Instances: Use ~ prefix (e.g., ssh ~test01@host) to create ephemeral instances that auto-delete on poweroff
  • Configuration Parsing: Smart login parser supports inline instance configuration:
    • Image selection: +test01+ubuntu/24.04@host
    • Resource allocation: +test01+m4+c2+d20@host (4GB RAM, 2 CPUs, 20GB disk)
    • Advanced options: +test01+nest+priv+vm@host (nested, privileged, VM)
  • Default Templates: Integration with /etc/ssh2incus/create-config.yaml for standardized instance creation defaults

Authentication Enhancements

  • Password Authentication: Added --password-auth (-P) flag to enable password-based SSH authentication
  • Multi-Factor Authentication: New --auth-methods flag allows configuring authentication method chains (e.g., "publickey,password")
  • Advanced Password Hashing: Integrated yescrypt-go library for secure password hashing and verification

Terminal Session Management

  • Persistent Sessions: Added / prefix for persistent terminal sessions that survive SSH disconnections
  • Terminal Multiplexer Support: Added --term-mux (-T) flag to choose between tmux (default) and screen for persistent sessions
  • Built-in tmux Binary: Embedded static tmux binaries (arm64 and amd64) that are automatically deployed when tmux is not available in instances
  • Automatic Package Installation: System can now automatically install terminal multiplexers (tmux or screen) in instances when missing

System Package Management

  • Cross-Platform Package Installation: New InstallPackages() function with support for:
    • Debian-based systems (apt-get)
    • RHEL-based systems (dnf/yum)
    • Alpine Linux (apk)
  • Automatic OS Detection: Smart detection of instance operating systems via /usr/lib/os-release parsing
  • Package Manager Integration: Seamless integration with native package managers including proper environment handling

Instance Configuration Management

  • Create Config Support: New create-config.yaml functionality for standardized instance creation profiles
  • Configuration Templates: Support for instance configuration templates with memory, CPU, VM settings, devices, and config options
  • Fallback Configuration Paths: Smart configuration loading with multiple fallback paths and relative/absolute path resolution
  • Login Parser: Advanced login string parsing supporting complex instance creation syntax with multiple configuration options

Changed

Core Infrastructure

  • Go Runtime: Updated from Go 1.24.2 to Go 1.24.7
  • Incus API: Updated Incus client from v6.11.0 to v6.16.0 for latest container management features
  • Enhanced Argument Parsing: Improved command-line argument parsing with proper quoted string support and escape character handling
  • Authentication Flow: Refactored authentication system to support method chaining and more flexible auth configurations

Configuration Management

  • Expanded Server Config: Enhanced server configuration structure with new options:
    • TermMux: Terminal multiplexer selection
    • PassAuth: Password authentication toggle
    • AuthMethods: Authentication method chain configuration

Improved

User Experience

  • On-Demand Infrastructure: Create and connect to new instances in a single SSH command without pre-provisioning
  • Smart Package Handling: Instances automatically get required terminal multiplexer packages installed without manual intervention
  • Better Error Messages: Enhanced error reporting for authentication failures and configuration issues
  • Flexible Authentication: Users can now combine multiple authentication methods for enhanced security
  • Intuitive Syntax: Human-readable instance creation syntax (e.g., +test+ubuntu/24.04+m2+c2+d10+nest+priv)

Performance & Reliability

  • Optimized Dependencies: Cleaned up unused dependencies and optimized package imports
  • Better Resource Management: Improved handling of binary deployments and package installations
  • Enhanced Compatibility: Better compatibility with different Linux distributions and package managers

Dependencies

Added

  • github.com/openwall/yescrypt-go v1.0.0 - Advanced password hashing
  • Various container-related dependencies for enhanced Incus integration

Updated

  • github.com/lxc/incus/v6 v6.11.0 → v6.16.0
  • github.com/spf13/pflag v1.0.6 → v1.0.10
  • github.com/stretchr/testify v1.10.0 → v1.11.1
  • golang.org/x/crypto v0.36.0 → v0.42.0
  • golang.org/x/sys v0.32.0 → v0.36.0

Removed

  • github.com/peterh/liner - No longer needed with new terminal handling

Technical Details

New Command-Line Options

  • --password-auth / -P: Enable password authentication
  • --auth-methods: Configure authentication method chains
  • --term-mux / -T: Select terminal multiplexer (tmux/screen)

New SSH Login Syntax

  • +instance-name: Create persistent instance with defaults
  • ~instance-name: Create ephemeral instance with defaults
  • /instance-name: Connect with persistent terminal session
  • +instance+image+options: Create instance with specific configuration
  • Example: ssh +test01+ubuntu/24.04+m4+c2+d20+nest+priv+vm@host

Instance Creation Options

  • Images: Any valid Incus image (e.g., ubuntu/24.04, alpine/edge)
  • Resources: mN (memory GB), cN (CPU cores), dN (disk GB)
  • Features: nest (nesting), priv (privileged), vm (virtual machine)
  • Shortcuts: n=nest, p=priv, v=vm, e=ephemeral

New Configuration Files

  • /etc/ssh2incus/create-config.yaml: Instance creation configuration template

Architecture Support

  • Built-in tmux binaries for both ARM64 and AMD64 architectures
  • Cross-platform package management for major Linux distributions

v0.6 — 2025-04-07

Release with core SSH-to-Incus functionality, including:

  • Basic SSH server with Incus integration
  • Public key authentication
  • File transfer support (SCP/SFTP)
  • Port forwarding capabilities
  • SSH agent forwarding
  • Multi-remote support
  • Process modes (master/daemon)
  • Incus shell access