Auto X.Org

v1.1.3

Automatically set the primary video output at boot-time given a video device is unavailable due to hardware pass-through (VFIO), or any other reason, in the X11 (X.Org) display server for a Linux machine.

💾 Download

View this repository on Codeberg, GitHub.

Table of Contents

• ❓ 1. Why?

• 🛠️ 2. Related Projects

• 📝 3. Documentation

• ✅ 4. Host Requirements

  • 4.1. Operating System
  • 4.2. Software
  • 4.3. Hardware

• 💾 5. Download

• ❓ 6. Usage

  • 6.1. The Command Interface (CLI) or Terminal
  • 6.2. Verify Installer is Executable
  • 6.3. Installer/Executable
  • 6.4. Examples
  • 6.5. Troubleshooting

• 💪 7. How Auto X.Org Works

• ❗ 8. Filenames and Pathnames Modified by Auto X.Org

  • 8.1. System Files
  • 8.2. Binaries and Files

• ☎️ 9. Contact

• 🌐 10. References

Contents

❓ 1. Why?

By default, the X11 (X.Org) display server can detect one (1) or more GPUs, and use any or all for video output. However, should the default or first-detected (primary) GPU be unavailable or invalid, video output may break.

Reasons for breakage include:

• Hardware/PCI pass-through or VFIO. This can affect all GPUs which share the same driver (of the same family or manufacturer).
• Reservation by a running Virtual Machine (VM). This can affect all devices which share the same IOMMU group. To mitigate this, a user may patch the Host kernel with ACS override ^[1], however this is a possible security risk and is not recommended for most users.

Given this issue - sometimes, consecutive GPUs may only output to a Command Line Interface (CLI) or terminal.

What can Auto X.Org do? This script may automatically set a valid GPU at Host boot-time. The user may manually set a preferred GPU, as matched by the GPU manufacturer, should any one GPU be valid. This flexibility is very useful for a new or changing VFIO setup.

⚠️ Warning: To use Auto X.Org at Host run-time, one must safely exit the desktop (save and exit all applications), as the display manager (the entire desktop) will be restarted.

⚠️ Note: to hot-swap (hot-plug) or bind/unbind of GPUs, combine Auto X.Org with any of the following methods:

• Optimus^[2]

🛠️ 2. Related Projects

To view other relevant projects, visit Codeberg or GitHub.

📝 3. Documentation

• What is IOMMU? ^[3]
• What is VFIO? ^[4]
• VFIO Discussion and Support ^[5]
• Hardware/PCI Pass-through Guide ^[6]
• Virtual Machine XML Format Guide ^[7]

✅ 4. Host Requirements

4.1. Operating System

Linux.

4.2. Software

• systemd for system services.

• xorg as the display server.

• Other display servers are not supported:

  • wayland: The author has experienced problems with Wayland and an NVIDIA GPU, on Debian Linux (as of writing in 2024).

4.3. Hardware

• A host with two (2) or more GPUs. This includes onboard graphics or an integrated GPU (iGPU) and one (1) or more dedicated GPU (dGPU).

• A host with one (1) GPU. Auto X.Org is not recommended for this setup. By default, X.Org will use this GPU every time.

💾 5. Download

• Download the Latest Release: Codeberg, GitHub

• Download the .zip file:

  • From the webpage

    1. Viewing from the top of the repository's (current) webpage, click the drop-down icon:

       • ··· on Codeberg.
       • <> Code on GitHub.

    2. Click Download ZIP and save.

    3. Open the .zip file, then extract its contents.

  • From the CLI:

    1. Open the CLI.
    2. Download the Latest:

    GH_USER=portellam; \
    GH_REPO=auto-xorg; \
    GH_BRANCH=master; \
    wget \
      https://github.com/${GH_USER}/${GH_REPO}/archive/refs/heads/${GH_BRANCH}.zip \
      -O "${GH_REPO}-${GH_BRANCH}.zip" \
    && unzip ./"${GH_REPO}-${GH_BRANCH}.zip" \
    && rm ./"${GH_REPO}-${GH_BRANCH}.zip"

• Clone the repository:

  1. Open the CLI.

  2. Change your directory to your home folder or anywhere safe:

     • cd ~

  3. Clone the repository:

     • git clone https://www.codeberg.org/portellam/auto-xorg
     • git clone https://www.github.com/portellam/auto-xorg

❓ 6. Usage

6.1. The Command Interface (CLI) or Terminal

To open a CLI or Terminal:

• Open a console emulator (for Debian systems: Konsole).

• Linux only: Open an existing console: press CTRL + ALT + F2, F3, F4, F5, or F6.

  • To return to the desktop, press CTRL + ALT + F7.
  • F1 is reserved for debug output of the Linux kernel.
  • F7 is reserved for video output of the desktop environment.
  • F8 and above are unused.

6.2. Verify Installer is Executable

1. Go to the directory where the cloned/extracted repository folder is: cd name_of_parent_folder/auto-xorg/

2. Make the installer script file executable: chmod +x installer.bash

   • Do not make any other script files executable. The installer will perform this action.
   • Do not make any non-script file executable. This is not necessary and potentially dangerous.

6.3. Installer/Executable

• From within the project folder, execute: sudo bash installer.bash

• Or after installation, from any folder execute: sudo auto-xorg

  • The CLI's shell (bash) should recognize that the script file is located in /usr/local/bin.

    -h, --help              Print this help and exit.
  
  Update X.Org:
    -r, --restart-display   Restart the display server immediately.
  
  Set device order:
    -f, --first             Find the first valid VGA device.
    -l, --last              Find the last valid VGA device.
  
  Prefer a vendor:
    -a, --amd               AMD or ATI
    -i, --intel             Intel
    -n, --nvidia            NVIDIA
    -o, --other             Any other manufacturer (past or future).
  

6.4. Examples

• Set options to find the first valid AMD/ATI GPU, then install:

  sudo bash installer.bash \
    --first \
    --amd

• Find the last valid NVIDIA GPU, then restart the display server immediately:

  sudo auto-xorg \
    --last \
    -nvidia \
    --restart-display

6.5. Troubleshooting

If the auto-xorg service fails, to diagnose review the log, execute:

sudo journalctl -u auto-xorg

Failure may be the result of absent GPU(s), or an exception. Review the log to debug.

💪 7. How Auto X.Org Works

1. Runs once at boot (as a service) or run at user discretion.

2. Parses a list of GPUs:

lspci -m \
  | grep \
    --extended-regexp \
    --ignore-case \
    'vga|graphics'

3. Saves valid and available GPU:

Valid example, a driver which is not blacklisted:

  lspci \
      -k \
      -s 04:00.0 \
    | grep \
      --extended-regexp \
      --ignore-case \
      'driver|VGA'

  04:00.0 VGA compatible controller: ...
  Kernel driver in use: nvidia

Invalid example, a driver which is blacklisted:

  lspci \
      -k \
      -s 01:00.0 \
    | grep \
      --extended-regexp \
      --ignore-case \
      'driver|VGA'

  01:00.0 VGA compatible controller: ...
  Kernel driver in use: vfio-pci

4. Appends to X.Org file: /etc/X11/xorg.conf.d/10-auto-xorg.conf

❗ 8. Filenames and Pathnames Modified by Auto X.Org

8.1. System Files

• /etc/X11/xorg.conf.d/

8.2. Binaries and Files

• /usr/local/bin/
• /etc/systemd/system/

☎️ 9. Contact

Do you need help? Please visit the Issues page.

🌐 10. References

1.

  Bypassing the IOMMU groups (ACS override patch). ArchWiki. Accessed June 4, 2025.

    ^{https://wiki.archlinux.org/title/PCI_passthrough_via_OVMF#Bypassing_the_IOMMU_groups_%28ACS_override_patch%29.}

2.

  Misairu-G/[GUIDE] Optimus laptop dGPU passthrough.md. GitHub. Accessed June 3, 2025.

    ^{https://gist.github.com/Misairu-G/616f7b2756c488148b7309addc940b28.}

  You can now passthrough your dGPU as you wish with an Optimus laptop. Reddit. Accessed June 3, 2025.

    ^{https://old.reddit.com/r/VFIO/comments/7d27sz/you_can_now_passthrough_your_dgpu_as_you_wish/.}

3.

  Input-output memory management unit. Wikipedia. Accessed June 4, 2025.

    ^{https://en.wikipedia.org/wiki/Input%E2%80%93output_memory_management_unit.}

4.

  VFIO - ‘Virtual Function I/O’ - The Linux Kernel Documentation. The linux kernel. Accessed June 14, 2024.

    ^{https://www.kernel.org/doc/html/latest/driver-api/vfio.html.}

5.

  VFIO Discussion and Support. Reddit. Accessed June 14, 2024.

    ^{https://old.reddit.com/r/VFIO/.}

6.

  PCI passthrough via OVMF. ArchWiki. Accessed June 14, 2024.

    ^{https://wiki.archlinux.org/title/PCI_passthrough_via_OVMF.}

7.

  XML Design Format. GitHub - libvirt/libvirt. Accessed June 18, 2024.

    ^{https://github.com/libvirt/libvirt/blob/master/docs/formatdomain.rst.}

Click here to return to the top of this document.