kvm-helper.sh

Interactive Linux helper script for detecting and configuring local GPU outputs for servers, Proxmox hosts, and KVM switch setups.

The script helps you identify which HDMI, DisplayPort, DVI, VGA, or internal display connector is detected by the Linux kernel. It can optionally set a suitable video= kernel parameter in GRUB, for example:

video=HDMI-A-1:1920x1080@60

Typical use cases:

• A Proxmox host shows no image on a KVM switch
• The KVM switch does not handle the current resolution correctly
• The server has an Intel iGPU plus an NVIDIA or AMD GPU
• The local console should use the internal GPU
• The external GPU should remain available for transcoding, CUDA, containers, or VM passthrough
• The KVM switch exposes incomplete or limited EDID data

Features

kvm-helper.sh can detect:

• DRM/KMS graphics devices under /sys/class/drm/
• Connected outputs such as HDMI-A-1, DP-1, DP-4, eDP-1
• Kernel drivers such as i915, amdgpu, radeon, nvidia, nouveau
• The active framebuffer through /proc/fb
• Reported monitor/KVM modes through /sys/class/drm/<connector>/modes
• NVIDIA display state through nvidia-smi, if available
• The bootloader type, with basic handling for GRUB and systemd-boot

The script can optionally:

• Set a matching video= parameter in /etc/default/grub
• Replace existing video= parameters while keeping other kernel parameters
• Create backups before modifying configuration files
• Run update-grub
• Run update-initramfs -u
• Set nvidia-drm modeset=1 fbdev=1, if explicitly requested
• Run in dry-run mode without changing anything

Supported systems

Best suited for:

• Debian
• Ubuntu
• Proxmox VE
• Other GRUB-based systems using /etc/default/grub

Partially supported:

• Fedora
• RHEL
• CentOS Stream
• openSUSE

On these systems, grub2-mkconfig may be available, but the correct GRUB output path depends on the distribution and boot mode.

Not automatically supported:

• systemd-boot
• rEFInd
• EFI-stub without GRUB
• Appliance-style systems with custom boot handling

Supported GPU types

The script works through Linux DRM/KMS and is not tied to one GPU vendor.

Common drivers:

GPU type	Kernel driver
Intel iGPU	i915, newer systems may use xe
AMD GPU/iGPU	amdgpu, older cards may use radeon
NVIDIA proprietary driver	nvidia, nvidia_drm
NVIDIA open-source driver	nouveau

The script configures the local Linux console output. It does not configure a desktop environment, X11, Wayland, GPU passthrough, or hardware transcoding.

Installation

Create the script:

nano kvm-helper.sh

Make it executable:

chmod +x kvm-helper.sh

Usage

First run it safely in dry-run mode:

sudo ./kvm-helper.sh --dry-run

If the detected output looks correct, run it interactively:

sudo ./kvm-helper.sh

Show help:

./kvm-helper.sh --help

Typical workflow

The script first displays an overview of detected GPUs, drivers, framebuffers, and DRM connectors.

Example:

Framebuffer:
0 i915drmfb

DRM connectors:
card0-DP-1: disconnected    driver=i915
card0-HDMI-A-1: connected   driver=i915
card1-DP-4: disconnected    driver=nvidia

In this example, the local console is running through the Intel iGPU, and the KVM switch is connected to:

card0-HDMI-A-1

The matching kernel connector name is:

HDMI-A-1

The script will usually suggest a safe KVM-friendly mode such as:

1920x1080@60

This becomes the kernel parameter:

video=HDMI-A-1:1920x1080@60

Example GRUB change

Before:

GRUB_CMDLINE_LINUX_DEFAULT="libata.noacpi=1"

After:

GRUB_CMDLINE_LINUX_DEFAULT="libata.noacpi=1 video=HDMI-A-1:1920x1080@60"

Existing kernel parameters are preserved.

After changing GRUB, the script can run the following commands on Debian, Ubuntu, or Proxmox systems:

update-grub
update-initramfs -u

A reboot is required afterwards.

Verify after reboot

Check the active kernel command line:

cat /proc/cmdline

You should see the configured parameter, for example:

video=HDMI-A-1:1920x1080@60

Check the framebuffer:

cat /proc/fb
cat /sys/class/graphics/fb0/name 2>/dev/null

Example for an Intel iGPU:

0 i915drmfb
i915drmfb

Check DRM connector status:

for d in /sys/class/drm/card*-*; do
  [ -f "$d/status" ] && echo "$(basename "$d"): $(cat "$d/status")"
done

Example:

card0-DP-1: disconnected
card0-HDMI-A-1: connected
card1-DP-1: disconnected

Recommendation for Proxmox servers

For Proxmox hosts, the most reliable setup is usually:

• Connect the KVM switch to the internal Intel or AMD iGPU
• Set the BIOS/UEFI primary display to iGPU, IGFX, or Internal Graphics
• Do not use the external NVIDIA or AMD GPU for the local console unless needed
• Keep the external GPU available for transcoding, CUDA, containers, or VM passthrough

NVIDIA cards with the proprietary driver can be unnecessarily awkward for a plain local text console. An Intel or AMD iGPU is usually the calmer option for Proxmox console output.

BIOS/UEFI hints

Depending on the motherboard, the relevant options may be named differently:

Initial Display Output
Primary Display
Init Display First
Internal Graphics
iGPU Multi-Monitor
IGFX
PEG
PCIe

For local console output through the internal GPU:

Primary Display: IGFX / Internal Graphics
Internal Graphics: Enabled

For local console output through an external GPU:

Primary Display: PEG / PCIe

If the internal GPU and an external GPU should both remain active, this option may be required on some boards:

iGPU Multi-Monitor: Enabled

KVM switch notes

Many KVM switches do not pass EDID data cleanly. This can cause Linux to see only a limited set of modes.

Check reported modes:

cat /sys/class/drm/card0-HDMI-A-1/modes

Example of limited KVM EDID:

1920x1080
1280x720
1024x768
800x600
640x480

If your monitor supports higher resolutions or refresh rates but Linux only sees 1080p through the KVM switch, the limiting factor is probably the KVM switch, cable, adapter, or monitor input.

For a plain server console, 1920x1080@60 is usually more than enough.

NVIDIA notes

The script may ask whether it should create or modify:

/etc/modprobe.d/nvidia-drm.conf

With this content:

options nvidia-drm modeset=1 fbdev=1

This may help if the local console should run through an NVIDIA GPU.

If the console runs through Intel or AMD and NVIDIA is only used for transcoding, CUDA, containers, or passthrough, this option is usually not needed.

Check NVIDIA display status:

nvidia-smi --query-gpu=name,pci.bus_id,display_active,display_mode --format=csv

Example:

name, pci.bus_id, display_active, display_mode
Quadro P620, 00000000:01:00.0, Disabled, Enabled

display_active: Disabled means the NVIDIA card is not currently used as an active display output.

That is fine if the local console is intentionally running through another GPU.

AMD notes

AMD GPUs using amdgpu are usually straightforward for local console output.

Example detection:

card1-DP-1: connected    driver=amdgpu

The script may then set a parameter such as:

video=DP-1:1920x1080@60

AMD usually does not require a special option comparable to NVIDIA nvidia-drm fbdev=1.

If multiple GPUs expose similar connector names, such as multiple DP-1 outputs, set the desired primary GPU in BIOS/UEFI as well.

Rollback

The script creates timestamped backups before modifying configuration files.

Example:

/etc/default/grub.bak-20260627-130500
/etc/modprobe.d/nvidia-drm.conf.bak-20260627-130500

Rollback GRUB:

cp /etc/default/grub.bak-YYYYMMDD-HHMMSS /etc/default/grub
update-grub
update-initramfs -u
reboot

Rollback NVIDIA DRM configuration:

cp /etc/modprobe.d/nvidia-drm.conf.bak-YYYYMMDD-HHMMSS /etc/modprobe.d/nvidia-drm.conf
update-initramfs -u
reboot

Remove the NVIDIA DRM configuration completely:

rm /etc/modprobe.d/nvidia-drm.conf
update-initramfs -u
reboot

Manual diagnostic commands

Show all GPUs:

lspci -nnk | grep -A4 -Ei "vga|3d|display"

Show DRM connector status:

for d in /sys/class/drm/card*-*; do
  [ -f "$d/status" ] && echo "$(basename "$d"): $(cat "$d/status")"
done

Show active framebuffer:

cat /proc/fb
cat /sys/class/graphics/fb0/name 2>/dev/null

Show available modes for a connector:

cat /sys/class/drm/card0-HDMI-A-1/modes

Decode EDID:

apt install edid-decode
edid-decode /sys/class/drm/card0-HDMI-A-1/edid

Check kernel parameters:

cat /proc/cmdline

Known limitations

The kernel parameter:

video=HDMI-A-1:1920x1080@60

is connector-based, not strictly PCI-device-specific.

On systems with multiple GPUs exposing identical connector names, such as two cards that both provide DP-1, this can theoretically be ambiguous. In such cases, also set the intended primary GPU in BIOS/UEFI.

The script is not intended to automatically configure complex multi-GPU workstation setups, desktop environments, Wayland, X11, or GPU passthrough.

Safety notes

Before applying changes:

sudo ./kvm-helper.sh --dry-run

After applying changes, keep remote SSH access available until the system has rebooted and the local console has been verified.

Do not blindly enable NVIDIA framebuffer options if the console is meant to run through Intel or AMD.

License

MIT License