forked from OpenPrinting/ipp-usb
-
Notifications
You must be signed in to change notification settings - Fork 0
/
ipp-usb.8
167 lines (159 loc) · 6.58 KB
/
ipp-usb.8
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
.\" generated with Ronn-NG/v0.9.1
.\" http://github.com/apjanke/ronn-ng/tree/0.9.1
.TH "IPP\-USB" "8" "March 2022" "" "ipp-usb.8"
.SH "NAME"
\fBipp\-usb\fR \- Daemon for IPP over USB printer support
.SH "DESCRIPTION"
\fBipp\-usb\fR daemon enables driver\-less printing and scanning on USB\-only AirPrint\-compatible printers and MFPs\.
.P
It works by connecting to the device by USB using IPP\-over\-USB protocol, and exposing the device to the network, including DNS\-SD (ZeroConf) advertising\.
.P
IPP printing, eSCL scanning and web console are fully supported\.
.SH "SYNOPSIS"
.SS "Usage:"
\fBipp\-usb mode [options]\fR
.SS "Modes are:"
.TP
\fBstandalone\fR
run forever, automatically discover IPP\-over\-USB devices and serve them all
.TP
\fBudev\fR
like standalone, but exit when last IPP\-over\-USB device is disconnected
.TP
\fBdebug\fR
logs duplicated on console, \-bg option is ignored
.TP
\fBcheck\fR
check configuration and exit
.SS "Options are"
.TP
\fB\-bg\fR
run in background (ignored in debug mode)
.SH "CONFIGURATION"
\fBipp\-usb\fR searched for its configuration file in two places: 1\. \fB/etc/ipp\-usb/ipp\-usb\.conf\fR 2\. \fBipp\-usb\.conf\fR in the directory where executable file is located
.P
Configuration file syntax is very similar to \.INI files syntax\. It consist of named sections, and each section contains a set of named variables\. Comments are started from # or ; characters and continues until end of line:
.IP "" 4
.nf
# This is a comment
[section 1]
variable 1 = value 1 ; and another comment
variable 2 = value 2
.fi
.IP "" 0
.SS "Network parameters"
Network parameters are all in the \fB[network]\fR section:
.IP "" 4
.nf
[network]
# TCP ports for HTTP will be automatically allocated in the following range
http\-min\-port = 60000
http\-max\-port = 65535
# Enable or disable DNS\-SD advertisement
dns\-sd = enable # enable | disable
# Network interface to use\. Set to `all` if you want to expose you
# printer to the local network\. This way you can share your printer
# with other computers in the network, as well as with iOS and Android
# devices\.
interface = loopback # all | loopback
# Enable or disable IPv6
ipv6 = enable # enable | disable
.fi
.IP "" 0
.SS "Logging configuration"
Logging parameters are all in the \fB[logging]\fR section:
.IP "" 4
.nf
[logging]
# device\-log \- what logs are generated per device
# main\-log \- what common logs are generated
# console\-log \- what of generated logs goes to console
#
# parameter contains a comma\-separated list of
# the following keywords:
# error \- error messages
# info \- informative messages
# debug \- debug messages
# trace\-ipp, trace\-escl, trace\-http \- very detailed per\-protocol traces
# trace\-usb \- hex dump of all USB traffic
# all \- all logs
# trace\-all \- alias to all
#
# Note, trace\-* implies debug, debug implies info, info implies error
device\-log = all
main\-log = debug
console\-log = debug
# Log rotation parameters:
# log\-file\-size \- max log file before rotation\. Use suffix M
# for megabytes or K for kilobytes
# log\-backup\-files \- how many backup files to preserve during rotation
#
max\-file\-size = 256K
max\-backup\-files = 5
# Enable or disable ANSI colors on console
console\-color = enable # enable | disable
.fi
.IP "" 0
.SS "Quirks"
Some devices, due to their firmware bugs, require special handling, called device\-specific \fBquirks\fR\. \fBipp\-usb\fR loads quirks from the \fB/usr/share/ipp\-usb/quirks/*\.conf\fR files and from the \fB/etc/ipp\-usb/quirks/*\.conf\fR files\. The \fB/etc/ipp\-usb/quirks\fR directory is for system quirks overrides or admin changes\. These files have \.INI\-file syntax with the content that looks like this:
.IP "" 4
.nf
[HP LaserJet MFP M28\-M31]
http\-connection = keep\-alive
[HP OfficeJet Pro 8730]
http\-connection = close
[HP Inc\. HP Laser MFP 135a]
blacklist = true
# Default configuration
[*]
http\-connection = ""
.fi
.IP "" 0
.P
For each discovered device, its model name is matched against sections of the quirks files\. The section name contains an exact model name, which contains \fBiManufacturer\fR+\fBiProduct\fR entries from \fBlsusb \-v\fR command output, or it may contain glob\-style wildcards: \fB*\fR that matches any sequence of characters and \fB?\fR , that matches any single character\. To match one of these characters (\fB*\fR and \fB?\fR) literally, use backslash as escape\.
.P
All matching sections from all quirks files are taken in consideration, and applied in priority order\. Priority is computed using the following algorithm:
.IP "\[ci]" 4
When matching model name against section name, amount of non\-wildcard matched characters is counted, and the longer match wins
.IP "\[ci]" 4
Otherwise, section loaded first wins\. Files are loaded in alphabetical order, sections read sequentially
.IP "" 0
.P
If some parameter exist in multiple sections, used its value from the most priority section
.P
The following parameters are defined:
.TP
\fBblacklist = true | false\fR
If \fBtrue\fR, the matching device is ignored by the \fBipp\-usb\fR
.TP
\fBhttp\-XXX = YYY\fR
Set XXX header of the HTTP requests forwarded to device to YYY\. If YYY is empty string, XXX header is removed
.TP
\fBusb\-max\-interfaces = N\fR
Don\'t use more that N USB interfaces, even if more is available
.P
In case of you found out about your device needs a quirk to work properly or it does not work with \fBipp\-usb\fR at all, although it provides IPP\-over\-USB interface, please report the isues at https://github\.com/OpenPrinting/ipp\-usb\. The possible quirk for the device can be added to the project itself and fix the situation for all device\'s owners\.
.SH "FILES"
.IP "\[ci]" 4
\fB/etc/ipp\-usb/ipp\-usb\.conf\fR: the daemon configuration file
.IP "\[ci]" 4
\fB/var/log/ipp\-usb/main\.log\fR: the main log file
.IP "\[ci]" 4
\fB/var/log/ipp\-usb/<DEVICE>\.log\fR: per\-device log files
.IP "\[ci]" 4
\fB/var/ipp\-usb/dev/<DEVICE>\.state\fR: device state (HTTP port allocation, DNS\-SD name)
.IP "\[ci]" 4
\fB/var/ipp\-usb/lock/ipp\-usb\.lock\fR: lock file, that helps to prevent multiple copies of daemon to run simultaneously
.IP "\[ci]" 4
\fB/usr/share/ipp\-usb/quirks/*\.conf\fR: device\-specific quirks (see above)
.IP "\[ci]" 4
\fB/etc/ipp\-usb/quirks/*\.conf\fR: device\-specific quirks defined by sysadmin (see above)
.IP "" 0
.SH "COPYRIGHT"
Copyright (c) by Alexander Pevzner (pzz@apevzner\.com)
.br
All rights reserved\.
.P
This program is licensed under 2\-Clause BSD license\. See LICENSE file for details\.
.SH "SEE ALSO"
cups(1)