{"id":19218881,"url":"https://github.com/openprinting/cups-browsed","last_synced_at":"2025-09-02T15:39:26.092Z","repository":{"id":65875721,"uuid":"566990427","full_name":"OpenPrinting/cups-browsed","owner":"OpenPrinting","description":null,"archived":false,"fork":false,"pushed_at":"2024-10-31T14:29:28.000Z","size":228262,"stargazers_count":35,"open_issues_count":11,"forks_count":10,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-10-31T15:30:50.729Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OpenPrinting.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES-1.x.md","contributing":"CONTRIBUTING.md","funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-11-16T20:54:57.000Z","updated_at":"2024-10-31T14:29:59.000Z","dependencies_parsed_at":"2023-12-06T01:30:31.630Z","dependency_job_id":"4bd9c4c9-6829-46b9-be6f-996395831157","html_url":"https://github.com/OpenPrinting/cups-browsed","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenPrinting%2Fcups-browsed","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenPrinting%2Fcups-browsed/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenPrinting%2Fcups-browsed/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenPrinting%2Fcups-browsed/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenPrinting","download_url":"https://codeload.github.com/OpenPrinting/cups-browsed/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223838266,"owners_count":17211693,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T14:28:36.499Z","updated_at":"2025-04-15T21:07:35.381Z","avatar_url":"https://github.com/OpenPrinting.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenPrinting cups-browsed v2.1.1 - 2025-01-08\n\nLooking for compile instructions?  Read the file \"INSTALL\"\ninstead...\n\n\n## INTRODUCTION\n\nCUPS is a standards-based, open-source printing system used by\nApple's Mac OS® and other UNIX®-like operating systems,\nespecially also Linux. CUPS uses the Internet Printing Protocol\n(\"IPP\") and provides System V and Berkeley command-line\ninterfaces, a web interface, and a C API to manage printers and\nprint jobs.\n\nThis package contains cups-browsed, a helper daemon to browse the\nnetwork for remote CUPS queues and IPP network printers and\nautomatically create local queues pointing to them.\n\ncups-browsed has the following functionality:\n\n- Auto-discover print services advertised via DNS-SD (network\n  printers, IPP-over-USB printers, Printer Applications, remote CUPS\n  queues) and create local queues pointing to them. CUPS usually\n  automatically creates temporary queues for such print services, but\n  several print dialogs use old CUPS APIs and therefore require\n  permanent local queues to see such printers.\n\n- Creating printer clusters where jobs are printed to one single queue\n  and get automatically passed on to a suitable member printer.\n  \n  + Manual (via config file) and automatic (equally-named remote CUPS\n    printers form local cluster, as in legacy CUPS 1.5.x and older)\n    creation of cluster queues\n\n  + If member printers are different models/types, the local queue\n    gets the totality of all their features, options, and choices. Job\n    goes to printer which actually supports the user-selected job\n    settings. So in a cluster of photo printer, fast laser, and large\n    format selecting photo paper for example makes the job go to the\n    photo printer, duplex makes it go to the laser, A2 paper to the\n    large format ... So user has one queue for all printers, they\n    select features, not printers for their jobs ...\n\n  + Automatic selection of destination printer depending on job option\n    settings\n\n  + Load balancing on equally suitable printers\n\n  + `implicitclass` backend holds the job, waits for instructions\n    about the destination printer of cups-browsed, converts the (PDF)\n    job to one of the destination's (driverless) input formats, and\n    passes on the job.\n\n- Highly configurable: Which printers are considered? For which type\n  of printers queues are created? Cluster types and member printers?\n  which names auto-created queues should get? DNS-SD and/or\n  BrowsePoll? ...\n\n- Multi-threading allows several tasks to be done in parallel and\n  assures responsiveness of the daemon when there is a large amount of\n  printers available in the network.\n\nFor compiling and using this package CUPS (2.2.2 or newer),\nlibcupsfilters 2.x, libppd, libavahi-common, libavahi-client, libdbus,\nand glib are needed.\n\nIt also needs gcc (C compiler), automake, autoconf, autopoint, and\nlibtool. On Debian, Ubuntu, and distributions derived from them you\ncould also install the \"build-essential\" package to auto-install most\nof these packages.\n\nReport bugs to [GitHub Issues for cups-browsed](https://github.com/OpenPrinting/cups-browsed/issues)\n\nSee the \"COPYING\", \"LICENCE\", and \"NOTICE\" files for legal\ninformation. The license is the same as for CUPS, for a maximum of\ncompatibility.\n\n## LINKS\n\n* [Short history of cups-browsed](https://openprinting.github.io/achievements/#cups-browsed)\n\n## TEST SUITE\n\nThe script test/run-tests.sh creates emulations of IPP printers via\n\"ippeveprinter\" (of CUPS 2.x) and checks whether cups-browsed creates\ncorresponding CUPS queues, whether a job to such a queue gets actually\nprinted, and whether cups-browsed removes the queues again when the\nprinters are shut down.\n\nSIDE EFFECT: By developing this script cups-browsed got tested running\nas non-root user (only needs to be member of the \"lpadmin\" group) and\nworks properly this way. Appropriate distribution packaging is\nrecommended to improve system security.\n\nREQUIREMENTS:\n\nMost of these are already needed for building or using cups-browsed.\n\n- CUPS 2.x must be installed: cupsd, lpstat, lp, ippevepriner,\n  cups-config, and everything needed to run cupsd.\n\n- cups-filters 2.x needs to be installed, providing the filters for\n  processing print jobs and the \"driverless\" utility to discover\n  printers via shell script.\n\n- cups-browsed 2.x needs to be installed for test mode 3 or for\n  running the script as root.\n\nThe script has different modes:\n\n- Run without arguments by \"make\" it goes into \"make check\" mode,\n  copying the files of the system's CUPS (to pull it out of the\n  distro's AppArmor harness of the distro, run it as normal\n  user, and modify the configuration) to run an own CUPS instance\n  on port 8631, and running the cups-browsed executable built\n  by \"make\", attached to this CUPS instance.\n\n- Run without arguments directly it asks the use for the test mode\n  and whether tey want to run the daemons under Valgrind. Modes are\n\n  + 0: Only start cupsd and cups-browsed, for manual testing\n    independent of the system's environment\n  + 1: As 0, but also run the 2 ippeveprinter instances to emulate\n    printers\n  + 2: Run the \"make check\" mode described above.\n  + 3: Do the same tests as in \"make check\" mode, but use the system's\n    CUPS and cups-browsed. This mode is for the autopkgtest of Debian\n    and Ubuntu, or for CI tests in general.\n\n- Run with a number (0-3) as argument the appropriate mode is selected,\n  run with a number (0-3) as first and \"yes\" or \"no\" as second argument\n  using or not using Valgrind is also selected.\n\n- Running the script as root always uses the system's CUPS and\n  cups-browsed.\n\nThe test's CUPS instance and all log files are held in\n/tmp/cups-browsed${USER}/.\n\n## DOCUMENTATION FROM CUPS-FILTERS 1.x\n\nMost of this is still valid for the current cups-browsed.\n\n### HELPER DAEMON FOR BROWSING REMOTE CUPS PRINTERS AND IPP NETWORK PRINTERS\n\nFrom version 1.6.0 on in CUPS the CUPS broadcasting/browsing\nfacility was dropped, in favour of DNS-SD-based broadcasting of\nshared printers. This is done as DNS-SD broadcasting of shared\nprinters is a standard, established by the PWG (Printing Working\nGroup, http://www.pwg.org/), and most other network services\n(shared file systems, shared media files/streams, remote desktop\nservices, ...) are also broadcasted via DNS-SD.\n\nProblem is that CUPS only broadcasts its shared printers but does\nnot browse broadcasts of other CUPS servers to make the shared\nremote printers available locally without any configuration\nefforts. This is a regression compared to the old CUPS\nbroadcasting/browsing. The intention of CUPS upstream is that the\napplication's print dialogs browse the DNS-SD broadcasts as an\nAirPrint-capable iPhone does, but it will take its time until all\ntoolkit developers add the needed functionality, and programs\nusing old toolkits or no toolkits at all, or the command line stay\nuncovered.\n\nThe solution is cups-browsed, a helper daemon running in parallel to\nthe CUPS daemon which listens to DNS-SD broadcasts of shared CUPS\nprinters on remote machines in the local network via Avahi. For each\nreported remote printer it creates a local raw queue pointing to the\nremote printer so that the printer appears in local print dialogs and\nis also available for printing via the command line. As with the\nformer CUPS broadcasting/browsing with this queue the driver on the\nserver is used and the local print dialogs give access to all options\nof the server-side printer driver.\n\nAlso high availability with redundant print servers and load\nbalancing is supported. If there is more than one server providing\na shared print queue with the same name, cups-browsed forms a\ncluster locally with this name as queue name and printing through\nthe \"implicitclass\" backend. Each job triggers cups-browsed to\ncheck which remote queue is suitable for the job, meaning that it\nis enabled, accepts jobs, and is not currently printing.  If none\nof the remote queues fulfills these criteria, we check again in 5\nseconds, until a printer gets free to accommodate the job. When we\nsearch for a free printer, we do not start at the first in the\nlist, but always on the one after the last one used (as CUPS also\ndoes with classes), so that all printer get used, even if the\nfrequency of jobs is low. This is also what CUPS formerly did with\nimplicit classes. Optionally, jobs can be sent immediately into\nthe remote queue with the lowest number of waiting jobs, so that\nno local queue of waiting jobs is built up.\n\nFor maximum security cups-browsed uses IPPS (encrypted IPP)\nwhenever possible.\n\nIn addition, cups-browsed is also capable of discovering IPP\nnetwork printers (native printers, not CUPS queues) with known\npage description languages (PWG Raster, Apple Raster, PDF,\nPostScript, PCL XL, PCL 5c/e) in the local network and auto-create\nprint queues with auto-created PPD files. This functionality is\nprimarily for mobile devices running CUPS to not need a printer\nsetup tool nor a collection of printer drivers and PPDs.\n\ncups-browsed can also be started on-demand, for example to save\nresources on mobile devices. For this, cups-browsed can be set\ninto an auto shutdown mode so that it stops automatically when it\nhas no remote printers to take care of any more, especially if an\non-demand running avahi-daemon stops. Note that CUPS must stay\nrunning for cups-browsed removing its queues and so being able to\nshut down. Ideal is if CUPS stays running another 30 seconds after\nfinishing its last job so that cups-browsed can take down the\nqueue. For how to set up and control this mode via command line,\nconfiguration directives, or sending signals see the man pages\ncups-browsed(8) and cups-browsed.conf(5).\n\nThe configuration file for cups-browsed is\n/etc/cups/cups-browsed.conf.  This file can include limited forms\nof the original CUPS BrowseRemoteProtocols, BrowseLocalProtocols,\nBrowsePoll, and BrowseAllow directives. It also can contain the\nnew CreateIPPPrinterQueues to activate discovering of IPP network\nprinters and creating PPD-less queues for them.\n\nNote that cups-browsed does not work with remote CUPS servers\nspecified by a client.conf file. It always connects to the local\nCUPS daemon by setting the CUPS_SERVER environment variable and so\noverriding client.conf. If your local CUPS daemon uses a\nnon-standard domain socket as only way of access, you need to\nspecify it via the DomainSocket directive in\n/etc/cups/cups-browsed.conf.\n\nThe \"make install\" process installs init scripts which make the\ndaemon automatically started during boot. You can also manually\nstart it with (as root):\n\n    /usr/sbin/cups-browsed \u0026\n\nor in debug mode with\n\n    /usr/sbin/cups-browsed --debug\n\nShut it down by sending signal 2 (SIGINT) or 15 (SIGTERM) to\nit. The queues which it has created get removed then (except a\nqueue set as system default, to not loose its system default\nstate).\n\nOn systems using systemd use a\n/usr/lib/systemd/system/cups-browsed.service file like this:\n\n    [Unit]\n    Description=Make remote CUPS printers available locally\n    After=cups.service avahi-daemon.service\n    Wants=cups.service avahi-daemon.service\n\n    [Service]\n    ExecStart=/usr/sbin/cups-browsed\n\n    [Install]\n    WantedBy=multi-user.target\n\nOn systems using Upstart use an /etc/init/cups-browsed.conf file like this:\n\n    start on (filesystem\n              and (started cups or runlevel [2345]))\n    stop on runlevel [016]\n\n    respawn\n    respawn limit 3 240\n\n    pre-start script\n        [ -x /usr/sbin/cups-browsed ]\n    end script\n\n    exec /usr/sbin/cups-browsed\n\nThese files are included in the source distribution as\nutils/cups-browsed.service and utils/cups-browsed-upstart.conf.\n\nIn the examples we start cups-browsed after starting\navahi-daemon. This is not required. If cups-browsed starts first,\nthen Bonjour/DNS-SD browsing kicks in as soon as avahi-daemon comes\nup. cups-browsed is also robust against any shutdown and restart\nof avahi-daemon.\n\nHere is some info on how cups-browsed works internally (first concept of a\ndaemon which does only DNS-SD browsing):\n\n    - Daemon start\n      o Wait for CUPS daemon if it is not running\n      o Read out all CUPS queues created by this daemon (in former sessions)\n      o Mark them unconfirmed and set timeout 10 sec from now\n    - Main loop (use avahi_simple_poll_iterate() to do queue list maintenance\n                 regularly)\n      o Event: New printer shows up\n        + Queue for printer is already created by this daemon -\u003e Mark list\n          entry confirmed, if discovered printer is ipps but existing queue ipp,\n\t  upgrade existing queue by setting URI to ipps. Set status to\n\t  to-be-created and timeout to now-1 sec to make the CUPS queue be\n\t  updated.\n        + Queue does not yet exist -\u003e Mark as to-be-created and set\n\t  timeout to now-1 sec.\n      o Event: A printer disappears\n        + If we have listed a queue for it, mark the entry as disappeared, set\n          timeout to now-1 sec\n      o On any of the above events and every 2 sec\n        + Check through list of our listed queues\n          - If queue is unconfirmed and timeout has passed, mark it as\n            disappeared, set timeout to now-1 sec\n          - If queue is marked disappered and timeout has passed, check whether\n\t    there are still jobs in it, if yes, set timeout to 10 sec from now,\n\t    if no, remove the CUPS queue and the queue entry in our list. If\n\t    removal fails, set timeout to 10 sec.\n\t  - If queue is to-be-created, create it, if succeeded set to\n\t    confirmed, if not, set timeout to 10 sec fron now. printer-is-shared\n\t    must be set to false.\n    - Daemon shutdown\n      o Remove all CUPS queues in our list, as long as they do not have jobs.\n\nDo not overwrite existing queues which are not created by us If\nthe simple \u003cremote_printer\u003e name is already taken, try to create a\n\u003cremote_printer\u003e@\u003cserver\u003e name, if this is also taken, ignore the\nremote printer. Do not retry, to avoid polling CUPS all the time.\n\nDo not remove queues which are not created by us. We do this by\nlisting only our queues and remove only listed queues.\n\nQueue names: Use the name of the remote queue. If a queue with the\nsame name from another server already exists, mark the new queue\nas duplicate and when a queue disappears, check whether it has\nduplicates and change the URI of the disappeared queue to the URI\nof the first duplicate, mark the queue as to-be-created with\ntimeout now-1 sec (to update the URI of the CUPS queue) and mark\nthe duplicate disappeared with timeout now-1 sec. In terms of\nhigh availability we replace the old load balancing of the\nimplicit class by a failover solution. Alternatively (not\nimplemented), if queue with same name but from other server\nappears, create new queue as \u003coriginal name\u003e@\u003cserver name without\n.local\u003e. When queue with simple name is removed, replace the first\nof the others by one with simple name (mark old queue disappeared\nwith timeout now-1 sec and create new queue with simple name).\n\nFill description of the created CUPS queue with the DNS-SD\nservice name (= original description) and location with the server\nname without .local.\n\nstderr messages only in debug mode (command line options:\n\"--debug\" or \"-d\" or \"-v\").\n\nQueue identified as from this daemon by doing the equivalent of\n\"lpadmin -p printer -o cups-browsed-default\", this generates a\n\"cups-browsed\" attribute in printers.conf with value \"true\".\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenprinting%2Fcups-browsed","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenprinting%2Fcups-browsed","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenprinting%2Fcups-browsed/lists"}