cups-kyocera-rastertokpsl-fix/README.md

<!--
SPDX-FileCopyrightText: 2026 Contributors to cups-kyocera-rastertokpsl-fix

SPDX-License-Identifier: CC0-1.0
-->

# CUPS wrapper for Kyocera `rastertokpsl`

A wrapper for the CUPS `rastertokpsl` filter designed to prevent crashes of the original Kyocera filter when processing print jobs with long or non-ASCII titles.

## Problem

Some versions of the Kyocera `rastertokpsl` filter use a fixed-size buffer to process the job title. Passing a long string or a string containing Cyrillic characters can cause a buffer overflow and result in the filter terminating unexpectedly:

```text
*** buffer overflow detected ***: terminated
```

In the CUPS logs, this may look like:

```text
PID 30752 (/usr/lib/cups/filter/rastertokpsl) crashed on signal 6
```

As a result, the job is not printed and the printer queue may enter the `stopped` state.

## Solution

The wrapper intercepts the CUPS arguments before launching the original `rastertokpsl`.

Before passing the job title to the original filter, the wrapper:

- converts UTF-8 to ASCII;
- removes unsupported characters;
- limits the string length;
- uses `print-job` if the resulting string is empty.

The original binary is stored as:

```text
/usr/lib/cups/filter/rastertokpsl.real
```

The wrapper is installed in its place:

```text
/usr/lib/cups/filter/rastertokpsl
```

## Installation

First, save the original filter:

```bash
sudo cp /usr/lib/cups/filter/rastertokpsl \
        /usr/lib/cups/filter/rastertokpsl.real
```

Create the wrapper file:

```bash
sudo nano /usr/lib/cups/filter/rastertokpsl
```

Contents:

```bash
#!/bin/bash

REAL="/usr/lib/cups/filter/rastertokpsl.real"

# Kyocera rastertokpsl uses the following arguments:
# $1 printer
# $2 job-id
# $3 title
# $4 copies
# $5 options

if [ "$#" -ne 5 ]; then
    echo "ERROR: rastertokpsl wrapper: expected 5 arguments, got $#" >&2
    exit 1
fi

printer="$1"
job_id="$2"
title="$3"
copies="$4"
options="$5"

# Convert the title to ASCII, remove unsupported characters,
# and limit its length to 20 characters.
safe_title="$(
    printf '%s' "$title" |
    iconv -f UTF-8 -t ASCII//TRANSLIT 2>/dev/null |
    LC_ALL=C tr -cd 'A-Za-z0-9' |
    tail -c 20
)"

[ -n "$safe_title" ] || safe_title="print-job"

# Pass the raster data through stdin.
exec "$REAL" \
    "$printer" \
    "$job_id" \
    "$safe_title" \
    "$copies" \
    "$options"
```

Set the appropriate permissions:

```bash
sudo chown root:root /usr/lib/cups/filter/rastertokpsl
sudo chmod 755 /usr/lib/cups/filter/rastertokpsl
sudo chmod 755 /usr/lib/cups/filter/rastertokpsl.real
```

Restart CUPS:

```bash
sudo systemctl restart cups
```

## Verification

Make sure the original file is an executable binary:

```bash
file /usr/lib/cups/filter/rastertokpsl.real
```

The expected output should contain `ELF ... executable`.

Test printing a normal job:

```bash
lp -d PRINTER /tmp/test.pdf
```

Then test a job with a long title:

```bash
lp -d PRINTER \
   -t "Very long Cyrillic job title for testing" \
   /tmp/test.pdf
```

Check the queue status:

```bash
lpstat -p
lpstat -o
```

To enable verbose CUPS logging when needed:

```bash
sudo cupsctl --debug-logging
sudo tail -F /var/log/cups/error_log
```

After troubleshooting is complete:

```bash
sudo cupsctl --no-debug-logging
```

## Restoring the Original Filter

To remove the wrapper and restore the original `rastertokpsl`:

```bash
sudo mv /usr/lib/cups/filter/rastertokpsl.real \
        /usr/lib/cups/filter/rastertokpsl

sudo systemctl restart cups
```

## Limitations

The wrapper is designed for a specific Kyocera `rastertokpsl` interface that uses five arguments:

```text
printer job-id title copies options
```

The `20` character limit was chosen as a conservative restriction for problematic filter versions. The exact size of the internal buffer depends on the specific `rastertokpsl` driver version and is not determined by CUPS itself.

Before installation, it is recommended to back up the original binary and check the driver version.

## Repository Structure

Example repository structure:

```text
cups-kyocera-rastertokpsl-fix/
├── README.md
└── rastertokpsl
```

The `rastertokpsl` file from the repository is installed to:

```text
/usr/lib/cups/filter/rastertokpsl
```