How-to guideTask-oriented

Install cetrafs on Proxmox VE

Quick install of the cetrafs packages, the pve-storage-cetrafs storage plugin and its web UI integration from their GitHub releases, on every node of a Proxmox VE cluster.

A Proxmox VE node needs these packages, all published as GitHub releases:

Package	From	Contents
`cetrafs-dkms`	cetrafs releases	The kernel module, built by DKMS for each kernel.
`cetrafs-tools`	cetrafs releases	`mkfs.cetra`, `fsck.cetra`, `defrag.cetra` and `growfs.cetra`.
`pve-storage-cetrafs`	cetrafs-proxmox releases	The Proxmox VE storage plugin: adds a `cetrafs` storage type.
`pve-storage-cetrafs-ui`	cetrafs-proxmox releases	Optional: the `cetrafs` storage type in the web UI, under Datacenter → Storage → Add → CetraFS. Needs Proxmox VE 9.

The storage plugin is optional but recommended. Without it, you mount the volume yourself and register it as directory storage, as in the Proxmox datastore tutorial.

The web UI package is optional too. Without it the storage works the same, but you manage it with pvesm, and the web UI lists it with type “Unknown”. The commands below install it; to leave it out, drop pve-storage-cetrafs-ui from them. See the web UI for how it works.

Install on every node

Every node, not just one

cetrafs and the plugin must be installed on every node of the cluster before you add a cetrafs storage. The storage configuration is shared by the whole cluster, and a node without the plugin can’t use, or even parse, a cetrafs entry. A node without the module can’t mount the volume.

1. Download the packages, on one node

As root, on any one node:

export VER=0.9.4 PVER=0.3
mkdir -p /root/cetrafs-$VER && cd /root/cetrafs-$VER

URL=https://github.com/cetrafs/cetrafs/releases/download/$VER
curl -fsSL --remote-name-all $URL/cetrafs-dkms_${VER}_all.deb $URL/cetrafs-tools_${VER}_amd64.deb
URL=https://github.com/cetrafs/cetrafs-proxmox/releases/download/$PVER
curl -fsSL --remote-name-all $URL/pve-storage-cetrafs_${PVER}_all.deb $URL/pve-storage-cetrafs-ui_${PVER}_all.deb

2. Install them on that node

(
    if [ -z "$VER" ] || [ -z "$PVER" ]; then
        echo "VER and PVER are not set: run the export line from step 1 first" >&2
        exit 1
    fi
    cd /root/cetrafs-$VER

    apt-get install -y proxmox-default-headers          # kernel headers, so DKMS can build the module
    apt-get install -y ./cetrafs-dkms_${VER}_all.deb ./cetrafs-tools_${VER}_amd64.deb \
                   ./pve-storage-cetrafs_${PVER}_all.deb ./pve-storage-cetrafs-ui_${PVER}_all.deb
)

3. Copy them to the other nodes

Cluster nodes already trust each other’s root SSH keys, so the same node can copy the packages to the rest of the cluster. On the node where you downloaded them:

(
    if [ -z "$VER" ] || [ -z "$PVER" ]; then
        echo "VER and PVER are not set: run the export line from step 1 first" >&2
        exit 1
    fi
    cd /root/cetrafs-$VER

    # every other node of the cluster, as "name address", from corosync.conf
    NODES=$(awk '/^[[:space:]]*name:/ {n=$2} /ring0_addr:/ {print n, $2}' /etc/pve/corosync.conf |
            grep -v "^$(hostname) ")

    echo "$NODES" | while read -r node addr; do
        echo "=== $node ($addr)"
        ssh -n -o HostKeyAlias=$node -o UserKnownHostsFile=/etc/pve/nodes/$node/ssh_known_hosts \
            root@$addr "mkdir -p /root/cetrafs-$VER" &&
        scp -q -o HostKeyAlias=$node -o UserKnownHostsFile=/etc/pve/nodes/$node/ssh_known_hosts \
            ./*.deb root@$addr:/root/cetrafs-$VER/
    done
)

Each node’s host key is checked against the one the cluster has recorded for it, the way Proxmox’s own migrations do.

4. Install them on the other nodes

Or let the node where you downloaded them do it over SSH:

(
    if [ -z "$VER" ] || [ -z "$PVER" ]; then
        echo "VER and PVER are not set: run the export line from step 1 first" >&2
        exit 1
    fi

    # every other node of the cluster, as "name address", from corosync.conf
    NODES=$(awk '/^[[:space:]]*name:/ {n=$2} /ring0_addr:/ {print n, $2}' /etc/pve/corosync.conf |
            grep -v "^$(hostname) ")

    echo "$NODES" | while read -r node addr; do
        echo "=== $node ($addr)"
        ssh -n -o HostKeyAlias=$node -o UserKnownHostsFile=/etc/pve/nodes/$node/ssh_known_hosts \
            root@$addr "cd /root/cetrafs-$VER &&
                apt-get install -y proxmox-default-headers &&
                apt-get install -y ./cetrafs-dkms_${VER}_all.deb ./cetrafs-tools_${VER}_amd64.deb ./pve-storage-cetrafs_${PVER}_all.deb ./pve-storage-cetrafs-ui_${PVER}_all.deb" ||
        echo "*** $node FAILED: install it there by hand, with step 2"
    done
)

It installs the packages on one node after another, and reports any node where the install fails.

About the packages

proxmox-default-headers follows the default Proxmox kernel series, so the headers for each new kernel arrive with the kernel and DKMS rebuilds the module automatically. If a node runs a kernel other than the default one, install its headers too: apt-get install -y proxmox-headers-$(uname -r).

Installing the plugin restarts the Proxmox API services (pvedaemon, pveproxy, pvestatd, pvescheduler) so they load it. Running guests are not affected.

pve-storage-cetrafs-ui must be the same version as pve-storage-cetrafs. After installing or upgrading it, reload the Proxmox web UI in your browser (Ctrl+F5) to see the CetraFS storage type.

Verify

From any node, check every node of the cluster, this one included. Each node prints one line:

awk '/^[[:space:]]*name:/ {n=$2} /ring0_addr:/ {print n, $2}' /etc/pve/corosync.conf |
while read -r node addr; do
    printf '%-12s ' "$node"
    ssh -n -o HostKeyAlias=$node -o UserKnownHostsFile=/etc/pve/nodes/$node/ssh_known_hosts \
        root@$addr '
            for p in cetrafs-dkms cetrafs-tools pve-storage-cetrafs pve-storage-cetrafs-ui; do
                s=$(dpkg-query -W -f="\${db:Status-Abbrev}\${Version}" $p 2>/dev/null)
                case "$s" in
                    ii*) printf "%s=%s " $p "${s#ii }" ;;
                    *)   printf "%s=MISSING " $p ;;
                esac
            done
            if dkms status cetrafs -k "$(uname -r)" 2>/dev/null | grep -q installed
            then echo "module=built"
            else echo "module=NOT-BUILT"
            fi' ||
    echo "UNREACHABLE"
done

A healthy cluster looks like this, with the same versions on every node:

pve1         cetrafs-dkms=0.9.4 cetrafs-tools=0.9.4 pve-storage-cetrafs=0.3 pve-storage-cetrafs-ui=0.3 module=built
pve2         cetrafs-dkms=0.9.4 cetrafs-tools=0.9.4 pve-storage-cetrafs=0.3 pve-storage-cetrafs-ui=0.3 module=built
pve3         cetrafs-dkms=0.9.4 cetrafs-tools=0.9.4 pve-storage-cetrafs=0.3 pve-storage-cetrafs-ui=0.3 module=built

MISSING means that package isn’t installed on the node. That is expected for pve-storage-cetrafs-ui if you chose not to install it. module=NOT-BUILT means DKMS has no module for the kernel the node is running: install that kernel’s headers (apt-get install -y proxmox-headers-$(uname -r)) and check dkms status cetrafs there.

Upgrade

Download the new releases and install them the same way, on every node: steps 1 to 4 above work for upgrades too. Keep cetrafs-dkms and cetrafs-tools at the same version on all nodes, and pve-storage-cetrafs and pve-storage-cetrafs-ui likewise. Read the cetrafs release notes first: if the on-disk format version changed, you have to move the data and reformat.

A new cetrafs-dkms builds the new module, but a mounted volume keeps running the old one until it is unmounted and the module is reloaded. The simplest way is to migrate the guests away and reboot the node, one node at a time.

Last updated 29 October 2026