87 lines
4.1 KiB
Markdown
87 lines
4.1 KiB
Markdown
|
# 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:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
mkdir -p ~/.config/systemd/user/
|
||
|
|
```
|
||
|
|
|
||
|
|
Then, place the following content into `~/.config/systemd/user/kanshi.service`:
|
||
|
|
|
||
|
|
```ini
|
||
|
|
[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:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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](https://wiki.archlinux.org/title/Kanshi)
|