روش استفاده (Usage):

ipp-usb mode [options]

حالت‌ها (Modes):

standalone

اجرای دائمی، شناسایی خودکار دستگاه‌های IPP-over-USB و سرویس‌دهی به همه آن‌ها

udev

مشابه حالت مستقل (standalone)، اما پس از قطع اتصال آخرین دستگاه IPP-over-USB از برنامه خارج می‌شود

debug

لاگ‌ها روی کنسول نیز نمایش داده می‌شوند و گزینه -bg نادیده گرفته می‌شود

check

بررسی پیکربندی و خروج از برنامه. همچنین فهرستی از تمام دستگاه‌های متصل را چاپ می‌کند

status

چاپ وضعیت دیمن در حال اجرای ipp-usb، شامل اطلاعات تمام دستگاه‌های متصل

گزینه‌ها (Options):

• -bg
  اجرا در پس‌زمینه (در حالت اشکال‌زدایی debug نادیده گرفته می‌شود)
• -path-conf-files-srch dir1[:dir2...]
  فهرست دایرکتوری‌هایی که فایل‌های پیکربندی (ipp-usb.conf) در آن‌ها جستجو می‌شوند (/etc/ipp-usb)
• -path-log-dir dir
  مسیر دایرکتوری محل نوشتن فایل‌های لاگ (main.log و لاگ مخصوص هر دستگاه DEVICE.log) (/var/log/ipp-usb)
• -path-lock-file file
  مسیر فایل قفل برنامه (/var/ipp-usb/lock/ipp-usb.lock)
• -path-dev-state-dir dir
  مسیر دایرکتوری محل نوشتن فایل‌های وضعیت اختصاصی هر دستگاه (/var/ipp-usb/dev)
• -path-ctrl-sock file
  مسیر سوکت کنترلی برنامه (/var/ipp-usb/ctrl)
• -path-quirks-files-srch dir1[:dir2...]
  فهرست دایرکتوری‌هایی که فایل‌های رفتارهای خاص (*.conf) در آن‌ها جستجو می‌شوند (/etc/ipp-usb/quirks:/usr/share/ipp-usb/quirks)

پارامترهای شبکه (Network parameters)

پارامترهای شبکه همگی در بخش [network] قرار دارند:

[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

احراز هویت (Authentication)

به‌طور پیش‌فرض، ipp-usb چاپگر USB متصل‌شده به‌صورت محلی را در دسترس تمام کاربران سیستم قرار می‌دهد.

اگرچه این رفتار در بیشتر موارد که رایانه و چاپگر هر دو در استفاده شخصی هستند منطقی است، اما برای محیط‌های بزرگ‌تر این رویکرد می‌تواند بیش از حد ساده و ابتدایی باشد.

دیمن ipp-usb سازوکاری فراهم می‌کند که اجازه می‌دهد دسترسی کلاینت‌های محلی بر اساس شناسه کاربری (UID) که برنامه کلاینت تحت آن اجرا می‌شود، کنترل گردد.

لطفاً توجه داشته باشید، این سازوکار برای اتصال‌های از راه دور کار نخواهد کرد (به‌طور پیش‌فرض غیرفعال است اما پشتیبانی می‌شود). احراز هویت کاربران از راه دور نیازمند سازوکار متفاوتی است که در دست بررسی است اما هنوز پیاده‌سازی نشده است.

همچنین توجه داشته باشید، این سازوکار ممکن است در نصب‌های کانتینری (مانند snap، flatpak و موارد مشابه) کار کند یا نکند. فضای نام کانتینر ممکن است از فضاهای نام سیستم و/یا کاربر جدا شده باشد، بنابراین حتی برای کلاینت‌های محلی نیز UID دیده‌شده توسط ipp-usb ممکن است با UID در سطح سیستم متفاوت باشد.

پارامترهای احراز هویت همگی در بخش [auth uid] قرار دارند:

# Local user authentication by UID/GID
[auth uid]
  # Syntax:
  #     operations = users
  #
  # Operations are comma-separated list of following operations:
  #     all    - all operations
  #     config - configuration web-console
  #     fax    - faxing
  #     print  - printing
  #     scan   - scanning
  #
  # Users have the following suntax:
  #     user   - user name
  #     @group - all users that belongs to the group
  #
  # Users and groups may be specified either by names or by
  # numbers. "*" means any
  #
  # Note, if user/group is not known in the context of request
  # (for example, in the case of non-local network connection),
  # "*" used for matching, which will only match wildcard
  # rules.
  #
  # User/group names are resolved at the moment of request
  # processing (and cached for a couple of seconds), so running
  # daemon will see changes to the /etc/passwd and /etc/group
  #
  # Examples:
  #     fax, print = lp, @lp   # Allow CUPS to do its work
  #     scan       = *         # Allow any user to scan
  #     config     = @wheel    # Only wheel group members can do that
  all = *

پیکربندی لاگ‌گیری (Logging configuration)

پارامترهای لاگ‌گیری همگی در بخش [logging] قرار دارند:

[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
  # ipp-usb queries IPP printer attributes at the initialization time
  # for its own purposes and writes received attributes to the log.
  # By default, only necessary attributes are requested from device.
  #
  # If this parameter is set to true, all printer attributes will
  # be requested. Normally, it only affects the logging. However,
  # some enterprise-level HP printers returns such huge amount of
  # data and do it so slowly, so it can cause initialization timeout.
  # This is why this feature is not enabled by default
  get-all-printer-attrs = false # false | true

قلق‌ها و رفتارهای خاص (Quirks)

برخی دستگاه‌ها به دلیل اشکالات میان‌افزار (فِرم‌ور) خود، نیازمند رفتار ویژه‌ای هستند که به آن قلق‌های (quirks) خاص دستگاه گفته می‌شود. ipp-usb این قلق‌ها را از فایل‌های /usr/share/ipp-usb/quirks/*.conf و فایل‌های /etc/ipp-usb/quirks/*.conf بارگذاری می‌کند. دایرکتوری /etc/ipp-usb/quirks برای بازنویسی قلق‌های سیستم یا تغییرات اعمال‌شده توسط مدیر سیستم است. این فایل‌ها ساختار فایل‌های .INI را دارند و محتوای آن‌ها به این صورت است:

# Various HP printers - match by bame
[HP LaserJet MFP M28-M31]
  http-connection = keep-alive
[HP OfficeJet Pro 8730]
  http-connection = close
[HP Inc. HP Laser MFP 135a]
  blacklist = true
# Xerox B210. Match by HWID, as model name is not reliable
# before reset.
[0924:42ea]
  mfg        = Xerox
  model      = B210
  init-reset = hard
# Default configuration
[*]
  http-connection = ""

نام بخش، دستگاه (یا گروهی از دستگاه‌ها) را که قلق‌ها بر آن اعمال می‌شوند مشخص می‌کند، و بدنه بخش حاوی قلق‌های اعمال‌شده است.

برای هر دستگاه کشف‌شده، قلق‌ها بر اساس شناسه سخت‌افزاری USB HWID (به‌صورت Vendor:Product در مبنای شانزده) و بر اساس نام مدل جستجو می‌شوند.

نام‌های بخش می‌توانند حاوی نویسه‌های عام (wildcard) باشند:

`[HP OfficeJet Pro 8730]` - match the "HP OfficeJet Pro 8730" device
`[HP OfficeJet *]`        - match all models with name started with
                            the "HP OfficeJet" prefix.
`[0924:42ea]`             - match the device with the USB HWID 0924:42ea
`[0924:*]`                - match all devices with the Vendor ID equal
                            to 0924 (this ID owned by Xerox).

نام‌های مدل می‌توانند حاوی نویسه‌های الگوی تطبیق (glob) باشند: * که با هر توالی از نویسه‌ها تطبیق می‌یابد و ? که با هر تک‌نویسه مطابقت دارد. برای تطبیق مستقیم یکی از این نویسه‌ها (* و ?) به‌صورت دقیق، از بک‌اسلش برای اسکیپ کردن استفاده کنید.

بخش‌های HWID تنها می‌توانند حاوی نویسه عام * به جای شناسه محصول (Product ID) باشند.

توجه داشته باشید، ساده‌ترین روش برای حدس زدن نام دقیق مدل یک دستگاه خاص، استفاده از دستور ipp-usb check است که فهرستی از تمام دستگاه‌های متصل را چاپ می‌کند. برای به‌دست آوردن فهرست HWIDهای USB، از دستور lsusb استفاده کنید.

اگر پارامتری در چندین بخش تطبیق‌یافته پیدا شود، ipp-usb از این اصل پیروی می‌کند: دقیق‌ترین تطبیق برنده است.

برای دقیق‌تر بودن، از الگوریتم اولویت‌بندی زیر استفاده می‌شود:

• شناسه دقیق HWID (بدون نویسه عام، مانند [0924:42ea]) دقیق‌ترین حالت در نظر گرفته می‌شود.
• نامزدهای بعدی، تطبیق نام مدل با دست‌کم یک نویسه تطبیق‌یافته غیرعام هستند. در صورت وجود چندین تطبیق برای نام مدل، تعداد نویسه‌های تطبیق‌یافته غیرعام شمرده می‌شود و تطبیق طولانی‌تر برنده است.
• نامزد بعدی، تطبیق HWID دارای نویسه عام است (مانند [0924:*]).
• و کمترین اولویت متعلق به تطبیق نام مدل با تمام نویسه عام است (مانند [*]).

در صورت تطبیق‌های چندگانه حتی پس از اعمال این الگوریتم، نخستین تعریف برنده خواهد بود. فایل‌ها به ترتیب الفبایی بارگذاری شده و بخش‌ها به‌صورت متوالی خوانده می‌شوند.

به بیان دیگر، تطبیق HWID بدون نویسه عام دقیق‌ترین حالت در نظر گرفته می‌شود، تطبیق‌های نام مدل بر اساس تعداد نویسه‌های تطبیق‌یافته غیرعام رتبه‌بندی می‌شوند، تطبیق HWID با نویسه عام اولویت کمتری نسبت به موارد بالا دارد زیرا تنها می‌تواند برای تمام دستگاه‌های یک سازنده خاص اعمال شود، و کمترین اولویت متعلق به تطبیق نام مدل با تمام نویسه عام است که برای تعیین مقادیر پیش‌فرض به کار می‌رود.

لطفاً توجه داشته باشید که قلق‌های تطبیق‌یافته بر اساس HWID زودتر بارگذاری می‌شوند و ممکن است باعث شوند برخی اقدامات پیش از بارگذاری و اعمال قلق‌های منطبق با نام مدل انجام گیرند، و قلق‌های منطبق بر نام مدل نمی‌توانند این اقدامات زودهنگام را لغو کنند. این موضوع به این دلیل رخ می‌دهد که برخی چاپگرها پیش از اعمال اقدامات مناسب نمی‌توانند نام مدل خود را به‌طور قابل اطمینانی گزارش دهند. این امر به قلق‌های زیر مربوط می‌شود:

• blacklist = true. اگر دستگاه بر اساس HWID در لیست سیاه قرار گیرد، قلق‌های نام مدل بارگذاری نخواهند شد.
• init-reset = hard. بازنشانی انجام خواهد شد، حتی اگر قلق منطبق بر نام مدل تنظیم متفاوتی داشته باشد.
• mfg = name و model = name. این پارامترها تنها برای قلق‌های HWID در دسترس هستند و اطلاعات هویتی ارائه‌شده توسط دستگاه را هنگام جستجوی قلق‌ها بر اساس نام مدل بازنویسی می‌کنند.

پارامترهای زیر تعریف شده‌اند:

• blacklist = true | false
  در صورت تنظیم روی true، دستگاه منطبق توسط ipp-usb نادیده گرفته می‌شود
• buggy-ipp-responses = reject | allow | sanitize
  برخی دستگاه‌ها پاسخ‌های IPP معیوب (ناقص) ارسال می‌کنند که ناقض مشخصات استاندارد IPP است. برنامه ipp-usb می‌تواند این پاسخ‌ها را رد کند (reject که باعث ناموفق شدن راه‌اندازی ipp-usb می‌شود)، آن‌ها را بپذیرد (allow که راه‌اندازی ipp-usb موفق خواهد بود، اما CUPS نیز باید آن‌ها را بپذیرد) یا آن‌ها را پالایش کند (sanitize که نقض‌های مشخصات IPP را برطرف می‌سازد).
• disable-fax = true | false
  در صورت تنظیم روی true، قابلیت فکس دستگاه منطبق نادیده گرفته می‌شود.
• disable-scan = true | false
  در صورت تنظیم روی true، قابلیت اسکن دستگاه منطبق نادیده گرفته می‌شود.
• http-XXX = YYY
  سرآیند XXX از درخواست‌های HTTP هدایت‌شده به دستگاه را روی مقدار YYY تنظیم می‌کند. اگر YYY رشته‌ای خالی باشد، سرآیند XXX حذف می‌شود.
• ignore-ipp-status = true | false
  در صورت تنظیم روی true، وضعیت IPP درخواست‌های ارسالی توسط خود ipp-usb نادیده گرفته می‌شود. این رفتار خاص زمانی مفید است که دستگاه درخواست IPP را به‌درستی مدیریت می‌کند اما وضعیت بازگردانده‌شده قابل اطمینان نیست. این گزینه تنها بر مرحله راه‌اندازی ipp-usb تأثیر می‌گذارد.
• init-delay = DELAY
  تأخیر میان باز شدن دستگاه (و در صورت تمایل، بازنشانی آن) و ارسال اولین درخواست به دستگاه.
• init-retry-partial = true | false
  در صورتی که تنها بخشی از عملکردهای دستگاه راه‌اندازی شده باشند، تلاش مجدد برای راه‌اندازی انجام می‌شود؛ به‌جای آنکه برنامه با عملکردهای ناقص به کار خود ادامه دهد.

این گزینه زمانی می‌تواند مفید باشد که راه‌اندازی کامل دستگاه زمان زیادی ببرد. در طول این مدت، ممکن است برخی بخش‌ها به‌طور عادی پاسخ دهند در حالی که بخش‌های دیگر هنوز در حال راه‌اندازی هستند. برای نمونه، دستگاه ممکن است بلافاصله پس از روشن شدن قابلیت‌های اسکن خود را گزارش کند، در حالی که عملکرد چاپ آن چند دقیقه طول بکشد تا آماده به کار شود.

مشخص شده است که برخی از چاپگرهای سازمانی HP این مشکل را دارند.

• init-reset = none | soft | hard
  نحوه بازنشانی دستگاه در زمان راه‌اندازی اولیه. مقدار پیش‌فرض none است
• init-timeout = DELAY
  مهلت زمانی (تایم‌اوت) برای درخواست‌های HTTP ارسالی توسط ipp-usb در طول راه‌اندازی اولیه.
• mfg = name
  نام سازنده (تولیدکننده) USB را بازنویسی می‌کند. این رفتار خاص تنها می‌تواند در بخش HWID استفاده شود و بر جستجوی رفتارهای خاص بر اساس نام مدل تأثیر می‌گذارد.
• model = name
  نام مدل (محصول) USB را بازنویسی می‌کند. این رفتار خاص تنها می‌تواند در بخش HWID استفاده شود و بر جستجوی رفتارهای خاص بر اساس نام مدل تأثیر می‌گذارد.
• request-delay = DELAY
  تأخیر بین درخواست‌های متوالی HTTP ارسالی به دستگاه (این با usb-send-delay یکسان نیست، چرا که گزینه دوم بین هر یک از درخواست‌های متوالی ارسال به دستگاه از طریق USB تأخیر ایجاد می‌کند).
• usb-max-interfaces = N
  حتی اگر رابط‌های بیشتری در دسترس باشد، بیشتر از N رابط USB استفاده نشود.
• usb-send-delay = DELAY
  تأخیر میان درخواست‌های سطح پایین ارسال به دستگاه از طریق USB (این با request-delay که بین کل درخواست‌های سطح HTTP تأخیر می‌اندازد یکسان نیست).
• usb-send-delay-threshold = N
  گزینه usb-send-delay تنها در صورتی اعمال می‌شود که اندازه درخواست ارسال به دستگاه از طریق USB از این آستانه فراتر رود.
• zlp-recv-hack = true | false
  برخی دستگاه‌های سازمانی HP در مرحله راه‌اندازی اولیه (که می‌تواند چندین دقیقه طول بکشد) ممکن است با وضعیت HTTP 503 یا مشابه آن پاسخ دهند، که این مورد قابل انتظار است. با این حال، بدنه پاسخ ممکن است ناقص (بریده‌شده) باشد (به‌طور معمول، نویسه پایان‌دهنده '\n' گم می‌شود). در چنین مواردی، ipp-usb برای حفظ همگام‌سازی با دستگاه به‌طور نامحدود منتظر دریافت پاسخ می‌ماند.

در همین حال، این دستگاه‌ها در پایان خروجی ناقص یک بسته UDP با طول صفر ارسال می‌کنند. اگر گزینه zlp-recv-hack فعال باشد، هنگامی که ipp-usb بسته‌ای با طول صفر از طریق USB دریافت می‌کند و به دنبال آن مهلت زمانی دریافت فرا می‌رسد، این ترکیب از رویدادها را به‌عنوان پایان معتبر بدنه پاسخ تفسیر می‌کند. این مورد تنها در زمان راه‌اندازی اولیه عمل می‌کند و بر عملیات‌های بعدی تأثیری ندارد.

•

zlp-send = true | false
انتقال‌های خروجی را که مضربی از اندازه بسته نقطه پایانی (endpoint) هستند با یک بسته اضافی با طول صفر خاتمه می‌دهد.

پارامتر DELAY می‌تواند یا به‌صورت یک عدد صحیح بدون علامت (به میلی‌ثانیه) یا به‌صورت دنباله‌ای از اعداد اعشاری با بخش کسری اختیاری و پسوند واحد مشخص شود، مانند "300ms"، "0.5s" یا "2m30s". واحدهای زمانی معتبر عبارتند از "ns"، "us" (یا "µs")، "ms"، "s"، "m" و "h".

اگر درباره دستگاه خود متوجه شدید که برای کارکرد درست نیازمند یک رفتار خاص است یا اصلاً با ipp-usb کار نمی‌کند اگرچه رابط IPP-over-USB را ارائه می‌دهد، لطفاً این مشکل را در https://github.com/OpenPrinting/ipp-usb گزارش دهید. این کار به ما امکان می‌دهد مجموعه رفتارهای خاص خود را به‌روزرسانی کنیم و به سایر دارندگان چنین دستگاهی کمک نماییم.