proxmox-truenas - GitLite

KO | EN

gitlite — search

#python #hacktoberfest #typescript #llm #golang #machine-learning #rust #deep-learning #macos #java #awesome #vue #openai #open-source

proxmox-truenas

(★ 154)

TrueNAS over iSCSI for Proxmox VE

File Explorer

Download Latest Version (.zip)

- - release.yaml
- FUNDING.yml
- - Client.pm
  - Helpers.pm
- - .gitignore
  - apidoc.js.8.patch
  - apidoc.js.orig.patch
  - apidoc.js.patch
- - .gitignore
  - pvemanagerlib.js.8.patch
  - pvemanagerlib.js.9.patch
  - pvemanagerlib.js.orig.patch
.gitignore
.release-please-config.json
.release-please-manifest.json
_config.yml
build.sh
CHANGELOG.md
deploy.sh
LICENSE
README.md
version.txt

# Installation Guide

1. Get the code

git clone https://github.com/boomshankerx/proxmox-truenas

Downloads the entire project code from GitHub to your computer.

cd proxmox-truenas

Moves into the project folder you just downloaded.

2. Official Install Script

Easy Recommended

Prerequisites

APT (Debian/Ubuntu 계열) Built into Debian/Ubuntu-based Linux distributions.

apt install proxmox-truenas-native

Installs directly from the APT package repository (Debian/Ubuntu-based).

apt install proxmox-truenas

Installs directly from the APT package repository (Debian/Ubuntu-based).

✅ After installing, open a new terminal and run the program's version command (e.g. --version) to confirm it worked.

Pulled directly from this repo's README.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# TrueNAS over iSCSI

## Acknowledgement

This plugin was made possible by the great work at <https://github.com/TheGrandWazoo/freenas-proxmox>. It has been converted to be compatible with the TrueNAS WebSocket API. It is currently being targeted at Proxmox VE 8+ and TrueNAS 24.10+

## Donations

Thank you for supporting open-source. Made with love for the community.

[![Donate](https://github.com/user-attachments/assets/11a20af8-9bb0-4e42-97a3-35e753b0c8ba)](https://www.paypal.com/donate?hosted_button_id=QZD95HR69R8KA)

## Migrating from freenas-proxmox

1. Choose a node to migrate first and log into the WebUI of that node. Open a shell console
2. `sed -i 's/freenas/truenas/g' /etc/pve/storage.cfg`
3. `apt update && apt full-upgrade`
4. `apt purge freenas-proxmox`
5. `apt --purge autoremove` (freenas-proxmox has installed a perl restclient).
6. `apt reinstall pve-manager libpve-storage-perl`
7. Install proxmox truenas APT repository
8. Install the version of the plugin you intend to use Native or Patch. Please read compatibility carefully
9. Repeat steps 3-7 on each node in the cluster

## Known Issues

### iSCSI GET_LBA_STATUS and iscsidirect

```
qemu-img: iSCSI GET_LBA_STATUS failed at lba 0: SENSE KEY:ILLEGAL_REQUEST(5) ASCQ:INVALID_FIELD_IN_CDB(0x2400)
```

This is a known warning that occurs during disk migration or backup when using iscsidirect with TrueNAS. It should have no effect on data transfer or integrity. See the discussions below for more information.

https://forum.proxmox.com/threads/lsi-sas2308-scsi-controller-unsupported-sa-0x12.78785/  
https://bugzilla.proxmox.com/show_bug.cgi?id=4046

### TPM Storage

#### UPDATE

Proxmox has added support for TPM storage for ZFS over iSCSI in qemu-server: 9.1.10
https://bugzilla.proxmox.com/show_bug.cgi?id=3662

## APT Repository

GPG Key

```
curl -fsSL https://boomshankerx.github.io/proxmox-truenas-apt/gpg.key \
  | gpg --dearmor -o /etc/apt/keyrings/proxmox-truenas.gpg
```

[Repository](https://manpages.debian.org/sources.list)

```
. /etc/os-release
cat > /etc/apt/sources.list.d/proxmox-truenas.sources << EOF
Types: deb
URIs: https://boomshankerx.github.io/proxmox-truenas-apt
Suites: $VERSION_CODENAME
Components: main
Signed-By: /etc/apt/keyrings/proxmox-truenas.gpg
EOF
```

# TrueNAS over iSCSI Native Storage Plugin

**BOTH VERSIONS OF THIS PLUGIN CANNOT BE INSTALLED AT THE SAME TIME**

## Compatibility

- TrueNAS 25.10+  
- Proxmox VE 8/9

TrueNAS 25.10 has implemented API functionality that supports complete management of iSCSI disk storage.

There is currently no Web UI integration for this native plugin. Proxmox has indicated that they are working on the ability for storage plugins to better integrate into the WebUI. Progress updates can be tracked here: https://github.com/boomshankerx/proxmox-truenas/issues/113. Until then, the plugin can be configured in storage.cfg.

## Installation

```
apt update
apt install proxmox-truenas-native
```

## Configuration

### TrueNAS

<https://github.com/boomshankerx/proxmox-truenas/wiki/Configuration-Guide>

### Proxmox

#### pvesm

```
pvesm add truenas truenas \
--blocksize 16k \
--pool tank/proxmox \
--portal 10.0.0.1 \
--target iqn.2005-10.org.freenas.ctl:proxmox \
--shared 1 \
--sparse 1 \
--truenas_apikey <APIKEY> \
--truenas_apiv4_host 10.0.0.1 \
--truenas_use_ssl 1
```

#### storage.cfg

```
truenas: truenas
    blocksize 16k
    pool tank/proxmox
    portal 10.0.0.1
    shared 1
    sparse 1
    target iqn.2005-10.org.freenas.ctl:proxmox
    truenas_apikey <APIKEY>
    truenas_apiv4_host 10.0.0.1
    truenas_use_ssl 1
```

# TrueNAS Patch for ZFS over iSCSI (Deprecated)

**BOTH VERSIONS OF THIS PLUGIN CANNOT BE INSTALLED AT THE SAME TIME**

## Compatibility

- TrueNAS 24.10 - 25.10
- pve-manager 8.4.14 / 9.2.10  
- libpve-storage-perl 8.3.7 / 9.2.10

TrueNAS CORE 13.0U6.8 has been reported to work however it is not recommended due to lun limit in ctld  
See: <https://github.com/boomshankerx/proxmox-truenas/issues/56#issuecomment-3315936158>

## Installation

```
apt update
apt install proxmox-truenas
```

## Configuration

### TrueNAS iSCSI

This plugin requires that TrueNAS iSCSI is properly configured prior to connecting
<https://www.truenas.com/docs/scale/25.10/scaletutorials/shares/iscsi/addingiscsishares/#iscsi-manual-setup>

### TrueNAS API Key

<https://www.truenas.com/docs/scale/25.10/scaletutorials/toptoolbar/managingapikeys/>

### SSH Key

You will still need to configure the SSH connector for listing the ZFS Pools because this is currently being done in a Proxmox module (ZFSPoolPlugin.pm). To configure this please follow the steps at <https://pve.proxmox.com/wiki/Storage:_ZFS_over_iSCSI> that have to do with SSH between Proxmox VE and TrueNAS. The code segment should start out `mkdir /etc/pve/priv/zfs`.

1. Remember to follow the instructions mentioned above for the SSH keys.
2. Refresh the Proxmox GUI in your browser to load the new Javascript code.
3. Add your new TrueNAS ZFS-over-iSCSI storage using the TrueNAS-API.
4. Thanks for your support.

### Example Config (/etc/pve/storage.cfg)

Choose: truenas_apikey (Preferred)  OR  truenas_user + truenas_password

```
zfs: truenas
    blocksize 16k
    content images
    iscsiprovider truenas
    nowritecache 0
    pool tank/proxmox
    portal 10.0.0.1
    sparse 1
    target iqn.2005-10.org.freenas.ctl:proxmox
    truenas_apikey <APIKEY>
    truenas_apiv4_host 10.0.0.1
    truenas_password <PASSWORD>
    truenas_use_ssl 1
    truenas_user <USER>
```

## Star History
[![Star History Chart](https://api.star-history.com/svg?repos=boomshankerx/proxmox-truenas&type=date&legend=top-left)](https://www.star-history.com/#boomshankerx/proxmox-truenas&type=date&legend=top-left)