Using SeedDMS like a printer

Assume you have just received by email your booking confirmation for the next vacation and would like to keep a copy of it in your SeedDMS. Or you have found this wonderful recipe on how to make german schnitzel and would like to save a PDF of it in your SeedDMS. Well, you could save it to your local disk and then upload it into SeedDMS. But, how would it be if you just print it right into SeedDMS, no matter if you are using your mobile phone or your desktop PC. The SeedDMS Cups backend makes this possible. It can be downloaded as a debian package from https://github.com/SeedDMS/go-cupsbackend

How it works

The Common Unix Printing System (cups) is the defacto standard for printing on Linux and MacOS. It offers printers in a network, does format conversions and finally sends the printable data to the printer. The final step in this process is done by a so called cups backend. It usually talks to the printer but it may as well talk to any other device, even a web service like the REST API of SeedDMS.

How to set it up

First of all you need a print server running cups and install the debian package from https://github.com/SeedDMS/go-cupsbackend. Once that is done you can already configure a new printer with the tool of your choice. In this particular case I used the cups web ui.

Give it a name, e.g. SeedDMS — 2. Give it a name and allow access within the network, e.g. SeedDMS

Before printing on the new printer you will have to configure the backend by specifying the location, API key and folder of your SeedDMS. Create a file `/etc/seeddms-cups/printers.yaml’ with the content

default:
  Url: https://your-seeddms-host/restapi/index.php
  ApiKey: your-secret-key
  FolderId: 1

Of course you need to adjust the Url and set an ApiKey in SeedDMS and the configuration file. Instead of setting the default configuration, you could as well replace default by your printers name, e.g. SeedDMS. Do not make the configuration world readable, because it contains the API key.

Once done, it is time for a first test. On your cups server execute

lp -d SeedDMS a-pdf-file

and the pdf file will show up in your SeedDMS seconds later. If it doesn’t, then check the syslog messages on your server. It will give you detailed information on whether the configuration file was found and what possibly made the upload fail.

Though in many cases a single printer for uploading documents into a designated folder in SeedDMS is sufficient, you can create more printers with different configuration and you can have user dependent configuration files located either in the user’s home directory (~/.config/seeddms-cups/printers.yaml) or system wide in /etc/seeddms-cups/<username>/printers.yaml. The username is set by the cups client. On the cups server itself, it will be the account name of the user executing the lp or any other print command. If the printer is accessible in the network, it could be accessed by all devices and they use usernames which aren’t necessarily login names of real users. Mobile phones for example often set the model name of the phone.

Security considerations

Access on printers can hardly be restricted by cups. If a printer is network wide available, any device within that network may use it. This means in case of a SeedDMS printer, that any device would be able to upload documents into the configured folder. Even by users not known to SeedDMS. Hence, when you setup a printer, then take the following security considerations into account:

Possibly create a designated user in SeedDMS which is exclusively used for the printers.
Restrict access of that user on the upload folder
Associate that user with the API key in SeedDMS (which may not be possible, if the API is used otherwise)
Ensure your printers.conf are sufficiently protected from spying out the API key. Basically, do not make the configuration world readable, but restrict access to the user running the cups server.