Skip to content

Instantly share code, notes, and snippets.

@scyto

scyto/proxmox-tb-net.md

Last active June 5, 2026 05:43
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save scyto/67fdc9a517faefa68f730f82d7fa3570 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save scyto/67fdc9a517faefa68f730f82d7fa3570 to your computer and use it in GitHub Desktop.
Download ZIP
Thunderbolt Networking Setup
Raw
proxmox-tb-net.md

Thunderbolt Networking

this gist is part of this series

you wil need proxmox kernel 6.2.16-14-pve or higher.

Load Kernel Modules

  • add thunderbolt and thunderbolt-net kernel modules (this must be done all nodes - yes i know it can sometimes work withoutm but the thuderbolt-net one has interesting behaviou' so do as i say - add both ;-)
    1. nano /etc/modules add modules at bottom of file, one on each line
    2. save using x then y then enter

Prepare /etc/network/interfaces

doing this means we don't have to give each thunderbolt a manual IPv6 addrees and that these addresses stay constant no matter what Add the following to each node using nano /etc/network/interfaces

If you see any sections called thunderbolt0 or thunderbol1 delete them at this point.

Create entries to prepopulate gui with reminder

Doing this means we don't have to give each thunderbolt a manual IPv6 or IPv4 addrees and that these addresses stay constant no matter what.

Add the following to each node using nano /etc/network/interfaces this to remind you not to edit en05 and en06 in the GUI

This fragment should go between the existing auto lo section and adapater sections.

iface en05 inet manual
#do not edit it GUI

iface en06 inet manual
#do not edit in GUI

If you see any thunderbol sections delete them from the file before you save it.

*DO NOT DELETE the source /etc/network/interfaces.d/* this will always exist on the latest versions and should be the last or next to last line in /interfaces file

Rename Thunderbolt Connections

This is needed as proxmox doesn't recognize the thunderbolt interface name. There are various methods to do this. This method was selected after trial and error because:

  • the thunderboltX naming is not fixed to a port (it seems to be based on sequence you plug the cables in)
  • the MAC address of the interfaces changes with most cable insertion and removale events

  1. use udevadm monitor command to find your device IDs when you insert and remove each TB4 cable. Yes you can use other ways to do this, i recommend this one as it is great way to understand what udev does - the command proved more useful to me than the syslog or lspci command for troublehsooting thunderbolt issues and behavious. In my case my two pci paths are 0000:00:0d.2and 0000:00:0d.3 if you bought the same hardware this will be the same on all 3 units. Don't assume your PCI device paths will be the same as mine.

  2. create a link file using nano /etc/systemd/network/00-thunderbolt0.link and enter the following content:

[Match]
Path=pci-0000:00:0d.2
Driver=thunderbolt-net
[Link]
MACAddressPolicy=none
Name=en05
  1. create a second link file using nano /etc/systemd/network/00-thunderbolt1.link and enter the following content:
[Match]
Path=pci-0000:00:0d.3
Driver=thunderbolt-net
[Link]
MACAddressPolicy=none
Name=en06

Set Interfaces to UP on reboots and cable insertions

This section en sure that the interfaces will be brought up at boot or cable insertion with whatever settings are in /etc/network/interfaces - this shouldn't need to be done, it seems like a bug in the way thunderbolt networking is handled (i assume this is debian wide but haven't checked).

Huge thanks to @corvy for figuring out a script that should make this much much more reliable for most

  1. create a udev rule to detect for cable insertion using nano /etc/udev/rules.d/10-tb-en.rules with the following content:
ACTION=="move", SUBSYSTEM=="net", KERNEL=="en05", RUN+="/usr/local/bin/pve-en05.sh"
ACTION=="move", SUBSYSTEM=="net", KERNEL=="en06", RUN+="/usr/local/bin/pve-en06.sh"

  1. save the file

  2. create the first script referenced above using nano /usr/local/bin/pve-en05.sh and with the follwing content:

#!/bin/bash

LOGFILE="/tmp/udev-debug.log"
VERBOSE="" # Set this to "-v" for verbose logging
IF="en05"

echo "$(date): pve-$IF.sh triggered by udev" >> "$LOGFILE"

# If multiple interfaces go up at the same time, 
# retry 10 times and break the retry when successful
for i in {1..10}; do
    echo "$(date): Attempt $i to bring up $IF" >> "$LOGFILE"
    /usr/sbin/ifup $VERBOSE $IF >> "$LOGFILE" 2>&1 && {
        echo "$(date): Successfully brought up $IF on attempt $i" >> "$LOGFILE"
        break
    }
  
    echo "$(date): Attempt $i failed, retrying in 3 seconds..." >> "$LOGFILE"
    sleep 3
done

save the file and then

  1. create the second script referenced above using nano /usr/local/bin/pve-en06.sh and with the follwing content:
#!/bin/bash

LOGFILE="/tmp/udev-debug.log"
VERBOSE="" # Set this to "-v" for verbose logging
IF="en06"

echo "$(date): pve-$IF.sh triggered by udev" >> "$LOGFILE"

# If multiple interfaces go up at the same time, 
# retry 10 times and break the retry when successful
for i in {1..10}; do
    echo "$(date): Attempt $i to bring up $IF" >> "$LOGFILE"
    /usr/sbin/ifup $VERBOSE $IF >> "$LOGFILE" 2>&1 && {
        echo "$(date): Successfully brought up $IF on attempt $i" >> "$LOGFILE"
        break
    }
  
    echo "$(date): Attempt $i failed, retrying in 3 seconds..." >> "$LOGFILE"
    sleep 3
done

and save the file

  1. make both scripts executable with chmod +x /usr/local/bin/*.sh
  2. run update-initramfs -u -k all to propogate the new link files into initramfs
  3. Reboot (restarting networking, init 1 and init 3 are not good enough, so reboot)

Enabling IP Connectivity

proceed to the next gist

Slow Thunderbolt Performance? Too Many Retries? No traffic? Try this!

verify neighbors can see each other (connectivity troubleshooting)

##3 Install LLDP - this is great to see what nodes can see which.

  • install lldpctl with apt install lldpd on all 3 nodes
  • execute lldpctl you should info

make sure iommu is enabled (speed troubleshooting)

if you are having speed issues make sure the following is set on the kernel command line in /etc/default/grub file intel_iommu=on iommu=pt one set be sure to run update-grub and reboot

everyones grub command line is different this is mine because i also have i915 virtualization, if you get this wrong you can break your machine, if you are not doing that you don't need the i915 entries you see below

GRUB_CMDLINE_LINUX_DEFAULT="quiet intel_iommu=on iommu=pt" (note if you have more things in your cmd line DO NOT REMOVE them, just add the two intel ones, doesnt matter where.

Pinning the Thunderbolt Driver (speed and retries troubleshooting)

identify you P and E cores by running the following

cat /sys/devices/cpu_core/cpus && cat /sys/devices/cpu_atom/cpus

you should get two lines on an intel system with P and E cores. first line should be your P cores second line should be your E cores

for example on mine:

root@pve1:/etc/pve# cat /sys/devices/cpu_core/cpus && cat /sys/devices/cpu_atom/cpus
0-7
8-15

create a script to apply affinity settings everytime a thunderbolt interface comes up

  1. make a file at /etc/network/if-up.d/thunderbolt-affinity
  2. add the following to it - make sure to replace echo X-Y with whatever the report told you were your performance cores - e.g. echo 0-7
#!/bin/bash

# Check if the interface is either en05 or en06
if [ "$IFACE" = "en05" ] || [ "$IFACE" = "en06" ]; then
# Set Thunderbot affinity to Pcores
    grep thunderbolt /proc/interrupts | cut -d ":" -f1 | xargs -I {} sh -c 'echo X-Y | tee "/proc/irq/{}/smp_affinity_list"'
fi
  1. save the file - done

Extra Debugging for Thunderbolt

dynamic kernel tracing - adds more info to dmesg, doesn't overhwelm dmesg

I have only tried this on 6.8 kernels, so YMMV If you want more TB messages in dmesg to see why connection might be failing here is how to turn on dynamic tracing

For bootime you will need to add it to the kernel command line by adding thunderbolt.dyndbg=+p to your /etc/default/grub file, running update-grub and rebooting.

To expand the example above"

`GRUB_CMDLINE_LINUX_DEFAULT="quiet intel_iommu=on iommu=pt thunderbolt.dyndbg=+p"`

Don't forget to run update-grub after saving the change to the grub file.

For runtime debug you can run the following command (it will revert on next boot) so this cant be used to cpature what happens at boot time.

`echo -n 'module thunderbolt =p' > /sys/kernel/debug/dynamic_debug/control`

install tbtools

these tools can be used to inspect your thundebolt system, note they rely on rust to be installedm you must use the rustup script below and not intsall rust by package manager at this time (9/15/24)

apt install pkg-config libudev-dev git curl
curl https://sh.rustup.rs -sSf | sh
git clone https://github.com/intel/tbtools
restart you ssh session
cd tbtools
cargo install --path .
@Khayoann2

Khayoann2 commented Jun 4, 2026 •
edited
Loading

Copy link
Copy Markdown

Hi Randy- Did you fuse the guide on proxmox? Any notable issues? https://pve.proxmox.com/wiki/Ceph_Squid_to_Tentacle

I followed this runbook gen by AI and no issue so far (i did it today but smells good :))

Thank you @Randymartin1991 for the confirm :) Works like a charm

Prerequisites (blocking)

  • ceph -s → HEALTH_OK, all PGs active+clean
  • No rebalance / backfill in progress
  • From each node: ping -c2 10.0.0.81 / .82 / .83 OK
  • Backup: cp /etc/pve/ceph.conf /root/ceph.conf.pre-tentacle-$(date +%F) on one node
  • Maintenance window (~45–90 min), low I/O load (NVMe already warm → avoid heavy PBS backups during upgrade)

Global commands (once, from any node)

# After HEALTH_OK check
ceph osd set noout

At the end: ceph osd unset noout.

Phase 0 — Tentacle repo on all 3 nodes

On pve01, pve02, pve03 (SSH as root):

sed -i 's/ceph-squid/ceph-tentacle/' /etc/apt/sources.list.d/ceph.sources
grep URIs /etc/apt/sources.list.d/ceph.sources   # must show ceph-tentacle
apt update
apt-cache madison ceph | head -3                   # expected: 20.2.1-pve1

Do not mix Squid and Tentacle packages on the same node after apt upgrade.

Phase 1 — Package upgrade + service restarts (one node at a time)

Recommended order: pve01 → pve02 → pve03 (active mgr on pve03 last).

For each node:

1.1 Packages

apt update
apt full-upgrade -y
# Check before rebooting if the kernel was updated:
ceph -v   # should show 20.2.x after package upgrade + daemon restarts

1.2 Monitors (one per node hosting a mon)

systemctl restart ceph-mon.target
sleep 15
ceph -s    # HEALTH_OK or HEALTH_WARN (noout only)
ceph quorum_status --format json-pretty | head -20

Wait for 3/3 quorum before the next node.

Check progress (from any node):

ceph versions
ceph mon dump | grep min_mon_release   # expected after all mons: 20 (tentacle)

1.3 Managers (after all mons are on 20.2)

When all mons have been restarted at least once:

# On each node that runs a mgr:
systemctl restart ceph-mgr.target
ceph -s   # mgr: pve0X(active), standbys: ...

1.4 OSD (one node at a time — critical with 1 OSD per node)

systemctl restart ceph-osd.target
watch -n5 'ceph -s; ceph osd tree | grep -E "down|up"'

Wait for HEALTH_OK or HEALTH_WARN with only noout before the next node.

Verify each OSD version before moving on:

ceph tell osd.0 version   # on pve01
ceph tell osd.1 version   # on pve02
ceph tell osd.2 version   # on pve03
# each must report release "tentacle", version "20.2.1"

Do not run ceph osd require-osd-release tentacle while any OSD is still on Squid.

During upgrade — expected states

Observation OK?
HEALTH_WARN + noout flag(s) set Yes — expected while noout is set
96 active+clean + 1–2 active+clean+scrubbing+deep Yes — deep scrub after OSD restart; wait or continue if no degraded PGs
ceph versions shows Squid on some osd, Tentacle on others Yes — mid-rollout; finish remaining OSD restarts
PG degraded / recovering stuck No — wait; do not proceed to next node

Phase 2 — CephFS ISOs-Templates (MDS)

max_mds is already 1 → no ceph fs set … max_mds 1 needed.

On nodes without the active MDS (standby only), stop MDS:

systemctl stop ceph-mds.target    # only if this node is not hosting active rank 0

Verify:

ceph status   # 1 active MDS for ISOs-Templates
ceph fs status ISOs-Templates

On the node running the active MDS (rank 0):

systemctl restart ceph-mds.target

Then on the other nodes:

systemctl start ceph-mds.target
ceph fs get ISOs-Templates | grep -E 'max_mds|up|in'
ceph versions   # mds must all be Tentacle 20.2.1

Phase 3 — Finalize Tentacle

When ceph versions shows no Squid left:

ceph versions
ceph mon dump | grep min_mon_release    # expected: 20 (tentacle)
ceph osd require-osd-release tentacle
ceph osd unset noout
ceph -s    # expected: HEALTH_OK

Post-upgrade checks

ceph -v
ceph versions
ceph -s
ceph osd perf
ceph osd tree
ceph fs status ISOs-Templates
pvesm status
# Thunderbolt
ping -c2 10.0.0.82   # from pve01
ping -c2 10.0.0.83
# OSD addresses (public + cluster split)
ceph osd dump | grep "^osd"
# NVMe
nvme smart-log /dev/nvme0n1 | grep -iE 'Warning Temperature|media_errors'

Functional test: start a VM on vm-disks, access ISOs-Templates from the PVE UI.

Optional performance baseline (quiet window):

rados bench -p vm-disks 30 write --no-cleanup
rados bench -p vm-disks 30 seq
rados -p vm-disks cleanup

Per-node validation:

# On each pve0X
ceph -v
dpkg -l ceph | tail -1
systemctl is-active ceph-mon@pve0X ceph-mgr@pve0X ceph-osd@N

Rollback

No official downgrade from Tentacle back to Squid after ceph osd require-osd-release tentacle.
Before that command: you can restore ceph.sources (squid) + 19.2 packages only if all daemons have not been migrated yet (rare).

Quick troubleshooting

Symptom Action
PG peering / recovering for a long time Keep noout, watch ceph -s; do not move to next node
Lost mon quorum systemctl status ceph-mon@*.service, journalctl -u ceph-mon@pve01
MDS damned / damaged Do not change max_mds; check ceph fs status / MDS wiki
Lost TB route ip route | grep 10.0.0; fix FRR / TB interfaces before continuing
Mixed Squid/Tentacle OSDs at finalize Restart ceph-osd.target on remaining node(s); re-check ceph tell osd.N version

@Randymartin1991

Randymartin1991 commented Jun 4, 2026 via email

Copy link
Copy Markdown

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment