PrintMaster Documentation on PrintMaster Docs

Agent Module Documentation

Mon, 01 Jan 0001 00:00:00 +0000

Location: agent/agent/

The agent module handles network discovery protocols, device detection, SNMP operations, and live discovery methods. It sits between the scanner (device querying) and storage (persistence) layers.

Architecture Overview

agent/
├── detect.go # Main Discover() function, IP enumeration, ARP/ICMP
├── probe.go # TCP port probing, connectivity checks
├── parse.go # SNMP PDU parsing, OID interpretation
├── snmp.go # Legacy SNMP operations (being phased out)
├── snmp_iface.go # SNMP interface definitions
├── mdns.go # mDNS/Bonjour discovery
├── ssdp.go # SSDP/UPnP discovery
├── wsdiscovery.go # WS-Discovery protocol
├── snmptraps.go # SNMP trap listener
├── llmnr.go # LLMNR name resolution
├── arp.go # ARP table reading
├── merge.go # Device data merging and deduplication
├── helpers.go # Utility functions
├── metrics.go # Performance metrics collection
├── report.go # Scan result reporting
├── types.go # Data structures (PrinterInfo, ScanMeta, etc.)
├── config.go # Configuration structures
├── diagnostics.go # Diagnostic logging and debugging
├── update.go # Device update and refresh logic
└── vendor_roots.go # Vendor OID root definitions

Discovery Methods

1. Active Network Scanning (`detect.go`)

Purpose: Enumerate IP addresses and perform liveness checks.

Auto-Update & Installer Repackaging Plan

Mon, 01 Jan 0001 00:00:00 +0000

This document captures the agreed strategy for server- and agent-driven updates, including manifest signing, installer repackaging, and rollout choreography. It serves as a checklist we can iterate through incrementally.

Goals

Enable the PrintMaster server to self-update without user intervention (non-Docker deployments).
Allow the server to orchestrate agent updates, including fully background installations triggered from the fleet UI.
Provide customized installers (per fleet/tenant) that embed configuration data and can be used for both onboarding and update flows.
Maintain trust without external code-signing certificates by using server-signed manifests and checksum validation.
Keep Docker deployments opt-in / manual since they already rely on image pulls.

High-Level Architecture

Release Intake

Build & Release Workflow

Mon, 01 Jan 0001 00:00:00 +0000

Quick Start (Development)

Windows PowerShell Quick Launch

Use the helper script to test, build, and launch the agent:

# From project root (where dev/ exists)
pwsh -NoProfile -ExecutionPolicy Bypass .\dev\launch.ps1

This script will:

Run go test ./... (exits if tests fail)
Build agent into ./bin/printmaster-agent.exe
Start the built binary
Open browser to http://localhost:8080

Manual Development Workflow

If you prefer manual control:

# Run tests
go test ./...

# Build (from project root)
go build -o ./bin/printmaster-agent.exe ./agent

# Run the agent
./bin/printmaster-agent.exe

# Open UI
Start-Process 'http://localhost:8080'

Note: The launch script is intentionally conservative - tests must pass before build and server start.

Configuration Guide

Mon, 01 Jan 0001 00:00:00 +0000

Complete reference for configuring PrintMaster agent and server.

Configuration Methods
Agent Configuration
Server Configuration
Environment Variables
Command Line Options

Configuration Methods

PrintMaster supports multiple configuration methods, applied in this order (later overrides earlier):

Built-in defaults
Configuration file (config.toml)
Environment variables
Database-stored settings (UI changes)
Command-line flags

Configuration File Location

Platform	Agent Path	Server Path
Windows	`C:\ProgramData\PrintMaster\agent\config.toml`	`C:\ProgramData\PrintMaster\server\config.toml`
Linux	`/etc/printmaster/agent.toml`	`/etc/printmaster/server.toml`
macOS	`/Library/Application Support/PrintMaster/agent/config.toml`	`/Library/Application Support/PrintMaster/server/config.toml`
Docker	`/var/lib/printmaster/agent/config.toml`	`/var/lib/printmaster/server/config.toml`

Or place config.toml in the same directory as the binary.

Contributing to PrintMaster

Mon, 01 Jan 0001 00:00:00 +0000

Thank you for your interest in contributing to PrintMaster! This document provides guidelines and information to help you get started.

Code of Conduct
Getting Started
Development Setup
Project Structure
Making Changes
Testing
Submitting Changes
Adding Printer Support

Code of Conduct

Please be respectful and constructive in all interactions. We’re building something useful together.

Getting Started

Fork the repository on GitHub
Clone your fork locally
Create a branch for your changes

git clone https://github.com/YOUR_USERNAME/printmaster.git
cd printmaster
git checkout -b feature/your-feature-name

Development Setup

Prerequisites

Go 1.24+ - Download
Git - For version control
PowerShell (Windows) or Bash (Linux/macOS) - For build scripts

Building

# Windows - Build agent
.\build.ps1 agent

# Windows - Build server
.\build.ps1 server

# Windows - Build both
.\build.ps1 both

Running Tests

# Test agent packages
cd agent; go test ./... -v

# Test server packages
cd server; go test ./... -v

Quick Development Workflow

# Windows - Kill existing processes, build, and launch
.\dev\launch.ps1

Project Structure

printmaster/
├── agent/ # Agent binary - printer discovery & monitoring
│ ├── scanner/ # SNMP scanning pipeline
│ │ └── vendor/ # Vendor-specific OID profiles
│ ├── storage/ # SQLite device/metrics storage
│ └── web/ # Embedded web UI
├── server/ # Server binary - multi-agent management
│ ├── handlers/ # HTTP API handlers
│ ├── storage/ # Database layer
│ └── web/ # Embedded web UI
├── common/ # Shared packages (logger, config, etc.)
└── docs/ # Design documentation

Key documentation:

Deprecations and Removed Features

Mon, 01 Jan 0001 00:00:00 +0000

This document tracks features that have been removed or are pending removal, with rationale and migration notes.

Removed Features

Candidate/MIB Profile Workflow

Status: ✅ Removed
When: Early 2025
What: Agent no longer loads or parses vendor candidate files or MIB profiles. All associated UI and HTTP endpoints removed.
Rationale: Simplify agent, reduce maintenance cost, avoid tight coupling to vendor-specific data files
Migration: None required. Discovery now relies on Printer-MIB and minimal vendor-agnostic heuristics
Cleanup: Any data under mib_profiles/ can be deleted safely

Sandbox Simulation

Status: ✅ Removed
What: Sandbox feature (simulate candidates against saved walks) removed
Rationale: Depended on candidates/MIB profiles; added complexity without core value
Migration: Use built-in discovery and targeted diagnostic walks

`/mib_walk` HTTP Endpoint

Status: ✅ Removed
What: On-demand MIB walk HTTP endpoint
Rationale: Encourage bounded, targeted walks inside discovery pipeline; avoid broad, ad-hoc walks
Migration: Use discovery and “Walk All” device action in UI where applicable; targeted walks occur automatically for confirmed printers

`/saved_ranges` HTTP Endpoint

Status: ✅ Removed (Replaced)
When: October 2025
What: Legacy IP ranges endpoint
Replacement: Use unified /settings endpoint (GET/POST for discovery.ranges_text)

Migration:

// Old:
fetch('/saved_ranges');

// New:
const settings = await fetch('/settings').then(r => r.json());
const ranges = settings.discovery.ranges_text;

Manual MIB Walk UI Functions

Status: ✅ Removed
Location: agent/web/app.js
Functions: runMibWalk(), runMibWalkFor(ip)
Rationale: Full device information now gathered automatically during discovery; deep scan pipeline provides comprehensive data collection
Migration: Automated scanning provides all needed data

Removed Features (Previously Pending)

Old Logging System

Status: ✅ Removed
When: December 2025
Location: Was in agent/main.go
Functions: logMsg(msg string), logMutex, logBuffer []string
Description: Simple timestamp-prefixed logging to in-memory buffer and file
Replacement: Structured logger package (common/logger/logger.go) - now used throughout codebase
Migration: Complete - all logging now uses appLogger structured logging

Deprecated (Still Supported)

`/settings/subnet_scan` HTTP Endpoint

Status: ⚠️ Deprecated (still works)
Replacement: Use /settings endpoint (GET/POST for discovery.subnet_scan)

Migration:

// Old:
fetch('/settings/subnet_scan');

// New:
const settings = await fetch('/settings').then(r => r.json());
const enabled = settings.discovery.subnet_scan;

Removal Date: v1.0 (will be removed in 1.0 release)

Migration Checklist

When removing deprecated code:

Device Report Proxy Worker

Mon, 01 Jan 0001 00:00:00 +0000

This document describes the Cloudflare Worker that handles device diagnostic reports for PrintMaster.

Overview

The proxy worker receives diagnostic reports from PrintMaster agents, creates a GitHub Gist with the full diagnostic data, and returns URLs for creating a pre-filled GitHub issue.

Endpoint

URL: https://api.printmaster.work/diagnostic
Method: POST
Content-Type: application/json

Request Format

{
 "report": {
 "report_id": "RPT-18B2A3C4D5E6-1234",
 "timestamp": "2024-01-15T10:30:00Z",
 "agent_version": "0.25.7",
 "os": "windows",
 "arch": "amd64",
 "issue_type": "wrong_manufacturer",
 "expected_value": "HP LaserJet Pro M404dn",
 "user_message": "Device shows as Unknown instead of HP",
 "device_ip": "10.0.1.50",
 "device_serial": "VNC1234567",
 "device_model": "HP LaserJet Pro M404dn",
 "device_mac": "00:11:22:33:44:55",
 "current_manufacturer": "Unknown",
 "current_model": "Unknown Printer",
 "current_serial": "VNC1234567",
 "current_hostname": "[hash:a1b2c3d4]",
 "current_page_count": 15234,
 "detected_vendor": "Unknown",
 "detection_steps": [
 "Querying sysDescr (.1.3.6.1.2.1.1.1.0)",
 "No vendor match found"
 ],
 "snmp_responses": [
 {
 "oid": ".1.3.6.1.2.1.1.1.0",
 "type": "OctetString",
 "value": "HP LaserJet Pro M404dn",
 "hex_value": ""
 }
 ],
 "recent_logs": [
 "2024-01-15T10:29:55Z [INFO] Scanning device 10.0.1.50"
 ]
 }
}

Response Format

Success (200 OK)

{
 "success": true,
 "gist_url": "https://gist.github.com/printmaster-bot/abc123def456",
 "issue_url": "https://github.com/printmaster-org/printmaster/issues/new?template=device-report.yml&title=%5BDevice+Report%5D+wrong_manufacturer+%E2%80%93+HP+LaserJet+Pro+M404dn&gist_url=https%3A%2F%2Fgist.github.com%2Fprintmaster-bot%2Fabc123def456&issue_type=Wrong+manufacturer+detection&expected_value=HP+LaserJet+Pro+M404dn&device_model=HP+LaserJet+Pro+M404dn&device_manufacturer=Unknown"
}

Error (4xx/5xx)

{
 "success": false,
 "error": "Failed to create gist: rate limit exceeded"
}

Cloudflare Worker Implementation

Create a new Cloudflare Worker with the following code:

Docker Deployment

Mon, 01 Jan 0001 00:00:00 +0000

Deploy PrintMaster Server using Docker containers with multi-architecture support.

Quick Start

docker run -d \
 --name printmaster-server \
 -p 9090:9090 \
 -v printmaster-data:/var/lib/printmaster/server \
 -e ADMIN_PASSWORD=your-secure-password \
 ghcr.io/printmaster-org/printmaster-server:latest

Access at http://localhost:9090 with username admin.

Supported Architectures

All images are built for multiple architectures automatically:

Architecture	Platform	Use Case
`linux/amd64`	x86_64 servers	Intel/AMD servers, cloud VMs
`linux/arm64`	ARM 64-bit	Apple Silicon, AWS Graviton, Raspberry Pi 4+
`linux/arm/v7`	ARM 32-bit	Raspberry Pi 3/4 (32-bit OS)

Docker automatically pulls the correct architecture for your platform.

E2E Testing Strategy

Mon, 01 Jan 0001 00:00:00 +0000

Overview

End-to-end tests verify that the agent and server work together correctly. These tests are more expensive than unit tests but provide confidence that the full system functions as expected.

Quick Start

Run E2E Tests Locally

# Linux/macOS
cd tests
./run-e2e.sh

# Windows
cd tests
.\run-e2e.ps1

Options

Option	Description
`--build` / `-Build`	Force rebuild Docker containers
`--keep-up` / `-KeepUp`	Leave containers running after tests
`--verbose` / `-Verbose`	Show detailed output

Architecture

Docker Compose Environment

The E2E tests use Docker Compose to create an isolated test environment:

Epson Enterprise OID Mapping

Mon, 01 Jan 0001 00:00:00 +0000

Device: AM-C550 Series (172.52.105.91)
Enterprise OID Base: 1.3.6.1.4.1.1248.1.2.2.27.*
Validation Date: 2025-11-03
Status: ✅ Fully validated against device web interface

Direct OID Mappings (No Calculation Needed)

Page Count Totals

Metric	OID	Value	Status
Total Pages	`.27.1.1.30.1.1`	81,563	✅ Exact match
Total B&W Pages	`.27.1.1.3.1.1`	39,797	✅ Exact match
Total Color Pages	`.27.1.1.4.1.1`	41,766	✅ Exact match

Function-Specific Counters (Combined B&W + Color)

Metric	OID	Value	Calculation
Total Print from Computer	`.27.6.1.4.1.1.1`	49,053	B&W Print (9,619) + Color Print (39,434) = 49,053 ✅
Total Copy	`.27.6.1.4.1.1.2`	32,474	B&W Copy (30,161) + Color Copy (2,313) = 32,474 ✅

Color-Specific Counters

Metric	OID	Value	Status
Color Print from Computer	`.27.6.1.5.1.1.1`	39,434	✅ Exact match
Color Copy	`.27.6.1.5.1.1.2`	2,313	✅ Exact match

Calculated Metrics (via Subtraction)

B&W Function Breakdown

B&W Print from Computer = Total Print from Computer - Color Print from Computer
 = 49,053 - 39,434
 = 9,619 ✅

B&W Copy = Total Copy - Color Copy
 = 32,474 - 2,313
 = 30,161 ✅

Color Function Breakdown (if needed)

Color Print Other = Color Total - Color Print from Computer - Color Copy
 = 41,766 - 39,434 - 2,313
 = 19 ✅

B&W Function Breakdown (if needed)

B&W Print Other = B&W Total - B&W Print from Computer - B&W Copy
 = 39,797 - 9,619 - 30,161
 = 17 ✅

Scan Counters (Not Yet Found in OIDs)

From web UI:

Epson Remote-Mode Integration Plan

Mon, 01 Jan 0001 00:00:00 +0000

This document captures the concrete steps required to land Epson remote-mode support in the agent while keeping the feature isolated behind a flag and reusing the new SNMP batching helper.

Goals

Reuse the remote-mode command surface documented in docs/SNMP_RESEARCH_NOTES.md (commands di, st, ia, ii, ||).
Surface reliable ink, maintenance-box, and alert data in PrinterInfo/metrics without relying on sparse Printer-MIB leaves.
Limit SNMP chatter by batching OIDs (already covered by batchedGet) and caching EEPROM ranges per device.

Building Blocks

Batching helper (agent/scanner/snmp_batch.go): already available; use it whenever remote-mode helpers need scalar GETs.
Vendor module hook (agent/scanner/vendor/epson.go): entry point for calling the remote-mode helper from MetricOIDs/Parse whenever the feature flag is on.
Learned OID cache (agent/agent/types.go::LearnedOIDMap): add an EpsonEEPROMWindows slice so we remember which address ranges returned data.
Feature flag plumbing: add epson_remote_mode_enabled to agent config, default false, surfaced through settings UI.
Storage + downsampling: extend DeviceMetricsSnapshot to track main_waste, borderless_waste, waste_box_3 so they flow through existing downsamplers.

Implementation Steps

Remote-mode transport helper

Features Guide

Mon, 01 Jan 0001 00:00:00 +0000

Complete guide to PrintMaster’s features and capabilities.

Device Discovery
Device Monitoring
Multi-Site Management
WebSocket Proxy
Alerts & Notifications
Scheduled Scans
Auto-Updates
Security Features
API Access

Device Discovery

PrintMaster automatically discovers printers and copiers on your network using SNMP.

How Discovery Works

Port Scanning: Quick TCP scan to find devices with printer ports open (80, 443, 9100)
SNMP Detection: Query each candidate to confirm it’s a printer
Deep Scan: Collect detailed device information via SNMP

Discovery Methods

Method	Description	When Used
IP Range Scan	Scan a specified range of IP addresses	Manual configuration
Subnet Auto-Scan	Automatically scan local subnets	Default behavior
Single Device	Add a specific printer by IP	Known devices

Supported Devices

PrintMaster supports most SNMP-enabled printers and copiers, including:

Frequently Asked Questions

Mon, 01 Jan 0001 00:00:00 +0000

Common questions about PrintMaster.

General

What is PrintMaster?

PrintMaster is a cross-platform printer/copier fleet management system. It automatically discovers network printers, collects device information (model, serial number, page counts, toner levels), and provides a web interface for monitoring your print fleet.

Who is PrintMaster for?

Managed Service Providers (MSPs) - Monitor client print infrastructure
Managed Print Services (MPS) providers - Track usage and supplies
Copier dealers - Manage devices across customer sites
IT departments - Monitor corporate print fleets

Is PrintMaster free?

Yes, PrintMaster is open source and free to use under the MIT license.

Getting Started

Mon, 01 Jan 0001 00:00:00 +0000

This guide walks you through your first steps with PrintMaster after installation.

Overview
Standalone Agent Setup
Server + Agent Setup
Discovering Printers
Understanding the Dashboard
Next Steps

Overview

PrintMaster can be used in two modes:

Standalone Mode: Run just the agent to monitor printers at a single site
Server Mode: Run a central server with multiple agents across sites

Choose the setup that matches your needs:

Use Case	Recommended Setup
Single office, single network	Standalone Agent
Multiple sites, centralized management	Server + Agents
MSP managing multiple clients	Server + Agents (multi-tenant)

Standalone Agent Setup

If you’re monitoring printers at a single location, the standalone agent is all you need.

Git & GitHub Integration - Complete ✅

Mon, 01 Jan 0001 00:00:00 +0000

What Was Added

1. Automated Release Script (`release.ps1`)

Location: c:\temp\printmaster\release.ps1

Usage:

# Patch release (bug fixes)
.\release.ps1 agent patch

# Minor release (new features)
.\release.ps1 agent minor

# Major release (breaking changes)
.\release.ps1 agent major

# Release server or both
.\release.ps1 server patch
.\release.ps1 both patch

What it does automatically:

✅ Checks if working directory is clean
✅ Bumps version in VERSION file(s)
✅ Runs all tests
✅ Builds optimized release binary
✅ Commits VERSION change
✅ Creates git tag (e.g., v0.2.0)
✅ Pushes to GitHub

Flags:

Installation Guide

Mon, 01 Jan 0001 00:00:00 +0000

This guide covers installing PrintMaster on all supported platforms.

Quick Install
Server Installation
Agent Installation
First-Time Setup

Quick Install

Server (Docker)

docker run -d \
 --name printmaster-server \
 -p 9090:9090 \
 -v printmaster-data:/var/lib/printmaster/server \
 -e ADMIN_PASSWORD=your-secure-password \
 ghcr.io/printmaster-org/printmaster-server:latest

Access at http://localhost:9090 with username admin and your chosen password.

Agent (Windows)

Download and run the MSI installer from GitHub Releases.

Kyocera Enterprise OID Mapping

Mon, 01 Jan 0001 00:00:00 +0000

Device: TASKalfa 6052ci (172.52.105.95)
Serial: W2D8303202
Enterprise OID Base: 1.3.6.1.4.1.1347.*
Analysis Date: 2025-11-03
Status: ✅ VALIDATED - Complete OID structure decoded

Summary

Kyocera devices provide exceptional detail via enterprise OIDs:

Standard Printer-MIB provides total impressions (432,951)
Kyocera .42.3.* tree provides complete function and color breakdown
Direct OIDs available for all major metrics (no calculation needed!)
Best-in-class metrics compared to other vendors

Validated OID Mappings

Page Count Totals

Metric	OID	Value	Validated
Total Impressions	`1.3.6.1.2.1.43.10.2.1.4.1.1`	432,951	✅ Standard Printer-MIB
Total Printed Pages	`1.3.6.1.4.1.1347.43.10.1.1.12.1.1`	424,405	✅ Kyocera Enterprise
Total B&W Printed	Calculated	241,538	Sum of B&W functions
Total Color Printed	Calculated	182,867	Sum of Color functions

Kyocera Enterprise OID Structure (`.42.3.*`)

Function Totals (`.42.3.1.1.1.*`)

Metric	OID	Value	Validated
Printer Total	`1.3.6.1.4.1.1347.42.3.1.1.1.1`	304,339	✅
Copy Total	`1.3.6.1.4.1.1347.42.3.1.1.1.2`	116,254	✅
Fax Total	`1.3.6.1.4.1.1347.42.3.1.1.1.4`	3,812	✅

Print Breakdown by Function and Color (`.42.3.1.2.1.1.*`)

Metric	OID	Value	Validated
Printer B&W	`1.3.6.1.4.1.1347.42.3.1.2.1.1.1.1`	163,915	✅
Printer Color	`1.3.6.1.4.1.1347.42.3.1.2.1.1.1.3`	140,424	✅
Copy B&W	`1.3.6.1.4.1.1347.42.3.1.2.1.1.2.1`	73,811	✅
Copy Color	`1.3.6.1.4.1.1347.42.3.1.2.1.1.2.3`	42,443	✅
Fax B&W	`1.3.6.1.4.1.1347.42.3.1.2.1.1.4.1`	3,812	✅

Scan Counters (`.42.3.1.3.1.1.*`)

Metric	OID	Value	Validated
Copy Scans	`1.3.6.1.4.1.1347.42.3.1.3.1.1.2`	42,138	✅
Fax Scans	`1.3.6.1.4.1.1347.42.3.1.3.1.1.4`	3,057	✅
Other Scans	`1.3.6.1.4.1.1347.42.3.1.4.1.1.1`	43,441	✅

Calculated Totals (Validation)

Total B&W Printed:
 Printer B&W (163,915) + Copy B&W (73,811) + Fax B&W (3,812) = 241,538 ✅

Total Color Printed:
 Printer Color (140,424) + Copy Color (42,443) + Fax Color (0) = 182,867 ✅

Total Printed:
 Printer (304,339) + Copy (116,254) + Fax (3,812) = 424,405 ✅

Total Scans:
 Copy Scans (42,138) + Fax Scans (3,057) + Other Scans (43,441) = 88,636 ✅

Previously Found OIDs (Still Investigating)

OID Pair 1: B&W vs Color Split

OID	Value	Likely Meaning
`.43.10.1.1.16.1.1`	221,912	B&W Total or Color Total?
Calculated	211,039	Complementary (Total - 221,912)

Math Check: 221,912 + 211,039 = 432,951 ✅

MIB profiles (mib_profiles/) and automation

Mon, 01 Jan 0001 00:00:00 +0000

This document describes the lightweight JSON schema used to store manufacturer MIB profiles, recommended workflow for generating profiles from collected MIB walks, and how profiles can be distributed to agents.

Schema (example keys)

vendor (string): short vendor id, e.g. “hp”
enterprise_oid (string): vendor enterprise prefix, e.g. “1.3.6.1.4.1.11”
version (string): profile version
canonical (map): semantic name -> OID (page_count, serial, supplies roots, etc.)
probes (array): recommended quick probe OIDs that are safe/cheap to GET during discovery
sample_values (map): example values to help human review and tests
notes (string): freeform notes

Storage and runtime plan

PostgreSQL and TimescaleDB Upgrades

Mon, 01 Jan 0001 00:00:00 +0000

PrintMaster’s Compose examples use timescale/timescaledb:latest-pg18 for new deployments. The server supports PostgreSQL 18 and TimescaleDB through the standard pgx driver and TimescaleDB APIs.

Important warning

Changing latest-pg15 to latest-pg18 while keeping the existing /var/lib/postgresql volume will not perform a PostgreSQL major upgrade. PostgreSQL 15 and 18 use incompatible data-directory formats. The container will normally refuse to start, and deleting the volume would destroy data.

For PG18, mount the volume at /var/lib/postgresql, not /var/lib/postgresql/data. The PG18 image manages its version-specific data directory below that root.

PrintMaster Overview

Mon, 01 Jan 0001 00:00:00 +0000

PrintMaster automatically discovers and monitors network printers and copiers. Built for MSPs, MPS providers, copier dealers, and IT departments managing print fleets.

Why PrintMaster?

PrintMaster was born from real-world frustration managing multi-vendor print fleets. Existing solutions meant juggling multiple tools—PrintAudit for metering, Epson Remote Services for Epson devices, Kyocera Net Manager for Kyocera, Epson Device Admin for local management—each with their own quirks, agents that randomly disconnect, and per-device licensing fees.

PrintMaster Test Coverage Analysis

Mon, 01 Jan 0001 00:00:00 +0000

Last Updated: December 27, 2025

This document provides a comprehensive analysis of test coverage across the PrintMaster codebase, identifying well-tested areas, gaps, and recommendations for improvement.

Executive Summary

Component	Test Files	Coverage Level	Priority for Improvement
Server Storage	20+	⭐⭐⭐⭐⭐ Excellent	Low
Agent Scanner	8	⭐⭐⭐⭐ Good	Medium
Common Libraries	12	⭐⭐⭐⭐ Good	Low
Server API/Handlers	3	⭐⭐⭐ Moderate	Medium
Agent Storage	6	⭐⭐⭐⭐ Good	Low
Reports System	3	⭐⭐⭐ Moderate	Medium
WebSocket/Proxy	2	⭐⭐⭐ Moderate	Medium
E2E Tests	3	⭐⭐ Basic	HIGH
Email Templates	0	⭐ None	HIGH
Spooler (Windows)	0	⭐ None	HIGH
Metrics Collector	0	⭐ None	HIGH
Report Scheduler	0	⭐ None	HIGH
OIDC Handlers	0	⭐ None	Medium
JS/Frontend	14	⭐⭐⭐ Moderate	Medium

1. Go Unit Tests (92 test files)

1.1 Server Package (`server/`)

✅ Excellent Coverage

File/Package	Tests	Description
`storage/*_test.go`	20+ files	Most comprehensive testing - Covers all CRUD operations, agents, devices, metrics, alerts, reports, users, sessions, tenants, settings, OIDC, dialects
`main_test.go`	30+ tests	Health endpoints, auth, heartbeat, batch uploads, token handling, device proxy parsing
`config_test.go`	Multiple	Configuration loading/parsing
`websocket_test.go`	8+ tests	WebSocket connection, heartbeat, proxy requests

Key storage tests:

PrintMaster TODO

Mon, 01 Jan 0001 00:00:00 +0000

Consolidated pending features and improvements from across the codebase.

Current Version: Agent v0.23.6, Server v0.23.6

🔴 High Priority (Pre-1.0)

USB Printer Support

Implemented via an IPP-USB HTTP proxy (Windows only) — see USB_IMPLEMENTATION.md. The earlier pure-Go SNMP-over-USB plan (gousbsnmp) was abandoned and never built.

IPP-USB proxy + web-scraped metrics (Windows)
Linux/macOS USB device enumeration + proxy support
Same metrics as network printers (page counts, toner, supplies) - USB scraping is best-effort per vendor, not at parity yet
USB printer configuration UI
USB/network printer differentiation in main devices table (currently tracked separately)

SNMPv3 Support

Security enhancement for enterprise deployments.

PROJECT STRUCTURE

Mon, 01 Jan 0001 00:00:00 +0000

Project Structure (Overview)

printmaster/
├── agent/ # Agent service and embedded UI (Go)
│ ├── main.go # Agent entrypoint
│ ├── config.go / config.toml # Agent configuration loader + sample
│ ├── agent/ # Discovery + protocol workers (mDNS, SSDP, etc.)
│ ├── scanner/ # SNMP pipeline, vendor registry, metrics extraction
│ ├── storage/ # Embedded SQLite schema + migrations
│ ├── proxy/ / supplies/ # Proxy tunnel + consumables helpers
│ ├── featureflags/ # Toggle definitions used by agent UI
│ ├── web/ # Embedded UI assets (built into the binary)
│ └── docs/ # Agent-specific reference material
├── server/ # Multi-agent server/API hub (Go)
│ ├── main.go # Server entrypoint
│ ├── config.go / config.toml # Server configuration + defaults
│ ├── websocket.go # Agent tunnel / live proxy handling
│ ├── storage/ # Server persistence + tenancy data
│ ├── authz/, logger/, tls.go # Auxiliary subsystems
│ └── web/ # Server UI + static assets
├── common/ # Shared Go modules (config, logger, snmp, util, web)
├── docs/ # Architecture + operations documentation
├── dev/ # Local developer scripts (e.g., launch.ps1)
├── scripts/ # Operational PowerShell helpers (kill, update, etc.)
├── tools/ # Standalone utilities and generators
├── tests/ # Integration / e2e test harnesses
├── static/ # Third-party front-end assets (e.g., flatpickr)
├── ui/ # Legacy UI experiments (kept for reference)
├── logs/, test-results/ # Output folders (ignored in git)
├── build.ps1 / release.ps1 # Build + release orchestration
└── README.md # High-level overview

Module Descriptions

Agent (`agent/`)

Single-binary agent that discovers printers, collects metrics, persists to SQLite, and serves the embedded UI. Key subpackages:

Range syntax and parsing rules

Mon, 01 Jan 0001 00:00:00 +0000

This file documents what the server accepts in the range editor textarea and how the ParseRangeText behavior works.

Supported formats

Single IPv4 address: e.g. 192.168.1.42
CIDR notation: e.g. 192.168.1.0/24
Full range (start-end): e.g. 192.168.1.10-192.168.1.20
Short-hand range (right side maps to last N octets):
- 192.168.1.10-20 expands to 192.168.1.10 through 192.168.1.20.
- 10-20 is interpreted relative to the default/prepended subnet only when configured in the UI as Add/Override behavior.
Last-octet wildcard: 192.168.1.x or 192.168.1.* (expands the last octet 0..255)

Behaviors and constraints

REMAINING TASKS

Mon, 01 Jan 0001 00:00:00 +0000

Remaining tasks for Printer MIB pairing & candidate workflows

Overview

This document lists remaining work items, priorities, acceptance criteria, and testing notes for the features implemented during the recent changes: pairing of list columns (name/level) from saved MIB walks, UI flow to inspect saved walks, and persisting candidate mappings.

High-level goals

Let the agent detect and present column-based consumable information (e.g. toner names and levels) from saved MIB walks.
Allow users to persist discovered column mappings into vendor candidate profiles quickly and reliably.
Provide robust normalization and tests for edge-cases across vendors.

Priority tasks

Security Architecture for Agent-Server Communication

Mon, 01 Jan 0001 00:00:00 +0000

Overview

This document outlines the security architecture for when the PrintMaster agent communicates with a central server, particularly for the reverse proxy feature where the server may relay connections between users and printers through the agent.

Threat Model

Agent → Server: Agent authenticates to server, sends discovery data, receives config
User → Server → Agent → Printer: User accesses printer web UI through server proxy that routes through agent
Key Risks: Unauthorized agent access, credential interception, session hijacking, MITM attacks, unauthorized printer access

Security Layers

1. Agent Authentication (MVP)

Purpose: Verify agent identity before accepting connections or data uploads.

Security Policy

Mon, 01 Jan 0001 00:00:00 +0000

Supported Versions

We release security patches for the following versions:

Component	Version	Supported
Agent	latest	:white_check_mark:
Server	latest	:white_check_mark:

We recommend always running the latest version for the best security.

Reporting a Vulnerability

Please do not report security vulnerabilities through public GitHub issues.

Instead, please report them privately via one of these methods:

Option 1: GitHub Security Advisories (Preferred)

Go to the Security tab
Click “Report a vulnerability”
Fill out the form with details

Option 2: Email

Send details to the repository owner via GitHub (check profile for contact info).

Service Mode - Quick Reference

Mon, 01 Jan 0001 00:00:00 +0000

Overview

PrintMaster Agent can run as a system service for production deployments. This ensures the agent starts automatically on boot and runs continuously in the background.

Commands

# Install service (requires admin/root)
printmaster-agent --service install

# Start service
printmaster-agent --service start

# Stop service
printmaster-agent --service stop

# Uninstall service
printmaster-agent --service uninstall

# Run in foreground (testing)
printmaster-agent --service run

# Interactive mode (default)
printmaster-agent

Platform-Specific Details

Windows

Requirements: Administrator privileges

SNMP Reference Guide

Mon, 01 Jan 0001 00:00:00 +0000

This document covers SNMP discovery, Printer-MIB OIDs, vendor detection, metrics collection, and meter history tracking in PrintMaster.

Overview

PrintMaster uses SNMP (Simple Network Management Protocol) to discover and monitor network printers. The implementation follows a two-phase scan approach:

Phase 1 (Quick Probe) - Small number of SNMP GETs to quickly verify device is a printer
Phase 2 (Deep Scan) - Targeted walk for confirmed printers to gather detailed metrics

This approach keeps discovery fast on large networks while still capturing rich vendor-specific data.

SNMP Research Notes

Mon, 01 Jan 0001 00:00:00 +0000

This file captures actionable takeaways from inspecting other open-source SNMP printer discovery/management tools so we can fold the best ideas into PrintMaster without blindly copying code.

Sources Consulted

Ircama/epson_print_conf (Python) — exhaustive remote-mode OIDs plus EEPROM decoding for dozens of Epson models (epson_print_conf.py).
CUPS SNMP backend (backend/snmp.c) — hardened discovery logic with vendor-specific fallbacks (OpenPrinting/cups).

Standard OIDs We Should Poll Everywhere

These came up repeatedly in both projects and map cleanly to our existing data model:

Testing and CI guidelines

Mon, 01 Jan 0001 00:00:00 +0000

This document describes how to write fast, deterministic tests for the PrintMaster agent and server.

Test Types

PrintMaster has three levels of testing:

Unit Tests - Test individual functions/packages in isolation (agent/, server/)
Integration Tests - Test component interactions (e.g., database rotation)
End-to-End Tests - Test full agent-server communication (see tests/ directory)

For E2E test details, see ../tests/E2E_TESTING.md.

Why mocking is necessary

Network operations (ICMP, TCP connect, SNMP Get/Walk) are slow and flaky in CI. Unit tests must avoid touching the real network so they remain fast and reliable. The project uses small package-level factories and interfaces to make mocking easy.

Troubleshooting Guide

Mon, 01 Jan 0001 00:00:00 +0000

Solutions for common PrintMaster issues.

Discovery Issues
Connection Issues
Web UI Issues
Service Issues
Database Issues
Performance Issues
Logs & Diagnostics

Discovery Issues

No Printers Found

Symptoms: Scan completes but no devices appear.

Solutions:

Verify network connectivity

# Can you reach the printer?
ping 192.168.1.100

Check SNMP is enabled on the printer
- Access the printer’s web interface
- Look for SNMP settings in Network or Security
- Ensure SNMP v1/v2c is enabled
Verify the SNMP community string

Unraid Deployment

Mon, 01 Jan 0001 00:00:00 +0000

Deploy PrintMaster Server on Unraid using the Docker container.

Installation Methods

Method 1: Community Applications (Recommended)

Install Community Applications plugin if not already installed
Search for “PrintMaster Server”
Click Install
Configure settings (see below)
Click Apply

Method 2: Manual Docker Setup

Go to Docker tab in Unraid
Click Add Container
Configure:

Setting	Value
Name	`PrintMaster-Server`
Repository	`ghcr.io/printmaster-org/printmaster-server:latest`
Network Type	`Bridge`
Port	`9090` → `9090` (TCP)
Volume	`/mnt/user/appdata/printmaster-server/data` → `/var/lib/printmaster/server`
Volume	`/mnt/user/appdata/printmaster-server/logs` → `/var/log/printmaster/server`

Configuration

Essential Settings

Setting	Value	Description
HTTP Port	`9090`	Web interface and API
Data Directory	`/mnt/user/appdata/printmaster-server/data`	Database storage
Logs Directory	`/mnt/user/appdata/printmaster-server/logs`	Application logs
Timezone	Your timezone (e.g., `America/New_York`)	For correct timestamps

Environment Variables

Variable	Value	Description
`BIND_ADDRESS`	`0.0.0.0`	Allow external access
`BEHIND_PROXY`	`true` or `false`	Behind Nginx Proxy Manager?
`LOG_LEVEL`	`info`	`debug`, `info`, `warn`, `error`
`TZ`	`America/New_York`	Your timezone
`PM_DISABLE_SELFUPDATE`	`true`	Recommended for Docker

Reverse Proxy Setup

With Nginx Proxy Manager

Set container variables:

USB Printer Support

Mon, 01 Jan 0001 00:00:00 +0000

Status: ✅ Implemented (Windows only)

Summary

USB printer support is implemented as an IPP-USB HTTP proxy, not the SNMP-over-USB approach originally planned (see “Abandoned approach” below). The agent enumerates USB printers that expose an embedded web UI over the IPP-USB interface class, then tunnels HTTP requests to that web UI over the USB bulk endpoints — the same approach used by OpenPrinting/ipp-usb.

Metrics (page counts, toner levels, etc.) are obtained by scraping the printer’s embedded web UI/XML endpoints, not by querying SNMP OIDs over USB.

Vendor Meter Analysis from Production Logs

Mon, 01 Jan 0001 00:00:00 +0000

Date: November 3, 2025
Source: logs_20251103_064511.zip analysis
Purpose: Identify meter detection gaps and opportunities for vendor-specific OID improvements

Executive Summary

Analysis of 10 production devices revealed:

✅ All devices successfully report page counts during discovery (standard Printer-MIB)
❌ Metrics collection fails with zeros despite OIDs being correct
🎯 Root cause: SNMP GET queries fail where WALK succeeds
💡 Solution: Learned OID system (already implemented) will fix this
🔍 Opportunity: Vendor-specific enterprise OIDs offer additional counters

Device Breakdown

1. Epson AM-C550 Series (172.52.105.91) ✅ VALIDATED

Current Status: ❌ Metrics returning 0 despite discovery finding 81,563 pages
Vendor Module: Generic (no Epson module exists)
Discovery OID: 1.3.6.1.2.1.43.10.2.1.4.1.1 = 81,563 ✅ Validation Date: 2025-11-03

WebSocket HTTP Proxy Feature

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The PrintMaster system now supports proxying HTTP requests through the WebSocket connection between agents and the server. This allows you to access:

Agent web UIs from anywhere (even behind NAT/firewalls)
Device web UIs (printer admin pages) through the agent’s network connection

Architecture

Browser → Server → WebSocket → Agent → Target (Agent UI or Device)
 ← ← ← ←

Flow

User clicks “Open UI” button in the server web interface
Browser makes HTTP request to server proxy endpoint
Server converts HTTP request to WebSocket message (proxy_request)
Server sends message through WebSocket to connected agent
Agent receives proxy request and makes local HTTP request to target
Agent sends HTTP response back through WebSocket (proxy_response)
Server forwards response to browser

WebSocket Protocol

Message Types

`proxy_request` (Server → Agent)

{
 "type": "proxy_request",
 "data": {
 "request_id": "unique-id",
 "url": "http://localhost:8080/",
 "method": "GET",
 "headers": {
 "User-Agent": "...",
 "Accept": "..."
 },
 "body": "base64-encoded-body"
 },
 "timestamp": "2025-11-07T12:00:00Z"
}

`proxy_response` (Agent → Server)

{
 "type": "proxy_response",
 "data": {
 "request_id": "unique-id",
 "status_code": 200,
 "headers": {
 "Content-Type": "text/html",
 "Content-Length": "1234"
 },
 "body": "base64-encoded-response-body"
 },
 "timestamp": "2025-11-07T12:00:01Z"
}

API Endpoints

Agent UI Proxy

GET /api/v1/proxy/agent/{agentID}/{path...}

Proxies HTTP requests to the agent’s own web UI (typically running on http://localhost:8080).

PrintMaster Documentation on PrintMaster Docs

Agent Module Documentation

Architecture Overview

Discovery Methods

1. Active Network Scanning (detect.go)

Auto-Update & Installer Repackaging Plan

Goals

High-Level Architecture

Build & Release Workflow

Quick Start (Development)

Windows PowerShell Quick Launch

Manual Development Workflow

Configuration Guide

Table of Contents

Configuration Methods

Configuration File Location

Contributing to PrintMaster

Table of Contents

Code of Conduct

Getting Started

Development Setup

Prerequisites

Building

Running Tests

Quick Development Workflow

Project Structure

Deprecations and Removed Features

Removed Features

Candidate/MIB Profile Workflow

Sandbox Simulation

/mib_walk HTTP Endpoint

/saved_ranges HTTP Endpoint

Manual MIB Walk UI Functions

Removed Features (Previously Pending)

Old Logging System

Deprecated (Still Supported)

/settings/subnet_scan HTTP Endpoint

Migration Checklist

Device Report Proxy Worker

Overview

Endpoint

Request Format

Response Format

Success (200 OK)

Error (4xx/5xx)

Cloudflare Worker Implementation

Docker Deployment

Quick Start

Supported Architectures

E2E Testing Strategy

Overview

Quick Start

Run E2E Tests Locally

Options

Architecture

Docker Compose Environment

Epson Enterprise OID Mapping

Direct OID Mappings (No Calculation Needed)

Page Count Totals

Function-Specific Counters (Combined B&W + Color)

Color-Specific Counters

Calculated Metrics (via Subtraction)

B&W Function Breakdown

Color Function Breakdown (if needed)

B&W Function Breakdown (if needed)

Scan Counters (Not Yet Found in OIDs)

Epson Remote-Mode Integration Plan

Goals

Building Blocks

Implementation Steps

Features Guide

Table of Contents

Device Discovery

How Discovery Works

Discovery Methods

Supported Devices

Frequently Asked Questions

General

What is PrintMaster?

Who is PrintMaster for?

1. Active Network Scanning (`detect.go`)

`/mib_walk` HTTP Endpoint

`/saved_ranges` HTTP Endpoint

`/settings/subnet_scan` HTTP Endpoint

1. Automated Release Script (`release.ps1`)

Kyocera Enterprise OID Structure (`.42.3.*`)

Function Totals (`.42.3.1.1.1.*`)

Print Breakdown by Function and Color (`.42.3.1.2.1.1.*`)

Scan Counters (`.42.3.1.3.1.1.*`)

1.1 Server Package (`server/`)

Agent (`agent/`)