ai/guides/manus-ai/managing-kanshi-with-systemd-user-service.md

Managing Kanshi with Systemd User Service

This guide explains how to configure kanshi as a systemd user service, ensuring it starts automatically with your niri Wayland session and runs reliably in the background. Using a systemd user service is generally preferred over simply running kanshi & in a startup script, as it provides better process management, logging, and automatic restarts if kanshi crashes.

Prerequisites

• Kanshi Installed: Ensure kanshi is installed on your system. If not, install it using your distribution's package manager (e.g., sudo apt install kanshi for Debian/Ubuntu, sudo pacman -S kanshi for Arch Linux).
• Kanshi Configuration: You should have your kanshi configuration file set up at ~/.config/kanshi/config as provided in the previous interaction.
• Systemd User Session: Your niri session should be managed by systemd user services. This is typically the default for modern Linux distributions.

Step 1: Create the Systemd User Service File

Create a new file named kanshi.service in your ~/.config/systemd/user/ directory. If the user directory doesn't exist, create it first:

mkdir -p ~/.config/systemd/user/

Then, place the following content into ~/.config/systemd/user/kanshi.service:

[Unit]
Description=Dynamic output configuration for Wayland compositors
Documentation=man:kanshi(1)
PartOf=graphical-session.target

[Service]
Type=simple
ExecStart=/usr/bin/kanshi
Restart=always

[Install]
WantedBy=graphical-session.target

Explanation of the Service File

• [Unit] Section:

  • Description: A human-readable description of the service.
  • Documentation: Points to the kanshi man page for further information.
  • PartOf=graphical-session.target: This directive ensures that kanshi is considered part of your graphical session. If your graphical session stops, kanshi will also stop. For niri, graphical-session.target is a suitable target to bind to, as niri is a Wayland compositor that typically runs within a graphical session [1].

• [Service] Section:

  • Type=simple: Indicates that the ExecStart command is the main process of the service.
  • ExecStart=/usr/bin/kanshi: Specifies the command to execute when the service starts. This should be the full path to your kanshi executable.
  • Restart=always: Configures systemd to automatically restart kanshi if it crashes or exits unexpectedly.

• [Install] Section:

  • WantedBy=graphical-session.target: This makes kanshi.service a dependency of graphical-session.target. When you enable the service, a symlink will be created, ensuring kanshi starts when your graphical session starts.

Step 2: Reload Systemd Daemon

After creating or modifying a systemd unit file, you need to tell systemd to reload its configuration:

systemctl --user daemon-reload

Step 3: Enable and Start the Kanshi Service

Now, enable the kanshi service so it starts automatically on login, and then start it immediately:

systemctl --user enable --now kanshi.service

• enable: Creates the necessary symlinks for the service to start on boot.
• --now: Starts the service immediately after enabling it.

Step 4: Verify Service Status

To check if kanshi is running correctly as a systemd user service, you can check its status:

systemctl --user status kanshi.service

You should see output indicating that the service is active (running).

Important Considerations for Niri

For kanshi (and other Wayland-related services) to function correctly as systemd user services, your niri session needs to correctly set up the Wayland environment variables (WAYLAND_DISPLAY, XDG_RUNTIME_DIR). Most display managers (like GDM, SDDM, LightDM) and niri session scripts handle this automatically. If you encounter issues, ensure these variables are correctly exported in your niri startup process.

References

[1] kanshi - ArchWiki. (n.d.). Retrieved from https://wiki.archlinux.org/title/Kanshi