kmscon for Debian
-----------------

The kmscon virtual terminal is not enabled on any ttyX by default upon package
installation. You will need to enable it manually.


Enabling kmscon
---------------

  # systemctl enable --force kmsconvt@.service

This replaces the symlink

  /etc/systemd/system/autovt@.service -> /usr/lib/systemd/system/getty@.service

with

  /etc/systemd/system/autovt@.service -> /usr/lib/systemd/system/kmsconvt@.service

so that all newly-activated TTYs are handled by kmscon instead of agetty. It
additionally creates
/etc/systemd/system/getty.target.wants/kmsconvt@tty1.service, which starts
kmscon on tty1 during boot.

The --force option is required: the systemd package owns the autovt@.service
alias on a Debian system, and "systemctl enable" refuses to overwrite an
existing alias without it.


Display managers and tty1
-------------------------

Display managers such as sddm and gdm3 start on tty1 by default. Older versions
only declare

  Conflicts=getty@tty1.service

in their service file, so systemd does not know that kmsconvt@tty1.service has
to be stopped as well. The display manager and kmscon then end up fighting over
the same DRM device, which shows up as

  ERROR: drm_shared: Cannot set drm master for /dev/dri/card0

in the journal and can leave the graphical session or the VT switching broken.
See https://github.com/kmscon/kmscon/issues/294 .

The display manager also has to list kmsconvt@tty1.service in its Conflicts=,
which is the case since:

  sddm  0.21.0+git20260801.f62b7ba-1
  gdm3  51

If your display manager is older than that, or is one that does not carry the
corresponding fix yet, keep tty1 free for it:

  # systemctl mask kmsconvt@tty1.service

kmscon then serves tty2 and above, and the display manager keeps tty1.


Temporarily disabling kmscon while keeping the package installed
---------------------------------------------------------------

To hand the virtual consoles back to agetty without removing the package:

  # systemctl enable --force getty@.service

To hand them back to kmscon again:

  # systemctl enable --force kmsconvt@.service

Both take effect for TTYs activated afterwards; already-running terminals are
left alone. Use "systemctl stop kmsconvt@ttyN.service" to also terminate a
kmscon instance that is currently running on ttyN.

A single tty can be excluded at any time with

  # systemctl mask kmsconvt@ttyN.service

and re-enabled with "systemctl unmask kmsconvt@ttyN.service".


Disabling kmscon permanently
----------------------------

  # systemctl disable kmsconvt@.service
  # systemctl enable --force getty@.service

The second command is important. "systemctl disable kmsconvt@.service" only
removes the autovt@.service alias, it does not restore the agetty one, and
systemd (>= 260) no longer recreates it on upgrades. Without it the system
would be left with no autovt@.service at all, and no virtual console could be
activated any more.

Removing or purging the kmscon package restores the agetty alias automatically,
so the above is only needed when keeping the package installed.


 -- Boyuan Yang <byang@debian.org>  Thu, 06 Aug 2026 11:45:00 -0400
