Documentation
¶
Overview ¶
Package server is the print server: a spool (print/spool) of the queues and printers of a configuration file, its HTTP API (/api/v1), the changes as Server-Sent Events, /metrics, and a page of its state. bdf printd runs it.
Index ¶
- func AirPrintProfile(cfg *Config, host string, port int) ([]byte, error)
- func ZoneRecords(cfg *Config, domain string, port int, caps map[string]*ipp.Printer) (string, error)
- type Config
- type Duration
- type FontsConfig
- type IPPConfig
- type LimitsConfig
- type Options
- type PrinterCheck
- type PrinterConfig
- type QueueConfig
- type RetentionConfig
- type Server
- type Size
- type TLSConfig
- type TokenConfig
- type UpstreamConfig
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AirPrintProfile ¶
AirPrintProfile is a configuration profile (.mobileconfig) that adds the IPP printers to iPhones and iPads that do not see them with mDNS (on another subnet): an AirPrint payload of each queue (the address, its path, the port, TLS), and the server's certificate as a root to trust when the server signed it itself. An MDM sends it, or a person opens it in Safari (the page of the printers links it). host is the name or the address the devices reach the server at; port the IPP server's.
func ZoneRecords ¶
func ZoneRecords(cfg *Config, domain string, port int, caps map[string]*ipp.Printer) (string, error)
ZoneRecords are the records of the queues for a DNS zone (RFC 6763 §11, wide-area DNS-SD), in the zone file's format: clients of other subnets find the printers in the domain, as they find them with mDNS on theirs. The host is the IPP server's (ipp.host), a name of the zone; caps give the queues' printers' capabilities (CheckPrinters), nil when unknown.
Types ¶
type Config ¶
type Config struct {
// Listen is the address of the HTTP API: 127.0.0.1:8640 by default.
Listen string `yaml:"listen"`
// Spool is the spool's file: spool.db next to the configuration
// file by default.
Spool string `yaml:"spool"`
// User is the requesting-user-name sent to the printers: "bdf" by
// default.
User string `yaml:"user"`
// TLS serves HTTPS; it is required when Listen is not a loopback
// address, unless Insecure.
TLS *TLSConfig `yaml:"tls"`
Insecure bool `yaml:"insecure"`
// Tokens are who may use the API. None on a loopback address lets
// anyone of the machine use it.
Tokens []TokenConfig `yaml:"tokens"`
Printers map[string]PrinterConfig `yaml:"printers"`
Queues map[string]QueueConfig `yaml:"queues"`
Retention RetentionConfig `yaml:"retention"`
Limits LimitsConfig `yaml:"limits"`
Fonts FontsConfig `yaml:"fonts"`
// TempDir holds documents while they arrive.
TempDir string `yaml:"temp-dir"`
// IPP shows the queues as IPP printers, which the systems add without
// a driver (IPP Everywhere, AirPrint, Mopria).
IPP *IPPConfig `yaml:"ipp"`
// Upstreams are the servers this one fetches jobs from, as a proxy
// of a branch (IPP INFRA): each into a queue of this server.
Upstreams map[string]UpstreamConfig `yaml:"upstreams"`
// contains filtered or unexported fields
}
Config is the configuration of a server, as its YAML file has it.
func LoadConfig ¶
LoadConfig reads a configuration file, with its secrets, and checks it.
func ParseConfig ¶
ParseConfig reads a configuration from YAML and checks it; paths are relative to the working directory.
type FontsConfig ¶
FontsConfig finds the fonts of documents that name them.
type IPPConfig ¶
type IPPConfig struct {
// Listen is the address: ":8631" by default.
Listen string `yaml:"listen"`
// Host is the name of the server in the printers' URIs, the
// certificate and DNS-SD: the machine's name, in .local, by default.
Host string `yaml:"host"`
// Auth is "none" (anyone of the network prints, under the
// requesting-user-name it gives) or "basic" (a token's name and
// secret): basic when there are tokens.
Auth string `yaml:"auth"`
// RequireTLS refuses ipp (HTTP 426): only ipps. It is so with basic.
RequireTLS bool `yaml:"require-tls"`
// TLS is the certificate of ipps; without it the server makes one,
// signed by itself, kept next to the spool (ipp-tls.pem).
TLS *TLSConfig `yaml:"tls"`
// Queues are the queues shown; all by default. Default is also shown
// at /ipp/print.
Queues []string `yaml:"queues"`
Default string `yaml:"default"`
// Location, Organization and OrganizationalUnit describe the
// printers (printer-location …), a queue's location over Location.
Location string `yaml:"location"`
Organization string `yaml:"organization"`
OrganizationalUnit string `yaml:"organizational-unit"`
// DNSSD advertises the printers on the local links (mDNS): true by
// default.
DNSSD *bool `yaml:"dns-sd"`
}
IPPConfig is the IPP server of the queues: a printer of each at /ipp/print/<queue>, ipp and ipps on one port, advertised with DNS-SD.
type LimitsConfig ¶
type LimitsConfig struct {
MaxDocument Size `yaml:"max-document"`
MaxJobs int `yaml:"max-jobs"`
MaxBytes Size `yaml:"max-bytes"`
MaxImpressions int `yaml:"max-impressions"`
Renders int `yaml:"renders"`
RetryFor Duration `yaml:"retry-for"`
// Uploads and Events bound the submissions and the event streams at
// once: 8 and 64 by default.
Uploads int `yaml:"uploads"`
Events int `yaml:"events"`
}
LimitsConfig bounds what the server takes.
type Options ¶
type Options struct {
// Converter converts the documents that are not .bdf; nil takes .bdf
// only.
Converter spool.Converter
// FontFS adds fonts to the configuration's.
FontFS fs.FS
// Log receives what happens; nothing by default.
Log *slog.Logger
// Grace is how long Serve lets the documents being sent finish when
// it stops: 30 seconds by default.
Grace time.Duration
// Now is the clock; time.Now by default.
Now func() time.Time
// IPPListener is the listener of the IPP server (Config.IPP) for
// Serve; nil listens on the configuration's address.
IPPListener net.Listener
}
Options are what a server takes besides its configuration.
type PrinterCheck ¶
type PrinterCheck struct {
Name string
// URL is the printer's, without a user and password.
URL string
Printer *ipp.Printer
Err error
}
PrinterCheck is what a printer of a configuration answered.
func CheckPrinters ¶
func CheckPrinters(ctx context.Context, cfg *Config) []PrinterCheck
CheckPrinters asks each printer of a configuration what it supports, without opening the spool. The certificate of an ipps printer is checked against its pinned fingerprint; one not pinned is taken as the first one seen (the fingerprints the spool recorded are not read).
type PrinterConfig ¶
type PrinterConfig struct {
// Proxy makes a printer that proxies of branches fetch the jobs of
// (IPP INFRA), with no URL: the bdf printd of a branch, behind a NAT,
// whose upstreams name the queue.
Proxy bool `yaml:"proxy"`
URL string `yaml:"url"`
// Format is ps or pdf for a printer of 9100 or LPD, or the language
// of a printer of labels, receipts or forms (zpl, sbpl, tpcl, escpos,
// escp) on any of them: a raw queue of CUPS too. Profile names its
// model (bdf print -profile list); the URL's lang, profile, dpi and
// width say the same of a raw printer.
Format string `yaml:"format"`
Profile string `yaml:"profile"`
PJL *bool `yaml:"pjl"`
Username string `yaml:"username"`
PasswordEnv string `yaml:"password-env"`
PasswordFile string `yaml:"password-file"`
// Fingerprint ("sha256:…") pins the certificate of an ipps printer;
// without it, the first certificate seen is recorded and kept.
Fingerprint string `yaml:"fingerprint"`
// Insecure takes any certificate.
Insecure bool `yaml:"insecure"`
}
PrinterConfig is a printer: its URL (ipp://, ipps://, http://, https://), its user and password when it asks for them, and the fingerprint of its certificate when it is pinned; or a printer of 9100 or LPD (socket://host:9100, lpd://host/queue), the format it takes (ps, the default, or pdf) and whether a PJL header goes before the document (by default, for PDF only).
type QueueConfig ¶
type QueueConfig struct {
Printers []string `yaml:"printers"`
Policy string `yaml:"policy"`
// Defaults are the ticket's defaults, with IPP's names (sides,
// print-color-mode, media …).
Defaults map[string]any `yaml:"defaults"`
Format string `yaml:"format"`
RasterIfLossy bool `yaml:"raster-if-lossy"`
MaxInflight int `yaml:"max-inflight"`
// Info and Location describe the queue as an IPP printer
// (printer-info, the name it is advertised with, and
// printer-location).
Info string `yaml:"info"`
Location string `yaml:"location"`
}
QueueConfig is a queue of printers.
type RetentionConfig ¶
type RetentionConfig struct {
Documents Duration `yaml:"documents"`
Records Duration `yaml:"records"`
}
RetentionConfig is how long what is done is kept ("168h", "7d").
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is a print server: a spool and its HTTP API.
func New ¶
New opens the spool of a configuration (spool.db, locked: a second server of the same file is refused) and makes the server. Serve starts it; Close closes a server that was not served.
func (*Server) Handler ¶
Handler is the server's HTTP handler: the API, /events, /metrics, /healthz and the page of the state.
func (*Server) IPPHandler ¶
IPPHandler is the handler of the IPP server (Config.IPP), nil without one: the printers at /ipp/print/<queue>, their icons and pages.
type TokenConfig ¶
type TokenConfig struct {
Name string `yaml:"name"`
File string `yaml:"file"`
Env string `yaml:"env"`
Value string `yaml:"value"`
Queues []string `yaml:"queues"`
Roles []string `yaml:"roles"`
// ActAs lets the token name the user of a job (X-BDF-User): an
// application that submits for its users.
ActAs bool `yaml:"act-as"`
// contains filtered or unexported fields
}
TokenConfig is a token: its name (the user of its jobs), its secret (from a file, the environment, or the value itself), the queues it may submit to (all when none), and its roles: submit, manage (others' jobs, accounting), admin (queues, discovery, backup).
type UpstreamConfig ¶
type UpstreamConfig struct {
URL string `yaml:"url"`
Queue string `yaml:"queue"`
Username string `yaml:"username"`
PasswordEnv string `yaml:"password-env"`
PasswordFile string `yaml:"password-file"`
Fingerprint string `yaml:"fingerprint"`
Insecure bool `yaml:"insecure"`
// Poll is how often the jobs are asked for: 10 seconds by default.
Poll Duration `yaml:"poll"`
// UUID is the output-device-uuid of this proxy; one made of the
// spool and the upstream's name by default.
UUID string `yaml:"uuid"`
}
UpstreamConfig is a server this one fetches jobs from: the URL of its queue (a queue of a printer of proxies there), the queue here the jobs go to, and the token's name and secret there (Basic).
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package client talks to a print server (bdf printd) over its HTTP API: it submits documents, follows and changes jobs, and reads the queues, the printers and the accounting.
|
Package client talks to a print server (bdf printd) over its HTTP API: it submits documents, follows and changes jobs, and reads the queues, the printers and the accounting. |