/auto-xorg

Automatically set the proper video output given a video device (VGA) is unavailable due to hardware-passthrough (VFIO) or any other reason, in the X.Org display environment for a Linux machine.

Primary LanguageShellGNU General Public License v3.0GPL-3.0

Auto X.Org

v1.1.1

Automatically set the proper video output given a video device (VGA) is unavailable due to hardware-passthrough (VFIO) or any other reason, in the X.Org display environment for a Linux machine.

Download

Table of Contents

Contents

1. Why?

X.Org will specify a VGA device to be the primary video output. When that VGA device is Passed-through or restricted to Virtual Machines (VMs) only (like in a VFIO setup), the VGA device cannot be used by the Host machine (Linux). Unfortunately, X.Org will not search for the next valid VGA device. This is where auto-X.Org steps in...

This script will automatically set the proper video output everytime, as it runs at Host startup. This flexibility is very useful for a new or changing VFIO setup.

2. Related Projects

Project Codeberg GitHub
Deploy VFIO link link
Auto X.Org link link
Generate Evdev link link
Guest Machine Guide link link
Libvirt Hooks link link
Power State Virtual Machine Manager link link

3. Documentation

4. Host Requirements

4.1. Operating System

Linux.

4.2. Software

  • systemd for system services.
  • X.Org or X11 as the video display environment.
  • Wayland is not supported.
    • Wayland causes problems for NVIDIA devices (as of 2024).

4.3. Hardware

Two (2) or more video devices. This script is not necessary for machines with one video device, as X.Org will find it.

5. Download

  • Download the Latest Release: Codeberg, GitHub

  • Download the .zip file:

    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.

  • Clone the repository:

    1. Open a Command Line Interface (CLI).
      • Open a console emulator (for Debian systems: Konsole).
      • Open a 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.
    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. Verify Installer is Executable

  1. Open the CLI (see Download).

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

  3. 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.2. installer.bash or auto-xorg

  • From within the project folder, execute: sudo bash installer.bash
  • Or after installation, from any folder execute: sudo bash 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 manager 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 brand (past or future).

6.3. Examples

  • Set options to find first valid AMD/ATI VGA device, then install:
sudo bash auto-xorg.bash -f -a
  • Find last valid NVIDIA VGA device, then restart the display manager immediately:
sudo bash auto-xorg -l -n -r

6.4. 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 VGA device(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 list of VGA devices:
lspci -m | grep --extended-regexp --ignore-case 'vga|graphics'
  1. Saves valid and available VGA device:
  lspci -ks 04:00.0 | grep --extended-regexp --ignore-case 'driver|VGA'

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

- Invalid example:
```
  lspci -ks 04:00.0 | grep --extended-regexp --ignore-case 'driver|VGA'

  01:00.0 VGA compatible controller: ...
  Kernel driver in use: vfio-pci
```
  1. 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

Did you encounter a bug? Do you need help? Please visit the Issues page (Codeberg, GitHub).

10. References

1.

PCI passthrough via OVMF. ArchWiki. Accessed June 14, 2024. https://wiki.archlinux.org/title/PCI_passthrough_via_OVMF.

2.

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.

3.

VFIO Discussion and Support. Reddit. Accessed June 14, 2024. https://www.reddit.com/r/VFIO/.

4.

XML Design Format. GitHub - libvirt/libvirt. Accessed June 18, 2024. https://github.com/libvirt/libvirt/blob/master/docs/formatdomain.rst.