Recommended way to manually add an undiscovered IPP printer in CUPS 3.x

Recommended way to manually add an undiscovered IPP printer in CUPS 3.x

[AbdElRahman Khalifa]

Hi everyone,

I'm working on the COSMIC printer setup application for CUPS 3.x.

I have a question about driverless IPP printers that are not
automatically discovered, for example, when DNS-SD/mDNS is disabled.

What is the recommended way for a desktop printer setup application to
allow users to add such a printer manually?

I'm looking for the intended approach in the CUPS 3.x architecture.

Thanks,
Abdelrahman Khalifa

Re: Recommended way to manually add an undiscovered IPP printer in CUPS 3.x

[Michael Sweet]

Abdelrahman,

For CUPS 2.x you'll use the "everywhere" model ("ppd-name" attribute passed with 'everywhere' value) with an "ipp:" or "ipps:" device URI.  If the user doesn't have the full URI (typically "ipps://hostname/ipp/print" these days) then you can send a Get-Printer-Attributes request to the "/" resource to try to get back the correct URI for the printer (returned in the "printer-uri-supported" attribute).


> On Aug 1, 2026, at 12:44 PM, AbdElRahman Khalifa <abdelrahman.5alifa@gmail.com> wrote:
> 
> Hi everyone,
> 
> I'm working on the COSMIC printer setup application for CUPS 3.x.
> 
> I have a question about driverless IPP printers that are not
> automatically discovered, for example, when DNS-SD/mDNS is disabled.
> 
> What is the recommended way for a desktop printer setup application to
> allow users to add such a printer manually?
> 
> I'm looking for the intended approach in the CUPS 3.x architecture.
> 
> Thanks,
> Abdelrahman Khalifa
> 

________________________
Michael Sweet

Re: Recommended way to manually add an undiscovered IPP printer in CUPS 3.x

[Till Kamppeter]

Abdelrahman,

If there is no mDNS/DNS-SD active you can do:

1. Put an option into the "Add Printer" part where the user only enters the IP 
(or host name) of the printer. It could then try get-printer-attributes on
- ipps://IP:443/
- ipps://IP:631/
- ipp://IP:631/
- ipps://IP:8000/
- ipp://IP:8000/
- ipps://IP:8001/
- ipp://IP:8001/
- ...

Test 1 and 3 are for network printers, 2 and 3 for remote CUPS servers, 4+ for 
remote Printer Applications.

2. Also test
- ipp://localhost:60000/
- ipp://localhost:60001/
- ...
- ipps://localhost:8000/
- ipp://localhost:8000/
- ipps://localhost:8001/
- ipp://localhost:8001/
- ...

either automatically in the main view or  by button(s) in "Add Printer". This is 
for local IPP-over-USB printers and local Printer Applications.

I only do not know how to keep the found printers with CUPS 3.x.


Michael,

if discovering a printer by the above tests using the method you have described, 
one creates a queue with ipp: or ipps: and "-m everywhere" under CUPS 2.x.

But how to proceed under CUPS 3.x?

If I have only the local server, it is stateless, it only uses temporary queues. 
How do I, in case of not using mDNS/DNS-SD, tell my discoveries/manual IP 
selections to the local server so that it sticks with them? Or am I REQUIRED to 
use mDNS/DNS-SD when I have a system with only the local server of CUPS 3.x as 
print environment?

Or do I have to use the sharing server when I just want to print locally but not 
use mDNS/DNS-SD? Does the sharing server has a config file for holding such 
printers?

    Till


On 8/1/26 19:16, Michael Sweet wrote:
> Abdelrahman,
> 
> For CUPS 2.x you'll use the "everywhere" model ("ppd-name" attribute passed with 'everywhere' value) with an "ipp:" or "ipps:" device URI.  If the user doesn't have the full URI (typically "ipps://hostname/ipp/print" these days) then you can send a Get-Printer-Attributes request to the "/" resource to try to get back the correct URI for the printer (returned in the "printer-uri-supported" attribute).
> 
> 
>> On Aug 1, 2026, at 12:44 PM, AbdElRahman Khalifa <abdelrahman.5alifa@gmail.com> wrote:
>>
>> Hi everyone,
>>
>> I'm working on the COSMIC printer setup application for CUPS 3.x.
>>
>> I have a question about driverless IPP printers that are not
>> automatically discovered, for example, when DNS-SD/mDNS is disabled.
>>
>> What is the recommended way for a desktop printer setup application to
>> allow users to add such a printer manually?
>>
>> I'm looking for the intended approach in the CUPS 3.x architecture.
>>
>> Thanks,
>> Abdelrahman Khalifa
>>
> 
> ________________________
> Michael Sweet
> 
> 

Re: Recommended way to manually add an undiscovered IPP printer in CUPS 3.x

[Michael Sweet]

Till,

> On Aug 1, 2026, at 3:50 PM, Till Kamppeter <till.kamppeter@gmail.com> wrote:
> ...
> But how to proceed under CUPS 3.x?

CUPS 3.x uses PAPPL 2.x which has different operations and attribute names (as part of standardization in the PWG) but otherwise works similarly.

The Create-Printer operation accepts the "smi55357-device-uri (uri)" and "smi55357-driver (keyword)" operation attributes to provide the device URI and model/driver name, and cupslocald (from the cups-local project) supports the following driver names:

- 'everywhere': IPP Everywhere/AirPrint/Mopria/Wi-Fi Direct printer
- 'pcl': Generic B&W PCL printer
- 'pcl_duplex': Generic B&W PCL printer with 2-sided printing support
- 'ps': Generic B&W PostScript printer
- 'ps_duplex': Generic B&W PostScript printer with 2-sided printing support
- 'ps_color': Generic Color PostScript printer
- 'ps_color_duplex': Generic Color PostScript printer with 2-sided printing support

The PCL and PostScript drivers are extremely limited and are just there to support legacy Samba printing basic support for local (typically enterprise) laser printers.

> If I have only the local server, it is stateless, it only uses temporary queues.

It is not stateless.  It just doesn't have permanent queues and doesn't share local queues with other systems.

> How do I, in case of not using mDNS/DNS-SD, tell my discoveries/manual IP selections to the local server so that it sticks with them? Or am I REQUIRED to use mDNS/DNS-SD when I have a system with only the local server of CUPS 3.x as print environment?

We have been talking about this ("printer profiles") for a very long time:

    https://github.com/OpenPrinting/cups-local/issues/2

> Or do I have to use the sharing server when I just want to print locally but not use mDNS/DNS-SD? Does the sharing server has a config file for holding such printers?

The sharing server is more of a traditional "all queues are permanent" service and saves the queue state/configuration across runs.

________________________
Michael Sweet

Re: Recommended way to manually add an undiscovered IPP printer in CUPS 3.x

[Till Kamppeter]

On 8/1/26 22:41, Michael Sweet wrote:
> Till,
> 
>> On Aug 1, 2026, at 3:50 PM, Till Kamppeter <till.kamppeter@gmail.com> wrote:
>> ...
>> But how to proceed under CUPS 3.x?
> 
> CUPS 3.x uses PAPPL 2.x which has different operations and attribute names (as part of standardization in the PWG) but otherwise works similarly.
> 
> The Create-Printer operation accepts the "smi55357-device-uri (uri)" and "smi55357-driver (keyword)" operation attributes to provide the device URI and model/driver name, and cupslocald (from the cups-local project) supports the following driver names:
> 
> - 'everywhere': IPP Everywhere/AirPrint/Mopria/Wi-Fi Direct printer
> - 'pcl': Generic B&W PCL printer
> - 'pcl_duplex': Generic B&W PCL printer with 2-sided printing support
> - 'ps': Generic B&W PostScript printer
> - 'ps_duplex': Generic B&W PostScript printer with 2-sided printing support
> - 'ps_color': Generic Color PostScript printer
> - 'ps_color_duplex': Generic Color PostScript printer with 2-sided printing support
> 
> The PCL and PostScript drivers are extremely limited and are just there to support legacy Samba printing basic support for local (typically enterprise) laser printers.
> 

So when I send a Create-Printer request to a CUPS 3.x daemon (both local and 
sharing) an entry in a profile (~/.cups/profiles/ or /etc/cups/profiles/*, 
latter only for sharing server) is created?

>> If I have only the local server, it is stateless, it only uses temporary queues.
> 
> It is not stateless.  It just doesn't have permanent queues and doesn't share local queues with other systems.
> 
>> How do I, in case of not using mDNS/DNS-SD, tell my discoveries/manual IP selections to the local server so that it sticks with them? Or am I REQUIRED to use mDNS/DNS-SD when I have a system with only the local server of CUPS 3.x as print environment?
> 
> We have been talking about this ("printer profiles") for a very long time:
> 
>      https://github.com/OpenPrinting/cups-local/issues/2
> 

OK, so they also work with the local server.

So this means that our printer setup tool which Abdelrahman is working on 
creates entries in the profile when manually adding print destinations, either 
if mDNS/DNS-SD is not used or when the printer is outside the local network 
(VLAN or so)?

OK, so we need to settle on a format for this file so that Abdelrahman can 
implement that.

>> Or do I have to use the sharing server when I just want to print locally but not use mDNS/DNS-SD? Does the sharing server has a config file for holding such printers?
> 
> The sharing server is more of a traditional "all queues are permanent" service and saves the queue state/configuration across runs.
>

Does the sharing server not get its queues the same way as the local one, both 
by discovering printers via mDNS/DNS-SD AND including destinations by entries in 
the profile (which can be system-wide now)? And it adds rules for how to share 
these printers also in the profile?

    Till

Re: Recommended way to manually add an undiscovered IPP printer in CUPS 3.x

[Till Kamppeter]

Abdelrahman,

I think now I see how the concept in CUPS 3.x is meant:

First, in "Add Printer" you do not only allow to look for legacy printers to 
assign Printer Applications to, but you also look for driverless network 
printers which are not visible due to mDNS/DNS-SD not running or the printer 
being in a network not being your local one.

So in "Add Printer" you give the options as I suggested before:

On 8/1/26 21:50, Till Kamppeter wrote:
> Abdelrahman,
> 
> If there is no mDNS/DNS-SD active you can do:
> 
> 1. Put an option into the "Add Printer" part where the user only enters the IP 
> (or host name) of the printer. It could then try get-printer-attributes on
> - ipps://IP:443/
> - ipps://IP:631/
> - ipp://IP:631/
> - ipps://IP:8000/
> - ipp://IP:8000/
> - ipps://IP:8001/
> - ipp://IP:8001/
> - ...
> 
> Test 1 and 3 are for network printers, 2 and 3 for remote CUPS servers, 4+ for 
> remote Printer Applications.
> 
> 2. Also test
> - ipp://localhost:60000/
> - ipp://localhost:60001/
> - ...
> - ipps://localhost:8000/
> - ipp://localhost:8000/
> - ipps://localhost:8001/
> - ipp://localhost:8001/
> - ...
> 
> either automatically in the main view or  by button(s) in "Add Printer". This is 
> for local IPP-over-USB printers and local Printer Applications.
> 

You also give the option to select a network, to extend IPP printer discovery 
into that network. For example the user can add the corporate printer VLAN here.

Settings will be saved in profiles in ~/.cups/profiles/

You can also add a switch to "Add Printer" to make system-wide settings, then 
they get saved in /etc/cups/profiles/. Flicking this switch requires 
authentication for a root operation.

So you add to the "Add Printer" part a GUI frontend for defining profiles.

The profiles are NOT being used by the running CUPS daemon (local or sharing) 
but by the function in libcups (cupsEnumDests()) to list available print 
destinations. All print dialogs will have to use this function (if a dialog uses 
CPDB it will use this function).

So from Michael we need to know what the capabilities and the syntax of the 
files for profiles are.


Also, you can add "Set Option Defaults" buttons to all print destinations in the 
main view. This button is to be considered as a GUI frontend for the "lpoptions" 
command (or its libcups API equivalent, see source code of "lpoptions"). So 
settings get saved in ~/.cups/lpoptions (or with "system-wide" switch and 
authentication in /etc/cups/lpoptions). Note that these saved options do not 
require that the daemon has a permanent queue. They are only used by the client 
side (print dialogs of all portals and toolkits, CPDB, CLI tools).


Michael, am I right now?

    Till

Re: Recommended way to manually add an undiscovered IPP printer in CUPS 3.x

[Alexander Pevzner]

Till,

I think this is a bad idea for users to disable DNS-SD. It breaks not 
only printing, but driverless scanning as well.

Providing user a method to somehow workaround disabled DNS-SD just 
creates a wrong illusion that we somehow support this mode of operation.

That said, adding driverless printer manually still a useful option in 
case the printer is connected to the non-local LAN segment.

At this case it doesn't make a lot of sense to probe for the ipp-usb 
managed printers (which, BTW, may have assigned ports not only 60000 and 
60001, but any subsequent port as well),

Regarding normal hardware printers, are there really printers out of 
existence, that can respond IPP requests on alternative ports but 
doesn't respond on a standard port 631? If not, there is not a lot of 
sense to probe ports 8000, 8001 etc.

On 8/1/26 10:50 PM, Till Kamppeter wrote:
> Abdelrahman,
> 
> If there is no mDNS/DNS-SD active you can do:
> 
> 1. Put an option into the "Add Printer" part where the user only enters 
> the IP (or host name) of the printer. It could then try get-printer- 
> attributes on
> - ipps://IP:443/
> - ipps://IP:631/
> - ipp://IP:631/
> - ipps://IP:8000/
> - ipp://IP:8000/
> - ipps://IP:8001/
> - ipp://IP:8001/
> - ...
> 
> Test 1 and 3 are for network printers, 2 and 3 for remote CUPS servers, 
> 4+ for remote Printer Applications.
> 
> 2. Also test
> - ipp://localhost:60000/
> - ipp://localhost:60001/
> - ...
> - ipps://localhost:8000/
> - ipp://localhost:8000/
> - ipps://localhost:8001/
> - ipp://localhost:8001/
> - ...
> 
> either automatically in the main view or  by button(s) in "Add Printer". 
> This is for local IPP-over-USB printers and local Printer Applications.
> 
> I only do not know how to keep the found printers with CUPS 3.x.
> 
> 
> Michael,
> 
> if discovering a printer by the above tests using the method you have 
> described, one creates a queue with ipp: or ipps: and "-m everywhere" 
> under CUPS 2.x.
> 
> But how to proceed under CUPS 3.x?
> 
> If I have only the local server, it is stateless, it only uses temporary 
> queues. How do I, in case of not using mDNS/DNS-SD, tell my discoveries/ 
> manual IP selections to the local server so that it sticks with them? Or 
> am I REQUIRED to use mDNS/DNS-SD when I have a system with only the 
> local server of CUPS 3.x as print environment?
> 
> Or do I have to use the sharing server when I just want to print locally 
> but not use mDNS/DNS-SD? Does the sharing server has a config file for 
> holding such printers?
> 
>     Till
> 
> 
> On 8/1/26 19:16, Michael Sweet wrote:
>> Abdelrahman,
>>
>> For CUPS 2.x you'll use the "everywhere" model ("ppd-name" attribute 
>> passed with 'everywhere' value) with an "ipp:" or "ipps:" device URI.  
>> If the user doesn't have the full URI (typically "ipps://hostname/ipp/ 
>> print" these days) then you can send a Get-Printer-Attributes request 
>> to the "/" resource to try to get back the correct URI for the printer 
>> (returned in the "printer-uri-supported" attribute).
>>
>>
>>> On Aug 1, 2026, at 12:44 PM, AbdElRahman Khalifa 
>>> <abdelrahman.5alifa@gmail.com> wrote:
>>>
>>> Hi everyone,
>>>
>>> I'm working on the COSMIC printer setup application for CUPS 3.x.
>>>
>>> I have a question about driverless IPP printers that are not
>>> automatically discovered, for example, when DNS-SD/mDNS is disabled.
>>>
>>> What is the recommended way for a desktop printer setup application to
>>> allow users to add such a printer manually?
>>>
>>> I'm looking for the intended approach in the CUPS 3.x architecture.
>>>
>>> Thanks,
>>> Abdelrahman Khalifa
>>>
>>
>> ________________________
>> Michael Sweet
>>
>>
> 
> 


-- 

	Wishes, Alexander Pevzner (pzz@apevzner.com)

Re: Recommended way to manually add an undiscovered IPP printer in CUPS 3.x

[Michael Sweet]

Till,

> On Aug 1, 2026, at 5:21 PM, Till Kamppeter <till.kamppeter@gmail.com> wrote:
> 
> On 8/1/26 22:41, Michael Sweet wrote:
>> Till,
>>> On Aug 1, 2026, at 3:50 PM, Till Kamppeter <till.kamppeter@gmail.com> wrote:
>>> ...
>>> But how to proceed under CUPS 3.x?
>> CUPS 3.x uses PAPPL 2.x which has different operations and attribute names (as part of standardization in the PWG) but otherwise works similarly.
>> The Create-Printer operation accepts the "smi55357-device-uri (uri)" and "smi55357-driver (keyword)" operation attributes to provide the device URI and model/driver name, and cupslocald (from the cups-local project) supports the following driver names:
>> - 'everywhere': IPP Everywhere/AirPrint/Mopria/Wi-Fi Direct printer
>> - 'pcl': Generic B&W PCL printer
>> - 'pcl_duplex': Generic B&W PCL printer with 2-sided printing support
>> - 'ps': Generic B&W PostScript printer
>> - 'ps_duplex': Generic B&W PostScript printer with 2-sided printing support
>> - 'ps_color': Generic Color PostScript printer
>> - 'ps_color_duplex': Generic Color PostScript printer with 2-sided printing support
>> The PCL and PostScript drivers are extremely limited and are just there to support legacy Samba printing basic support for local (typically enterprise) laser printers.
> 
> So when I send a Create-Printer request to a CUPS 3.x daemon (both local and sharing) an entry in a profile (~/.cups/profiles/ or /etc/cups/profiles/*, latter only for sharing server) is created?

*No*.

Profiles are ONLY for the local server, and they are manually created by the user/admin.  Profiles in /etc/cups/profiles (or similar "world" directories apply to all users while profiles under $HOME apply to that user.  There is one cupslocald running per logged-in user on a system.

The goal is that cupslocald will only list those printers/servers that it can connect to, and will periodically update the list of available printers as conditions change (switching networks, printers/servers coming and going, etc.)

>>> If I have only the local server, it is stateless, it only uses temporary queues.
>> It is not stateless.  It just doesn't have permanent queues and doesn't share local queues with other systems.
>>> How do I, in case of not using mDNS/DNS-SD, tell my discoveries/manual IP selections to the local server so that it sticks with them? Or am I REQUIRED to use mDNS/DNS-SD when I have a system with only the local server of CUPS 3.x as print environment?
>> We have been talking about this ("printer profiles") for a very long time:
>>     https://github.com/OpenPrinting/cups-local/issues/2
> 
> OK, so they also work with the local server.

They *only* work with the local server.  The sharing server does NOT use profiles at all.

> So this means that our printer setup tool which Abdelrahman is working on creates entries in the profile when manually adding print destinations, either if mDNS/DNS-SD is not used or when the printer is outside the local network (VLAN or so)?

No, he should focus on adding printers to the sharing server.  Profiles are not intended as things that are created/edited with special tools, they are simple text files that replace DNS-SD discovery of IPP printers/servers.

> OK, so we need to settle on a format for this file so that Abdelrahman can implement that.

The proposed format is in the issue.

>>> Or do I have to use the sharing server when I just want to print locally but not use mDNS/DNS-SD? Does the sharing server has a config file for holding such printers?
>> The sharing server is more of a traditional "all queues are permanent" service and saves the queue state/configuration across runs.
>> 
> 
> Does the sharing server not get its queues the same way as the local one, both by discovering printers via mDNS/DNS-SD AND including destinations by entries in the profile (which can be system-wide now)? And it adds rules for how to share these printers also in the profile?

No, the sharing server is more akin to a regular printer application - yes, printers get discovered via standard means (DNS-SD, SNMP, USB, etc.) and you add the queues (discovered or manual entry) that you want to share.  Profiles are NOT used to configure the sharing server, although you might use a profile on a client system to point cupslocald at a sharing server.

________________________
Michael Sweet

Re: Recommended way to manually add an undiscovered IPP printer in CUPS 3.x

[Till Kamppeter]

On 8/2/26 00:46, Alexander Pevzner wrote:
> Till,
> 
> I think this is a bad idea for users to disable DNS-SD. It breaks not only 
> printing, but driverless scanning as well.
> 

There can be corporate settings with DNS-SD turned off.

> Providing user a method to somehow workaround disabled DNS-SD just creates a 
> wrong illusion that we somehow support this mode of operation.
> 

The printer setup tool needs to work for everybody, also those in said corporate 
environment. And if DNS-SD is on, the printers in the local network appear 
readily available in the main view. So the user sees their printer already and 
so does not click on "Add Printer".

Also, the printer setup tool know whether DNS-SD is on or off, and with DNS-SD 
on, the options not making sense in "Add Printer" then could not be shown, to 
simplify "Add Printer" for the users who have DNS-SD on.

> That said, adding driverless printer manually still a useful option in case the 
> printer is connected to the non-local LAN segment.
> 

Yes, this is important and "Add Printer" should always display this option.

> At this case it doesn't make a lot of sense to probe for the ipp-usb managed 
> printers (which, BTW, may have assigned ports not only 60000 and 60001, but any 
> subsequent port as well),
> 

Probing for IPP-over-USB printers I only intended for the case of DNS-SD off 
(and there check more ports, perhaps up to 60010).

> Regarding normal hardware printers, are there really printers out of existence, 
> that can respond IPP requests on alternative ports but doesn't respond on a 
> standard port 631? If not, there is not a lot of sense to probe ports 8000, 8001 
> etc.
> 

Port 8000+ is for Printer Applications, not for driverless hardware network 
printers.

    Till

Re: Recommended way to manually add an undiscovered IPP printer in CUPS 3.x

[Till Kamppeter]

Abdelrahman,

here is how profiles work for the case of DNS-SD turned off:

https://github.com/OpenPrinting/cups-local/issues/2#issuecomment-1749078644

This works with the local server only.

The three lines in the example are:

1. For all print destinations (like printing, fax out) of a network printer (you 
specify the IP/name and port) or for a print server appliance.

2. For a remote CUPS server, all print destinations which it is sharing

3. For a single print destination

Profile files can also contain filters, so that if you have an enterprise 
network with DNS-SD turned on, print dialogs do not get cluttered with 
irrelevant printers. See

https://github.com/OpenPrinting/cups-local/issues/2#issuecomment-1749078668


The sharing server works like a Printer Application. You create queues on it, 
but those queues are pointing to IPP print destinations which you want to share. 
It is for relaying an IPP printer from one local network to another local 
network, or to gate jobs through the sharing server for page accounting or for 
access restriction.

    Till


On 8/1/26 23:48, Till Kamppeter wrote:
> Abdelrahman,
> 
> I think now I see how the concept in CUPS 3.x is meant:
> 
> First, in "Add Printer" you do not only allow to look for legacy printers to 
> assign Printer Applications to, but you also look for driverless network 
> printers which are not visible due to mDNS/DNS-SD not running or the printer 
> being in a network not being your local one.
> 
> So in "Add Printer" you give the options as I suggested before:
> 
> On 8/1/26 21:50, Till Kamppeter wrote:
>> Abdelrahman,
>>
>> If there is no mDNS/DNS-SD active you can do:
>>
>> 1. Put an option into the "Add Printer" part where the user only enters the IP 
>> (or host name) of the printer. It could then try get-printer-attributes on
>> - ipps://IP:443/
>> - ipps://IP:631/
>> - ipp://IP:631/
>> - ipps://IP:8000/
>> - ipp://IP:8000/
>> - ipps://IP:8001/
>> - ipp://IP:8001/
>> - ...
>>
>> Test 1 and 3 are for network printers, 2 and 3 for remote CUPS servers, 4+ for 
>> remote Printer Applications.
>>
>> 2. Also test
>> - ipp://localhost:60000/
>> - ipp://localhost:60001/
>> - ...
>> - ipps://localhost:8000/
>> - ipp://localhost:8000/
>> - ipps://localhost:8001/
>> - ipp://localhost:8001/
>> - ...
>>
>> either automatically in the main view or  by button(s) in "Add Printer". This 
>> is for local IPP-over-USB printers and local Printer Applications.
>>
> 
> You also give the option to select a network, to extend IPP printer discovery 
> into that network. For example the user can add the corporate printer VLAN here.
> 
> Settings will be saved in profiles in ~/.cups/profiles/
> 
> You can also add a switch to "Add Printer" to make system-wide settings, then 
> they get saved in /etc/cups/profiles/. Flicking this switch requires 
> authentication for a root operation.
> 
> So you add to the "Add Printer" part a GUI frontend for defining profiles.
> 
> The profiles are NOT being used by the running CUPS daemon (local or sharing) 
> but by the function in libcups (cupsEnumDests()) to list available print 
> destinations. All print dialogs will have to use this function (if a dialog uses 
> CPDB it will use this function).
> 
> So from Michael we need to know what the capabilities and the syntax of the 
> files for profiles are.
> 
> 
> Also, you can add "Set Option Defaults" buttons to all print destinations in the 
> main view. This button is to be considered as a GUI frontend for the "lpoptions" 
> command (or its libcups API equivalent, see source code of "lpoptions"). So 
> settings get saved in ~/.cups/lpoptions (or with "system-wide" switch and 
> authentication in /etc/cups/lpoptions). Note that these saved options do not 
> require that the daemon has a permanent queue. They are only used by the client 
> side (print dialogs of all portals and toolkits, CPDB, CLI tools).
> 
> 
> Michael, am I right now?
> 
>     Till
> 

Re: Recommended way to manually add an undiscovered IPP printer in CUPS 3.x

[AbdElRahman Khalifa]

Thank you for the explanations. I think I now understand the
separation between printer profiles, the local server, and the sharing
server.

My current understanding is the following:

1. cupsEnumDests() should be the source of truth for the destinations
displayed on the main Printers page.
It can return automatically discovered IPP destinations, remote CUPS
queues, Printer Application destinations, and eventually destinations
supplied through profiles.
Therefore, a destination must still be displayed even when I cannot
find a corresponding local DNS-SD advertisement.

2. DNS-SD should be an enrichment and grouping source, rather than the
authoritative destination list.
I currently use Avahi to obtain information such as the service
instance, hostname, port, resource path, TXT UUID, and the
relationship between _ipp._tcp and _ipps._tcp advertisements.
I will correlate this information with the destinations returned by
cupsEnumDests() and use it for physical-device grouping. Where
possible.

3,. COSMIC Printers should not create or edit printer profile files.

4. Profiles belong to the local-server/libcups discovery mechanism.
When libcups supports them, profile-defined destinations should appear
naturally through cupsEnumDests().
Queues owned by the sharing server are a separate concept.
I should query the sharing server using its IPP System Service
operations, such as Get-Printers, when I specifically need to list or
administer the queues owned by that server. I should not infer that
every destination returned by cupsEnumDests() is a configured
sharing-server queue.

5. A normal driverless destination returned by cupsEnumDests() is
already usable and does not require an Add operation. A queue on the
sharing server should only be created if the user explicitly requests
server-side sharing, relaying, accounting, access control, or similar
policies, for example, when the user opens the Add Printer dialog and
selects that printer.

6. For an undiscovered driverless printer entered manually via IP
address or hostname, printer setup tool should probe it using
Get-Printer-Attributes and then create a queue for it on the sharing
server.

Thanks,
Abdelrahman

Re: Recommended way to manually add an undiscovered IPP printer in CUPS 3.x

[Till Kamppeter]

On 8/2/26 11:18, AbdElRahman Khalifa wrote:
> Thank you for the explanations. I think I now understand the
> separation between printer profiles, the local server, and the sharing
> server.
> 
> My current understanding is the following:
> 
> 1. cupsEnumDests() should be the source of truth for the destinations
> displayed on the main Printers page.
> It can return automatically discovered IPP destinations, remote CUPS
> queues, Printer Application destinations, and eventually destinations
> supplied through profiles.
> Therefore, a destination must still be displayed even when I cannot
> find a corresponding local DNS-SD advertisement.
> 

Yes, especially as there can be destinations due to entries in the profile, 
either because DNS-SD is off or destination outside the local network are 
defined. You do not need to parse the profile or investigate any reasons, if you 
are using cupsEnumDests() the right thing will happen and you will see the 
correct list of available destinations. And as print dialogs are also supposed 
to use cupsEnumDests(), you see exactly the printers which you see in the print 
dialogs.

> 2. DNS-SD should be an enrichment and grouping source, rather than the
> authoritative destination list.
> I currently use Avahi to obtain information such as the service
> instance, hostname, port, resource path, TXT UUID, and the
> relationship between _ipp._tcp and _ipps._tcp advertisements.
> I will correlate this information with the destinations returned by
> cupsEnumDests() and use it for physical-device grouping. Where
> possible.
> 

Yes, DNS-SD checking by your software is only to get extra info, like for 
grouping. The authoritative list of available destinations comes from 
cupsEnumDests().

> 3,. COSMIC Printers should not create or edit printer profile files.
> 

Generally, under Linux configuration info is stored in text files and GUI tools 
to do configuration save the settings in that text files. So the GUI tools are 
frontends to easily "edit" these files and the user sees the realm of 
controlling the settings by GUI, as this is much more intuitive.

So principally one can make a GUI for managing a profile for the local server of 
CUPS.

For correctly configured Linux distros this should not be that necessary, as for 
end users at home or in small offices (SOHO setting), where we do not have a 
system administrator, DNS-SD should always be turned on, and so all print 
destinations get automatically available, without need to edit the profile. An 
end-user distro coming with DNS-SD off is not a good end-user distro.

In enterprise settings with a lot of machines and networks there are always 
system administrators who have no problems to hand-edit config files. And to 
manage the vast amount of network resources (also printers) they decide on how 
to do so, and when turning DNS-SD off or sub-dividing the local network into 
many smaller ones, they enter the needed references to printers and 
printer-providing external sub-nets, and also filters in the CUPS profiles of 
the desktop machines, so that cupsEnumDests() called by a user's print dialog or 
printer setup tool shows exactly the needed printers.

> 4. Profiles belong to the local-server/libcups discovery mechanism.
> When libcups supports them, profile-defined destinations should appear
> naturally through cupsEnumDests().

Yes, exactly this.

> Queues owned by the sharing server are a separate concept.
> I should query the sharing server using its IPP System Service
> operations, such as Get-Printers, when I specifically need to list or
> administer the queues owned by that server. I should not infer that
> every destination returned by cupsEnumDests() is a configured
> sharing-server queue.
>

A sharing server is a Printer Application and so it is like an IPP network 
printer. A Printer Application is not necessarily an application providing the 
driver for a non-driverless legacy printer, but a Printer Application is any 
kind of software implementation of a driverless IPP printer. Even ipp-usb is a 
Printer Application. On the sharing server there are print queues defined. These 
print queues are IPP print destinations for clients, and they pass on the jobs 
to other IPP print destinations. They are highly configurable, for example to 
allow only certain clients to see/use the print queue, to do page accounting, to 
restrict the use to certain users, to require authentication, ... and the 
network where the print queues are visible to clients and where the destination 
printer is do not need to be actually the same.

In most SOHO settings you do not need a sharing server as network printers are 
sharing themselves to your whole local network. Also Printer Applications to 
provide the driver for a legacy printer can be set to share the printer to the 
local network instead of only the local machine. The same is valid even for ipp-usb.

cupsEnumDests() is showing any IPP print destination, regardless of whether it 
is a network printer, a destination from a sharing server, an IPP-over-USB 
printer, a legacy printer set up with a Printer Application.

With IPP System Service you handle any IPP server. Get-Printers gives you all 
IPP destinations which this server provides. Works on a sharing server (shows 
the queues created on it), on a network multi-function printer (shows the print 
destination and depending on the device also the fax out destination), ... IPP 
System Service can especially also help you to group the print destinations 
correctly, especially if DNS-SD is turned off.

> 5. A normal driverless destination returned by cupsEnumDests() is
> already usable and does not require an Add operation.

Yes, that's it. The printer setup tool should provide buttons for opening the 
web admin interface and for default option settings (GUI for lpoptions).

> A queue on the
> sharing server should only be created if the user explicitly requests
> server-side sharing, relaying, accounting, access control, or similar
> policies, for example, when the user opens the Add Printer dialog and
> selects that printer.
> 

Yes, you use the sharing server by installing it and creating queues on it if 
you have special needs, which are not served by the network printers themselves.

You can have for example a sharing server in your local network which has a 
queue set up pointing to a printer in a VLAN, which your local network's DNS-SD 
does not see, but your DNS-SD sees your sharing server and so the printer gets 
available for everybody.

Or you can enforce page accounting by configuring the printer (via its web 
interface, do not forget to password-protect the web interface) to only accept 
jobs from the machine running your sharing server. On your sharing server create 
a queue pointing to your printer and having page accounting. Now users see only 
the queues of your sharing server and not the printer itself, forcing their jobs 
through the page accounting.

With DNS-SD in your local network turned off, you have to point to your sharing 
server in your profile, as you would also do for a regular network printer.

> 6. For an undiscovered driverless printer entered manually via IP
> address or hostname, printer setup tool should probe it using
> Get-Printer-Attributes and then create a queue for it on the sharing
> server.

Here the sharing server is not necessarily needed. To just overcome the fact 
that DNS-SD is not available or the printer is in a separate local network the 
sharing server is often overkill and adding the printer's URI to the profile 
does the trick already.

    Till

Re: Recommended way to manually add an undiscovered IPP printer in CUPS 3.x

[Michael Sweet]

Abdelrahman,

> On Aug 2, 2026, at 5:18 AM, AbdElRahman Khalifa <abdelrahman.5alifa@gmail.com> wrote:
> 
> Thank you for the explanations. I think I now understand the
> separation between printer profiles, the local server, and the sharing
> server.
> 
> My current understanding is the following:
> 
> 1. cupsEnumDests() should be the source of truth for the destinations
> displayed on the main Printers page.
> It can return automatically discovered IPP destinations, remote CUPS
> queues, Printer Application destinations, and eventually destinations
> supplied through profiles.
> Therefore, a destination must still be displayed even when I cannot
> find a corresponding local DNS-SD advertisement.

Correct.

> 2. DNS-SD should be an enrichment and grouping source, rather than the
> authoritative destination list.
> I currently use Avahi to obtain information such as the service
> instance, hostname, port, resource path, TXT UUID, and the
> relationship between _ipp._tcp and _ipps._tcp advertisements.
> I will correlate this information with the destinations returned by
> cupsEnumDests() and use it for physical-device grouping. Where
> possible.

The destinations returned by cupsEnumDests should have device-uri, printer-location, printer-make-and-model, printer-type, and printer-uuid as extracted from the TXT record.  Local queues will have more attributes (including printer-uri-supported which provides the local CUPS queue) but there should be no need to separately browse.

Also, the CUPS DNS-SD APIs are available and will isolate you from other OS changes below you. For example, the systemd folks have been trying to replace Avahi for several years now - it is possible they might actually succeed some day, and using the CUPS APIs will insulate you from that change...

> 3,. COSMIC Printers should not create or edit printer profile files.

You could conceptually provide an admin tool for "exporting" profiles to provide to end-users, but beyond that I don't think there is much point.

> 4. Profiles belong to the local-server/libcups discovery mechanism.
> When libcups supports them, profile-defined destinations should appear
> naturally through cupsEnumDests().

Correct.

> Queues owned by the sharing server are a separate concept.
> I should query the sharing server using its IPP System Service
> operations, such as Get-Printers, when I specifically need to list or
> administer the queues owned by that server. I should not infer that
> every destination returned by cupsEnumDests() is a configured
> sharing-server queue.

Correct.

> 5. A normal driverless destination returned by cupsEnumDests() is
> already usable and does not require an Add operation. A queue on the
> sharing server should only be created if the user explicitly requests
> server-side sharing, relaying, accounting, access control, or similar
> policies, for example, when the user opens the Add Printer dialog and
> selects that printer.

Correct.

> 6. For an undiscovered driverless printer entered manually via IP
> address or hostname, printer setup tool should probe it using
> Get-Printer-Attributes and then create a queue for it on the sharing
> server.

There may not be a sharing server.  There will always be a local server.

A "driverless" printer that has to be manually configured can be setup via a printer profile with the local server. The sharing server only needs to get involved if a) the printer is on a separate network that only the sharing server has access to or b) there is a need to control/monitor access to the printer as you detail in #5 above.

________________________
Michael Sweet

Re: Recommended way to manually add an undiscovered IPP printer in CUPS 3.x

[AbdElRahman Khalifa]

Michael, Till,

I tried to reproduce the proposed per-user profile behavior for an IPP
printer that is not discoverable through DNS-SD, but I cannot get the
profile entries to be recognized.

I tested the proposed directives:

```text
Server ipp://HOST:PORT/ipp/system
ServerName HOST:PORT
Printer ipp://HOST:PORT/ipp/print
```

My environment is:

```text
libcups3: 3.0.3 installed under /usr/local
also i have libcups2: 2.4.7
cups-locald: not installed
```

For the test printer I used:

```text
ippeveprinter -p 9200 -r off
```

So it does not advertise itself through DNS-SD at all. Direct
`Get-Printer-Attributes` requests work and return the printer
correctly.

I tested both per-user profile locations:

```text
~/.config/cups/profiles/
~/.cups/profiles/
```

However, `strace` shows that libcups3 never scans or opens either
profiles directory, and `cupsEnumDests()` doesn't shows the printer.

So currently I cannot reproduce the intended flow:

```text
profile file
    |
    v
cupslocald/libcups reads it
    |
    v
cupsEnumDests()
    |
    v
printer appears
```

Is `cups-locald` currently required for profiles to work?

And if so, is profile support expected to work with the current
`cups-local` tree, or is that part still not implemented/released?

I mainly want to make sure I am testing the intended CUPS 3.x setup
correctly before deciding how the COSMIC side should handle manually
entered/undiscovered printers.

Thanks,
Abdelrahman

Re: Recommended way to manually add an undiscovered IPP printer in CUPS 3.x

[Michael Sweet]

Abdelrahman,

This functionality has not yet been implemented - it is part of the cups-local project (not libcups).


> On Aug 7, 2026, at 3:14 PM, AbdElRahman Khalifa <abdelrahman.5alifa@gmail.com> wrote:
> 
> Michael, Till,
> 
> I tried to reproduce the proposed per-user profile behavior for an IPP
> printer that is not discoverable through DNS-SD, but I cannot get the
> profile entries to be recognized.
> 
> I tested the proposed directives:
> 
> ```text
> Server ipp://HOST:PORT/ipp/system
> ServerName HOST:PORT
> Printer ipp://HOST:PORT/ipp/print
> ```
> 
> My environment is:
> 
> ```text
> libcups3: 3.0.3 installed under /usr/local
> also i have libcups2: 2.4.7
> cups-locald: not installed
> ```
> 
> For the test printer I used:
> 
> ```text
> ippeveprinter -p 9200 -r off
> ```
> 
> So it does not advertise itself through DNS-SD at all. Direct
> `Get-Printer-Attributes` requests work and return the printer
> correctly.
> 
> I tested both per-user profile locations:
> 
> ```text
> ~/.config/cups/profiles/
> ~/.cups/profiles/
> ```
> 
> However, `strace` shows that libcups3 never scans or opens either
> profiles directory, and `cupsEnumDests()` doesn't shows the printer.
> 
> So currently I cannot reproduce the intended flow:
> 
> ```text
> profile file
>    |
>    v
> cupslocald/libcups reads it
>    |
>    v
> cupsEnumDests()
>    |
>    v
> printer appears
> ```
> 
> Is `cups-locald` currently required for profiles to work?
> 
> And if so, is profile support expected to work with the current
> `cups-local` tree, or is that part still not implemented/released?
> 
> I mainly want to make sure I am testing the intended CUPS 3.x setup
> correctly before deciding how the COSMIC side should handle manually
> entered/undiscovered printers.
> 
> Thanks,
> Abdelrahman
> 

________________________
Michael Sweet