238 lines
7.0 KiB
Markdown
238 lines
7.0 KiB
Markdown
# FreeNAS-Proxmox Plugin for Proxmox VE 9
|
|
|
|
This repository provides **complete Proxmox VE 9 compatibility** for the freenas-proxmox plugin, enabling seamless integration between Proxmox VE 9 and FreeNAS/TrueNAS systems for iSCSI storage management.
|
|
|
|
## 🚀 What's New in v2.0.0-pve9
|
|
|
|
- **Full Proxmox VE 9 compatibility** with architectural changes
|
|
- **Critical LUN 0 handling fix** - resolves VM startup failures
|
|
- **Improved error handling** and robust API communication
|
|
- **Enhanced FreeNAS.pm module** with complete method implementations
|
|
- **Automatic installation and patching scripts** for easy deployment
|
|
- **Comprehensive testing** and validation
|
|
|
|
## 🎯 Key Features
|
|
|
|
- **Complete iSCSI LUN management** through TrueNAS middleware API
|
|
- **Support for all LUN numbers** including LUN 0 (critical fix for PVE 9)
|
|
- **Cloud-init disk support** on TrueNAS storage
|
|
- **Automatic VM disk provisioning** and management
|
|
- **TrueNAS Core 13.0+ and TrueNAS Scale 22.12+ compatibility**
|
|
- **SSH-based secure communication** with TrueNAS systems
|
|
|
|
## 📋 Requirements
|
|
|
|
- **Proxmox VE 9.0+**
|
|
- **TrueNAS Core 13.0+ or TrueNAS Scale 22.12+**
|
|
- **SSH key authentication** between Proxmox and TrueNAS
|
|
- **iSCSI target configured** on TrueNAS
|
|
- **Root access** on Proxmox VE node
|
|
|
|
## 🔧 Installation
|
|
|
|
### New Installations
|
|
|
|
For new Proxmox VE 9 systems without existing freenas-proxmox plugin:
|
|
|
|
```bash
|
|
# Download the installer
|
|
wget https://raw.githubusercontent.com/TheGrandWazoo/freenas-proxmox/pve9-support/install-pve9.sh
|
|
|
|
# Make executable and run
|
|
chmod +x install-pve9.sh
|
|
sudo ./install-pve9.sh
|
|
```
|
|
|
|
### Existing Installations
|
|
|
|
For Proxmox VE 9 systems with existing freenas-proxmox plugin that needs PVE 9 fixes:
|
|
|
|
```bash
|
|
# Download the patcher
|
|
wget https://raw.githubusercontent.com/TheGrandWazoo/freenas-proxmox/pve9-support/patch-pve9.sh
|
|
|
|
# Make executable and run
|
|
chmod +x patch-pve9.sh
|
|
sudo ./patch-pve9.sh
|
|
```
|
|
|
|
## ⚙️ Configuration
|
|
|
|
### 1. SSH Key Setup
|
|
|
|
Configure SSH key authentication between Proxmox and TrueNAS:
|
|
|
|
```bash
|
|
# Create SSH key directory
|
|
mkdir -p /etc/pve/priv/zfs
|
|
|
|
# Generate SSH key (replace TRUENAS_IP with your TrueNAS IP)
|
|
ssh-keygen -f /etc/pve/priv/zfs/TRUENAS_IP_id_rsa
|
|
|
|
# Copy public key to TrueNAS
|
|
ssh-copy-id -i /etc/pve/priv/zfs/TRUENAS_IP_id_rsa.pub root@TRUENAS_IP
|
|
|
|
# Test connectivity
|
|
ssh -i /etc/pve/priv/zfs/TRUENAS_IP_id_rsa root@TRUENAS_IP "midclt call system.info"
|
|
```
|
|
|
|
### 2. TrueNAS iSCSI Configuration
|
|
|
|
Ensure your TrueNAS system has:
|
|
- **iSCSI service enabled**
|
|
- **Portal configured** with appropriate network settings
|
|
- **Target created** for Proxmox access
|
|
- **Authentication configured** (CHAP recommended)
|
|
|
|
### 3. Proxmox Storage Configuration
|
|
|
|
Add FreeNAS storage through the Proxmox web interface:
|
|
|
|
1. Navigate to **Datacenter → Storage → Add**
|
|
2. Select **"ZFS over iSCSI"** as storage type
|
|
3. Configure the following:
|
|
- **ID**: `freenas-storage` (or your preferred name)
|
|
- **Portal**: Your TrueNAS IP address
|
|
- **Target**: Your TrueNAS iSCSI target IQN
|
|
- **Pool**: ZFS pool name on TrueNAS
|
|
- **Block size**: `8k` (recommended)
|
|
- **iSCSI provider**: `freenas`
|
|
- **FreeNAS API host**: Your TrueNAS IP address
|
|
- **FreeNAS user**: `root`
|
|
- **FreeNAS password**: Your TrueNAS root password
|
|
- **Content**: Select `Disk image` and `Container` as needed
|
|
|
|
## 🐛 Critical Fixes Applied
|
|
|
|
### LUN 0 Handling Fix
|
|
|
|
**Problem**: Proxmox VE 9 had a critical bug where LUN 0 was treated as a falsy value, causing VM startup failures.
|
|
|
|
**Solution**: Fixed the condition check from `if !$guid` to `if !defined $guid` in ZFSPlugin.pm.
|
|
|
|
**Impact**: VMs with disks on LUN 0 can now start successfully.
|
|
|
|
### Return Format Compatibility
|
|
|
|
**Problem**: Function return formats between `list_lu` and `zfs_get_lun_number` were incompatible.
|
|
|
|
**Solution**: Standardized return formats to ensure proper data flow between functions.
|
|
|
|
**Impact**: Eliminates "unknown method" and parsing errors.
|
|
|
|
### Complete Method Implementation
|
|
|
|
**Problem**: Missing or incomplete LUN command methods in FreeNAS.pm.
|
|
|
|
**Solution**: Implemented all required methods with proper error handling.
|
|
|
|
**Impact**: Full iSCSI LUN management functionality.
|
|
|
|
## 🧪 Testing
|
|
|
|
After installation, test the integration:
|
|
|
|
### 1. Verify Storage Recognition
|
|
|
|
```bash
|
|
# Check storage status
|
|
pvesm status
|
|
|
|
# List available storage
|
|
pvesm list freenas-storage
|
|
```
|
|
|
|
### 2. Create Test VM
|
|
|
|
1. Create a new VM through Proxmox web interface
|
|
2. Select your FreeNAS storage for the disk
|
|
3. Start the VM and verify it boots correctly
|
|
|
|
### 3. Test Cloud-init Support
|
|
|
|
Create a VM with cloud-init enabled and verify the cloud-init disk is properly created on TrueNAS storage.
|
|
|
|
## 🔍 Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
**VM fails to start with "Could not find lu_name" error:**
|
|
- Ensure the patcher was applied correctly
|
|
- Check that FreeNAS storage is properly configured
|
|
- Verify SSH connectivity to TrueNAS
|
|
|
|
**iSCSI connection failures:**
|
|
- Verify TrueNAS iSCSI service is running
|
|
- Check network connectivity between Proxmox and TrueNAS
|
|
- Ensure proper authentication configuration
|
|
|
|
**Storage not appearing in Proxmox:**
|
|
- Verify ZFSPlugin.pm includes freenas provider support
|
|
- Check Proxmox service status: `systemctl status pvedaemon`
|
|
- Review logs: `/var/log/daemon.log`
|
|
|
|
### Debug Mode
|
|
|
|
To enable detailed debug logging:
|
|
|
|
```bash
|
|
# Enable debug logging
|
|
export PVE_DEBUG_STORAGE=1
|
|
|
|
# Restart pvedaemon
|
|
systemctl restart pvedaemon
|
|
|
|
# Check logs
|
|
tail -f /var/log/daemon.log | grep -i freenas
|
|
```
|
|
|
|
## 📝 Changelog
|
|
|
|
### v2.0.0-pve9 (2025-01-13)
|
|
|
|
**Added:**
|
|
- Complete Proxmox VE 9 compatibility
|
|
- Automated installation and patching scripts
|
|
- Comprehensive error handling and validation
|
|
- Enhanced documentation and troubleshooting guides
|
|
|
|
**Fixed:**
|
|
- Critical LUN 0 falsy value handling (prevents VM startup failures)
|
|
- Return format compatibility between plugin functions
|
|
- Provider integration in ZFSPlugin.pm
|
|
- Method implementations in FreeNAS.pm
|
|
|
|
**Improved:**
|
|
- SSH command execution and error handling
|
|
- API response parsing and validation
|
|
- Code organization and maintainability
|
|
|
|
## 🤝 Contributing
|
|
|
|
Contributions are welcome! Please:
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Test your changes thoroughly
|
|
4. Submit a pull request with detailed description
|
|
|
|
## 📄 License
|
|
|
|
This project is licensed under the GPL-3.0 License - see the [LICENSE](LICENSE) file for details.
|
|
|
|
## 🙏 Acknowledgments
|
|
|
|
- Original freenas-proxmox project by [TheGrandWazoo](https://github.com/TheGrandWazoo)
|
|
- Proxmox VE community for testing and feedback
|
|
- TrueNAS community for API documentation and support
|
|
|
|
## 📞 Support
|
|
|
|
- **GitHub Issues**: [Report bugs and request features](https://github.com/TheGrandWazoo/freenas-proxmox/issues)
|
|
- **Proxmox Forum**: [Community discussions](https://forum.proxmox.com/)
|
|
- **TrueNAS Forum**: [TrueNAS-specific questions](https://www.truenas.com/community/)
|
|
|
|
---
|
|
|
|
**⚠️ Important**: Always backup your Proxmox configuration before applying these patches. While thoroughly tested, modifications to system files should be approached with caution in production environments.
|