cv4pve-pepper 🌶️

🖥️ Simplified SPICE Remote Viewer Launcher for Proxmox VE

⭐ We appreciate your star, it helps! ⭐

🚀 Quick Start

# Download and extract (replace VERSION with actual version)
wget https://github.com/Corsinvest/cv4pve-pepper/releases/download/VERSION/cv4pve-pepper-linux-x64.zip
unzip cv4pve-pepper-linux-x64.zip

# Launch SPICE viewer for VM 100
./cv4pve-pepper --host=YOUR_HOST --username=root@pam --password=YOUR_PASSWORD \
                --vmid=100 --viewer=/usr/bin/remote-viewer

# With API token (recommended)
./cv4pve-pepper --host=YOUR_HOST --api-token=user@realm!token=uuid \
                --vmid=100 --viewer=/usr/bin/remote-viewer

📋 Table of Contents

🗂️ Click to expand navigation

🌟 Features
📦 Installation
⚙️ Configuration
🔧 Usage Examples
🖥️ SPICE Client Setup
🔐 Security & Authentication
🛠️ Troubleshooting
📊 Command Reference

🌟 Features

     ______                _                      __
    / ____/___  __________(_)___ _   _____  _____/ /_
   / /   / __ \/ ___/ ___/ / __ \ | / / _ \/ ___/ __/
  / /___/ /_/ / /  (__  ) / / / / |/ /  __(__  ) /_
  \____/\____/_/  /____/_/_/ /_/|___/\___/____/\__/

  🌶️ Launching SPICE remote-viewer for Proxmox VE (Made in Italy)

🏆 Core Capabilities

⚡ Simplified SPICE Access

✅ No GUI required - Pure command-line operation
✅ No .vv file downloads - Direct SPICE connection
✅ Automatic ticket management - Handles Proxmox VE tickets
✅ Cross-platform - Windows, Linux, macOS support
✅ Native C# implementation for reliability

🔧 Advanced Features

✅ Auto start/resume VMs on connection
✅ High availability support with multiple hosts
✅ Custom viewer options pass-through
✅ File-based configuration for automation
✅ SSL validation options

🛡️ Enterprise Ready

✅ API token authentication (Proxmox VE 6.2+)
✅ No root access required on Proxmox hosts
✅ External execution - runs outside Proxmox VE
✅ Multiple host support for cluster setups
✅ Secure authentication methods

🚀 User Experience

✅ Simple installation - single binary extraction
✅ Minimal configuration required
✅ Debug mode for troubleshooting
✅ Flexible proxy support for reverse proxies
✅ Wait for startup - configurable VM boot time

📦 Installation

🐧 Linux Installation

# Check available releases at: https://github.com/Corsinvest/cv4pve-pepper/releases
# Download specific version (replace VERSION with actual version)
wget https://github.com/Corsinvest/cv4pve-pepper/releases/download/VERSION/cv4pve-pepper-linux-x64.zip

# Extract
unzip cv4pve-pepper-linux-x64.zip

# Make executable
chmod +x cv4pve-pepper

# Optional: Move to system path
sudo mv cv4pve-pepper /usr/local/bin/

# Verify installation
cv4pve-pepper --version

🪟 Windows Installation

# Download from GitHub releases (replace VERSION with actual version)
Invoke-WebRequest -Uri "https://github.com/Corsinvest/cv4pve-pepper/releases/download/VERSION/cv4pve-pepper-win-x64.zip" -OutFile "cv4pve-pepper.zip"

# Extract
Expand-Archive cv4pve-pepper.zip -DestinationPath "C:\Tools\cv4pve-pepper"

# Add to PATH (optional)
$env:PATH += ";C:\Tools\cv4pve-pepper"

# Verify installation
cv4pve-pepper.exe --version

🍎 macOS Installation

# Download and extract (replace VERSION with actual version)
wget https://github.com/Corsinvest/cv4pve-pepper/releases/download/VERSION/cv4pve-pepper-osx-x64.zip
unzip cv4pve-pepper-osx-x64.zip
chmod +x cv4pve-pepper

# Move to applications
sudo mv cv4pve-pepper /usr/local/bin/

# Verify installation
cv4pve-pepper --version

🖥️ SPICE Client Setup

📋 Requirements

cv4pve-pepper requires a SPICE client (virt-viewer) to be installed on your system.

🐧 Linux SPICE Client

# Ubuntu/Debian
sudo apt update && sudo apt install virt-viewer

# CentOS/RHEL/Fedora
sudo dnf install virt-viewer

# Verify installation
which remote-viewer
# Should output: /usr/bin/remote-viewer

🪟 Windows SPICE Client

Download virt-viewer 0.5.6 or higher from SPICE official site
Install the package as Administrator
Note the path - typically: C:\Program Files\VirtViewer v?.?-???\bin\remote-viewer.exe

🍎 macOS SPICE Client

# Using Homebrew
brew install virt-viewer

# Or download from official site
# Note: macOS client may have limitations

📍 Common SPICE Client Paths

OS	Typical Path
Linux	`/usr/bin/remote-viewer`
Windows	`C:\Program Files\VirtViewer v?.?-???\bin\remote-viewer.exe`
macOS	`/usr/local/bin/remote-viewer`

⚙️ Configuration

🔐 Authentication Methods

🔑 Username/Password

cv4pve-pepper \
  --host=pve.local \
  --username=user@pam \
  --password=your_password \
  --vmid=100 \
  --viewer=/usr/bin/remote-viewer

🎫 API Token (Recommended)

cv4pve-pepper \
  --host=pve.local \
  --api-token=user@realm!token=uuid \
  --vmid=100 \
  --viewer=/usr/bin/remote-viewer

📁 Password from File

# Use interactive password prompt
cv4pve-pepper \
  --host=pve.local \
  --username=user@pam \
  --password=file:/etc/cv4pve/password \
  --vmid=100 \
  --viewer=/usr/bin/remote-viewer

# First run: prompts and saves password
# Later runs: reads from file

📄 Configuration Files

📋 Using Parameter Files

Create a configuration file for repeated use:

Create Configuration File

# /etc/cv4pve/pepper.conf
--host=pve.cluster.local
--api-token=spice@pve!viewer=uuid-here
--viewer=/usr/bin/remote-viewer
--viewer-options=-f --full-screen
--start-or-resume
--wait-for-startup=10

Use Configuration File

cv4pve-pepper @/etc/cv4pve/pepper.conf --vmid=100

🔧 Usage Examples

🖥️ Basic SPICE Connection

🔄 Simple VM Connection

Connect to VM by ID

cv4pve-pepper --host=pve.local --username=root@pam --password=secret \
              --vmid=100 --viewer=/usr/bin/remote-viewer

Connect to VM by Name

cv4pve-pepper --host=pve.local --api-token=user@pam!token=uuid \
              --vmid=web-server --viewer=/usr/bin/remote-viewer

Auto-start Stopped VM

cv4pve-pepper --host=pve.local --api-token=user@pam!token=uuid \
              --vmid=100 --viewer=/usr/bin/remote-viewer \
              --start-or-resume --wait-for-startup=15

🎛️ Advanced Options

⚙️ Viewer Customization

Full Screen Mode

cv4pve-pepper --host=pve.local --api-token=token \
              --vmid=100 --viewer=/usr/bin/remote-viewer \
              --viewer-options="-f"

Multiple Viewer Options

cv4pve-pepper --host=pve.local --api-token=token \
              --vmid=100 --viewer=/usr/bin/remote-viewer \
              --viewer-options="--full-screen --zoom=200"

Custom Proxy Configuration

cv4pve-pepper --host=pve.local --api-token=token \
              --vmid=100 --viewer=/usr/bin/remote-viewer \
              --proxy=https://spice-proxy.company.com:3128

🏢 High Availability Setup

🔄 Cluster Configuration

Multiple Proxmox Hosts

cv4pve-pepper --host=pve1.local:8006,pve2.local:8006,pve3.local:8006 \
              --api-token=cluster@pve!spice=uuid \
              --vmid=100 --viewer=/usr/bin/remote-viewer

SSL Certificate Validation

cv4pve-pepper --host=pve.company.com --validate-certificate \
              --api-token=secure@pve!token=uuid \
              --vmid=100 --viewer=/usr/bin/remote-viewer

🔧 Debug & Troubleshooting

🐛 Debug Mode

Enable Debug Output

cv4pve-pepper --host=pve.local --api-token=token \
              --vmid=100 --viewer=/usr/bin/remote-viewer \
              --debug

Test Connection Only

# Use --help to verify all parameters
cv4pve-pepper --host=pve.local --api-token=token --help

🔐 Security & Authentication

🛡️ Required Permissions

For SPICE access, the user/token needs minimal permissions:

Permission	Purpose	Scope
VM.Console	Access VM console	Virtual machines
VM.Audit	Read VM information	Virtual machines

🎫 API Token Setup

🔧 Creating SPICE Access Token

1. Create API Token

Follow Proxmox VE documentation for creating API tokens with the required permissions listed above.

2. Use Token in Commands

cv4pve-pepper --host=pve.local --api-token=spice@pve!viewer=uuid-from-creation \
              --vmid=100 --viewer=/usr/bin/remote-viewer

🔒 Security Best Practices

✅ Recommended

✅ Use API tokens instead of passwords
✅ Enable SSL certificate validation in production
✅ Use dedicated accounts for SPICE access
✅ Store credentials in secure configuration files
✅ Limit token permissions to minimum required

❌ Avoid

❌ Using root credentials for SPICE access
❌ Storing passwords in plain text scripts
❌ Disabling SSL validation without good reason
❌ Sharing tokens between different applications
❌ Using overly broad permissions

🛠️ Troubleshooting

⚠️ Common Issues & Solutions

🔌 "No SPICE Port" Error

Problem

Error: no spice port

Solution

This error appears when the VM's display hardware is not configured for SPICE:

Go to Proxmox web interface
Select your VM → Hardware
Edit Display device
Set Type to "SPICE (qxl)"
Start/restart the VM

🔐 Authentication Issues

Problem: "Authentication failed"

# Check credentials and permissions
cv4pve-pepper --host=pve.local --username=test@pam --password=wrong \
              --vmid=100 --viewer=/usr/bin/remote-viewer --debug

Solution

Verify credentials in Proxmox web interface
Check user permissions (VM.Console, VM.Audit)
Test API token format: user@realm!tokenid=uuid

🖥️ SPICE Client Issues

Problem: "Viewer not found"

# Test if remote-viewer is available
which remote-viewer
# or
/usr/bin/remote-viewer --version

Solution

Install virt-viewer package
Verify correct path to remote-viewer
Use full path in --viewer parameter

🌐 Network Issues

Problem: Connection timeouts

# Test with debug mode
cv4pve-pepper --host=pve.local --api-token=token \
              --vmid=100 --viewer=/usr/bin/remote-viewer --debug

Solution

Check network connectivity to Proxmox host
Verify firewall rules (port 8006 for API, SPICE ports)
Test with IP address instead of hostname

🔍 Debug Mode

🐛 Enabling Debug Output

# Enable detailed logging
cv4pve-pepper --host=pve.local --api-token=token \
              --vmid=100 --viewer=/usr/bin/remote-viewer \
              --debug

# Debug output will show:
# - API connection details
# - Authentication process
# - SPICE ticket generation
# - Viewer launch commands

📊 Command Reference

🔧 Global Options

⚙️ Complete Parameter List

cv4pve-pepper [options]

Connection Options

Parameter	Description	Example
`--host`	Proxmox host(s)	`--host=pve.local:8006`
`--username`	Username@realm	`--username=spice@pve`
`--password`	Password or file	`--password=secret`
`--api-token`	API token	`--api-token=user@realm!token=uuid`
`--validate-certificate`	Validate SSL certificate	`--validate-certificate`

VM & Viewer Options

Parameter	Description	Required
`--vmid`	VM ID or name	❌ Optional
`--viewer`	Path to remote-viewer	✅ Required
`--viewer-options`	Options for SPICE viewer	❌ Optional

Advanced Options

Parameter	Description	Default
`--proxy`	SPICE proxy server	None
`--start-or-resume`	Auto-start stopped/paused VM	`false`
`--wait-for-startup`	Wait seconds for VM startup	`5`
`--debug`	Enable debug output	`false`

📖 Usage Examples by Category

🎯 Common Use Cases

Basic Connection

# Simple connection
cv4pve-pepper --host=pve.local --username=root@pam --password=secret \
              --vmid=100 --viewer=/usr/bin/remote-viewer

# With API token
cv4pve-pepper --host=pve.local --api-token=spice@pve!token=uuid \
              --vmid=web-server --viewer=/usr/bin/remote-viewer

Production Setup

# HA cluster with SSL validation
cv4pve-pepper --host=pve1.local,pve2.local,pve3.local --validate-certificate \
              --api-token=production@pve!spice=uuid \
              --vmid=100 --viewer=/usr/bin/remote-viewer

# Auto-start with custom timeout
cv4pve-pepper --host=pve.local --api-token=token \
              --vmid=100 --viewer=/usr/bin/remote-viewer \
              --start-or-resume --wait-for-startup=30

Customized Viewer

# Full screen with high quality
cv4pve-pepper --host=pve.local --api-token=token \
              --vmid=100 --viewer=/usr/bin/remote-viewer \
              --viewer-options="--full-screen --zoom=150"

# Through reverse proxy
cv4pve-pepper --host=internal-pve.local --api-token=token \
              --vmid=100 --viewer=/usr/bin/remote-viewer \
              --proxy=https://proxy.company.com:3128

📞 Support & Community

🏢 Commercial Support

💼 Enterprise Support

Professional support and services

🌐 Official Website

Complete information and documentation

🤝 Community Resources

Resource	Description
GitHub Issues	Bug reports and feature requests
GitHub Discussions	Community Q&A and discussions
Proxmox Forum	General Proxmox VE community
cv4pve Documentation	Complete documentation suite

🔄 Contributing

We welcome contributions! Here's how you can help:

🐛 Report bugs via GitHub Issues
💡 Suggest features through GitHub Discussions
📖 Improve documentation with pull requests
🧪 Test releases and provide feedback
🌟 Star the repository to show support

📄 License

This software is part of the cv4pve-tools suite. For licensing details, please visit LICENSE.

_{Part of cv4pve-tools suite | Made with ❤️ in Italy by Corsinvest}

Name		Name	Last commit message	Last commit date
Latest commit History 49 Commits
.github/ISSUE_TEMPLATE		.github/ISSUE_TEMPLATE
.vscode		.vscode
src/Corsinvest.ProxmoxVE.Pepper		src/Corsinvest.ProxmoxVE.Pepper
.editorconfig		.editorconfig
.gitignore		.gitignore
3rd-party-licenses.md		3rd-party-licenses.md
Corsinvest.ProxmoxVE.Pepper.sln		Corsinvest.ProxmoxVE.Pepper.sln
Initialize-Tools.ps1		Initialize-Tools.ps1
LICENSE.md		LICENSE.md
README.md		README.md

License

Corsinvest/cv4pve-pepper

Folders and files

Latest commit

History

Repository files navigation

cv4pve-pepper 🌶️

🚀 Quick Start

📋 Table of Contents

🌟 Features

🏆 Core Capabilities

⚡ Simplified SPICE Access

🔧 Advanced Features

🛡️ Enterprise Ready

🚀 User Experience

📦 Installation

🐧 Linux Installation

🪟 Windows Installation

🍎 macOS Installation

🖥️ SPICE Client Setup

📋 Requirements

🐧 Linux SPICE Client

🪟 Windows SPICE Client

🍎 macOS SPICE Client

📍 Common SPICE Client Paths

⚙️ Configuration

🔐 Authentication Methods

🔑 Username/Password

🎫 API Token (Recommended)

📁 Password from File

📄 Configuration Files

Create Configuration File

Use Configuration File

🔧 Usage Examples

🖥️ Basic SPICE Connection

Connect to VM by ID

Connect to VM by Name

Auto-start Stopped VM

🎛️ Advanced Options

Full Screen Mode

Multiple Viewer Options

Custom Proxy Configuration

🏢 High Availability Setup

Multiple Proxmox Hosts

SSL Certificate Validation

🔧 Debug & Troubleshooting

Enable Debug Output

Test Connection Only

🔐 Security & Authentication

🛡️ Required Permissions

🎫 API Token Setup

1. Create API Token

2. Use Token in Commands

🔒 Security Best Practices

✅ Recommended

❌ Avoid

🛠️ Troubleshooting

⚠️ Common Issues & Solutions

Problem

Solution

Problem: "Authentication failed"

Solution

Problem: "Viewer not found"

Solution

Problem: Connection timeouts

Solution

🔍 Debug Mode

📊 Command Reference

🔧 Global Options

Connection Options

VM & Viewer Options

Advanced Options

📖 Usage Examples by Category

Basic Connection

Production Setup

Customized Viewer

📞 Support & Community

🏢 Commercial Support

💼 Enterprise Support

🌐 Official Website

Packages