/ 
Rex-GPU-0.002
/ Rex::GPU::NVIDIA::Setup::Debian

NAME

Rex::GPU::NVIDIA::Setup::Debian - NVIDIA driver setup for Debian (experimental)

VERSION

version 0.002

DESCRIPTION

Experimental, like Rex::GPU::NVIDIA::Setup. The NVIDIA driver install for Debian (and every is_debian host that is not Ubuntu): nvidia-driver from Debian non-free, or where that cannot drive the GPUs (Blackwell) the open-module set from NVIDIA's CUDA repository ("sources"), on the apt layer Rex::GPU::NVIDIA::Setup::Apt.

sources

In this order:

  • debian-nonfree -- nvidia-driver + nvidia-smi + libcuda1 from Debian non-free, proprietary kernel module, verified by nvidia-driver and libcuda1. libcuda1 is named because nvidia-driver pulls it only through recommends (libnvidia-encode1 -> libnvcuvid1), so a host with APT::Install-Recommends "false" would get no CUDA library -- and without it "already_installed" in Rex::GPU::NVIDIA::Setup never counts the driver as installed. Its branch comes from "nonfree_branch"; on a release that table does not know it is unknown, which fits only a GPU without constraints.

  • nvidia-cuda-repo -- NVIDIA's CUDA apt repository for debian12 or debian13 (x86_64 for amd64, sbsa for arm64, key cuda_repo): the compute-only open-module set nvidia-driver-cuda + nvidia-kernel-open-dkms, both verified, the newest branch the repository carries, at least 590. Unavailable on any other release or architecture.

So a Blackwell GPU (open module, 570 or newer: no Debian-packaged driver fits) gets the CUDA repository on Debian 12/13 and dies before the host is changed anywhere else; every other GPU gets non-free.

A host with NVSwitches ("nvswitches" in Rex::GPU::NVIDIA::Setup) needs NVIDIA Fabric Manager, which Debian does not package: non-free is rejected for it, and the CUDA repository installs nvidia-fabricmanager at the version of the installed nvidia-kernel-open-dkms. On Debian 11 such a host dies before it is changed.

An HGX B200/B300 ("nvlink_fabric_needed" in Rex::GPU::NVIDIA::Setup) is such a host too, and its NVLink fabric packages ("nvlink_fabric_packages" in Rex::GPU::NVIDIA::Setup::Apt: nvlsm from the same CUDA repository, infiniband-diags and libibumad3 from Debian) are installed after Fabric Manager; see "install_nvlink_fabric" in Rex::GPU::NVIDIA::Setup.

fabric_manager_package

The base class's, except for driver branch 570 or 575 (only on an already-installed driver, "retrofit_fabric_manager" in Rex::GPU::NVIDIA::Setup): there NVIDIA's CUDA repository names it nvidia-fabricmanager-NNN.

A reason unless the chosen driver source is NVIDIA's CUDA repository (nvlsm is in no Debian archive).

nonfree_branch

my $branch = $self->nonfree_branch($major);   # 12 => 535

The driver branch of Debian's own nvidia-driver in a release: 11 (470), 12 (535), 13 (550); undef for any other. A fixed table (maintainer decision, epic karr #25): looking it up with apt-cache would need non-free enabled first, a host change before the plan can fail. Override it for a release this table does not know.

plan

The base plan, plus $plan->{cuda_repo}: the chosen source's CUDA repository, or undef on the non-free path.

prepare_host

Enables contrib non-free non-free-firmware in Debian's own archive entries ("enable_nonfree") when the chosen source is non-free -- not on the CUDA-repo path, whose packages resolve from NVIDIA's repo plus Debian main, and must not mix with Debian's nvidia packages -- then the apt layer's step.

prepare_source

On the CUDA-repo path registers NVIDIA's repository ("add_nvidia_cuda_apt_repo") before the apt layer's apt-get update.

add_nvidia_cuda_apt_repo

$self->add_nvidia_cuda_apt_repo($repo);

Installs the cuda-keyring package of $repo (signing key plus the sources.list.d entry) with apt-get, and dies unless it is ii afterwards -- without it the driver install could only fail with a misleading "unable to locate package".

enable_nonfree

Adds whichever of contrib, non-free, non-free-firmware is missing to every recognised Debian archive entry, in /etc/apt/sources.list first and then in the deb822 /etc/apt/sources.list.d/*.sources (both may be present). Third-party entries and unknown mirrors are left alone; a file with nothing to add is not rewritten. Warns if no Debian archive entry is recognised.

An entry is a Debian archive entry if it is an enabled deb entry (not deb-src) whose components include main, and

  • it has a signed-by option (Signed-By: in deb822) that names only keyrings "is_debian_archive_keyring" accepts -- whatever its URI: a repository signed with Debian's archive key is Debian's archive or a mirror of it (karr #41). Any other signed-by (a foreign keyring, an inline key) makes it a third-party entry, even on a Debian URI;

  • or it has no signed-by, and "is_debian_archive_uri" accepts every one of its URIs.

is_debian_archive_uri

return 1 if $self->is_debian_archive_uri($uri);

True if $uri is one of Debian's archives: a host debian.org or *.debian.org (deb, security, ftp.de, ...; any http, https, ftp, optionally with an apt transport prefix such as tor+), Hetzner's Debian mirror (mirror.hetzner.com or mirror.hetzner.de under /debian/), or the mirror+file:/etc/apt/mirrors/debian.list / debian-security.list indirection of Debian's cloud images. Any other URI is not.

"enable_nonfree" asks it only for entries without signed-by. A mirror of your own -- a company mirror, apt-cacher-ng, a national ftp.* host outside debian.org -- whose entries carry no signed-by=/usr/share/keyrings/debian-archive-keyring.gpg is not recognised, so non-free is not enabled and nvidia-driver has no installation candidate. Recognise it in a subclass (see "WRITING YOUR OWN SETUP" in Rex::GPU::NVIDIA::Setup, and eg/custom-setup/lib/My/GPU/DebianMirror.pm in the distribution):

package My::GPU::DebianMirror;
use Moo;
extends 'Rex::GPU::NVIDIA::Setup::Debian';

sub is_debian_archive_uri {
  my ( $self, $uri ) = @_;
  return 1 if $uri =~ m{^http://apt-cache\.corp\.example:3142/debian/?$};
  return $self->SUPER::is_debian_archive_uri($uri);
}

# set gpu_nvidia_setup => 'My::GPU::DebianMirror';

Match only URIs that serve Debian's own archive: every entry with main that it accepts gets contrib non-free non-free-firmware added.

is_debian_archive_keyring

return 1 if $self->is_debian_archive_keyring($path);

True if the keyring file $path holds Debian's archive keys: by default a debian-archive-*.gpg, .pgp or .asc file directly under /usr/share/keyrings (what the debian-archive-keyring package ships). Override it for a mirror that is re-signed with a key of your own, whose entries name that keyring in signed-by -- for such an entry "is_debian_archive_uri" is not asked.

SEE ALSO

Rex::GPU::NVIDIA::Setup, "install_driver" in Rex::GPU::NVIDIA

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/rex-gpu/issues.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <getty@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.