From db009d158eaef788f8db052a9d0257dbb7c2868b Mon Sep 17 00:00:00 2001 From: David Ward Date: Thu, 14 Apr 2022 19:14:50 -0400 Subject: [PATCH] doc/saned: Move service configuration details out of man page The saned(8) man page should be used to describe the behavior of saned itself. The information about configuring inetd, xinetd, or systemd to launch saned - while it is helpful - belongs in a separate location. Keep in mind that distribution packages usually configure the service automatically, and they may ship with their own specific instructions. (For example, update-inetd can be used in Debian and its derivatives.) This change moves this information from the man page into a new file, making it more concise as well. Working examples are moved to separate files that can be copied directly from the source tree to the system. --- doc/Makefile.am | 1 + doc/saned.man | 292 +--------------------------------- doc/saned/saned.install.md | 59 +++++++ frontend/.gitignore | 4 + frontend/Makefile.am | 19 ++- frontend/saned.socket | 10 ++ frontend/saned.xinetd.conf.in | 13 ++ frontend/saned@.service.in | 11 ++ 8 files changed, 122 insertions(+), 287 deletions(-) create mode 100644 doc/saned/saned.install.md create mode 100644 frontend/saned.socket create mode 100644 frontend/saned.xinetd.conf.in create mode 100644 frontend/saned@.service.in diff --git a/doc/Makefile.am b/doc/Makefile.am index f050abb39..5c736feb5 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -129,6 +129,7 @@ BEDOCS += plustek/FAQ \ plustek/Plustek-PARPORT.changes plustek/Plustek-PARPORT.txt \ plustek/Plustek-USB-TODO.txt plustek/Plustek-USB.changes \ plustek/Plustek-USB.txt +BEDOCS += saned/saned.install.md BEDOCS += sceptre/s1200.txt BEDOCS += teco/teco1.txt teco/teco2.txt teco/teco3.txt BEDOCS += u12/U12.changes u12/U12.todo diff --git a/doc/saned.man b/doc/saned.man index d91f8176a..65cfc4fca 100644 --- a/doc/saned.man +++ b/doc/saned.man @@ -117,15 +117,6 @@ debug output to stderr instead of the syslog default. .TP .BR \-h ", " \-\-help displays a short help message. -.PP -If -.B saned -is run from other programs such as -.BR inetd (8), -.BR xinetd (8) -and -.BR systemd (1), -check that program's documentation on how to pass command-line options. .SH CONFIGURATION First and foremost: @@ -199,282 +190,6 @@ scan\-client.somedomain.firm .PP The case of the host names does not matter, so AHost.COM is considered identical to ahost.com. -.SH SERVER DAEMON CONFIGURATION -For -.B saned -to work properly in its default mode of operation, it is also necessary to -add the appropriate configuration for -.BR xinetd (8), -.BR inetd (8) -or -.BR systemd (1) -(see below). -Note that your -.BR inetd (8) -must support IPv6 if you want to connect to -.B saned -over IPv6; -.BR xinetd (8), -.BR openbsd-inetd (8) -and -.BR systemd (1) -are known to support IPv6, check the documentation for your -.BR inetd (8) -daemon. -.PP -In the sections below the configuration for -.BR inetd (8), -.BR xinetd (8) -and -.BR systemd (1) -are described in more detail. -.PP -For the configurations below it is necessary to add a line of the following -form to -.IR /etc/services : -.PP -.RS -sane\-port 6566/tcp # SANE network scanner daemon -.RE -.PP -The official IANA short name for port 6566 is "sane\-port". The older name -"sane" is now deprecated. - -.SH INETD CONFIGURATION -It is required to add a single line to the -.BR inetd (8) -configuration file -.IR (/etc/inetd.conf) -. -.PP -The configuration line normally looks like this: -.PP -.RS -sane\-port stream tcp nowait saned.saned @SBINDIR@/saned saned -.RE -.PP -However, if your system uses -.BR tcpd (8) -for additional security screening, you may want to disable -.B saned -access control by putting ``+'' in -.IR saned.conf -and use a line of the following form in -.IR /etc/inetd.conf -instead: -.PP -.RS -sane\-port stream tcp nowait saned.saned /usr/sbin/tcpd @SBINDIR@/saned -.RE -.PP -Note that both examples assume that there is a -.B saned -group and a -.B saned -user. If you follow this example, please make sure that the -access permissions on the special device are set such that -.B saned -can access the scanner (the program generally needs read and -write access to scanner devices). - -.SH XINETD CONFIGURATION -If -.BR xinetd (8) -is installed on your system instead of -.BR inetd (8) -the following example for -.I /etc/xinetd.conf -may be helpful: -.PP -.RS -.ft CR -.nf -# default: off -# description: The sane server accepts requests -# for network access to a local scanner via the -# network. -service sane\-port -{ - port = 6566 - socket_type = stream - wait = no - user = saned - group = saned - server = @SBINDIR@/saned -} -.fi -.ft R -.RE - -.SH SYSTEMD CONFIGURATION -.B saned -can be compiled with explicit -.BR systemd (1) -support. This -will allow logging debugging information to be forwarded -to the -.BR systemd (1) -journal. The -.BR systemd (1) -support requires compilation with the systemd-devel package -installed on the system. This is the preferred option. - -.B saned -can be used with -.BR systemd (1) -without the -.BR systemd (1) -integration compiled in, but then logging of debug information is not supported. - -The -.BR systemd (1) -configuration is different for the 2 options, so both are described below. - -.SH Systemd configuration for saned with systemd support compiled in -For -.BR systemd (1) -configuration we need to add 2 configuration files in -.IR /etc/systemd/system . -.PP -The first file we need to add here is called -.I saned.socket. -It shall have -the following contents: -.PP -.RS -.ft CR -.nf -[Unit] -Description=saned incoming socket - -[Socket] -ListenStream=6566 -Accept=yes -MaxConnections=1 - -[Install] -WantedBy=sockets.target -.fi -.ft R -.RE -.PP -The second file to be added is -.I saned@.service -with the following contents: -.PP -.RS -.ft CR -.nf -[Unit] -Description=Scanner Service -Requires=saned.socket - -[Service] -ExecStart=/usr/sbin/saned -User=saned -Group=saned -StandardInput=null -StandardOutput=syslog -StandardError=syslog -Environment=SANE_CONFIG_DIR=@CONFIGDIR@ -# If you need to debug your configuration uncomment the next line and -# change it as appropriate to set the desired debug options -# Environment=SANE_DEBUG_DLL=255 SANE_DEBUG_BJNP=5 - -[Install] -Also=saned.socket -.fi -.ft R -.RE -.PP -You need to set an environment variable for -.B SANE_CONFIG_DIR -pointing to the directory where -.B saned -can find its configuration files. -You will have to remove the # on the last line and set the variables -for the desired debugging information if required. Multiple variables -can be set by separating the assignments by spaces as shown in the -example above. -.PP -Unlike -.BR xinetd (8) -and -.BR inetd (8), -.BR systemd (1) -allows debugging output from backends set using -.B SANE_DEBUG_XXX -to be captured. See the man-page for your backend to see what options -are supported. -With the service unit as described above, the debugging output is -forwarded to the system log. - -.SH Systemd configuration when saned is compiled without systemd support -This configuration will also work when -.B saned -is compiled WITH -.BR systemd (1) -integration support, but it does not allow debugging information to be logged. -.PP -For -.BR systemd (1) -configuration for -.BR saned , -we need to add 2 configuration files in -.IR /etc/systemd/system . -.PP -The first file we need to add here is called -.I saned.socket. -It is identical to the version for -.BR systemd (1) -with the support compiled in. -It shall have the following contents: -.PP -.RS -.ft CR -.nf -[Unit] -Description=saned incoming socket - -[Socket] -ListenStream=6566 -Accept=yes -MaxConnections=1 - -[Install] -WantedBy=sockets.target -.fi -.ft R -.RE -.PP -The second file to be added is -.IR saned@.service . -This one differs from the version with -.BR systemd (1) -integration compiled in: -.PP -.RS -.ft CR -.nf -[Unit] -Description=Scanner Service -Requires=saned.socket - -[Service] -ExecStart=/usr/sbin/saned -User=saned -Group=saned -StandardInput=socket - -Environment=SANE_CONFIG_DIR=/etc/sane.d - -[Install] -Also=saned.socket -.fi -.ft R -.RE -.PP - .SH FILES .TP .I /etc/hosts.equiv @@ -518,6 +233,13 @@ and .I "@CONFIGDIR@" being searched (in this order). +.SH NOTES +Refer to +.I @DOCDIR@/saned/saned.install.md +for details on configuring +.B saned +as a service. + .SH "SEE ALSO" .BR sane (7), .BR scanimage (1), diff --git a/doc/saned/saned.install.md b/doc/saned/saned.install.md new file mode 100644 index 000000000..ba40a8255 --- /dev/null +++ b/doc/saned/saned.install.md @@ -0,0 +1,59 @@ +Configuring `saned` as a service +================================ + +To launch `saned` automatically in response to an incoming connection, +configure it as a service managed by `inetd`, `xinetd`, or `systemd`. + +First verify that /etc/services contains a line of the following form: + + sane-port 6566/tcp # SANE network scanner daemon + +If not, then add it. (The name "sane-port" has been assigned by IANA.) + + +The examples below assume there is a "saned" group and a "saned" user. +Make sure that the ACLs on the scanner device files are set such that +`saned` can access them for reading and writing. + + +`inetd` Configuration +--------------------- + +Configure `inetd` if your platform does not use `systemd` or `xinetd`. +Not all `inetd` implementations support IPv6; check its documentation. + +Add a line in /etc/inetd.conf like the following: + + sane-port stream tcp nowait saned.saned /usr/local/sbin/saned saned + + +`xinetd` Configuration +---------------------- + +Copy frontend/saned.xinetd.conf into the `xinetd` configuration files +directory (as /etc/xinetd.d/saned.conf). + + +`systemd` Configuration +----------------------- + +Copy frontend/saned.socket and frontend/saned@.service into one of the +system-wide directories for unit files (/etc/systemd/system/). + +The recommended way to adjust the service settings is with the command +`systemctl edit saned@`. This opens a file inside a text editor where +overrides may be entered. As an example, environment variables can be +set which are used to control debug logging in individual backends: + + [Service] + Environment=SANE_DEBUG_DLL=255 + Environment=SANE_DEBUG_BJNP=5 + +(Refer to the man pages of the appropriate backends for more details.) + +It is recommended to build SANE with explicit `systemd` support, which +allows log messages from `saned` to be written to the journal. If SANE +is built without this support, the following override must be used: + + [Service] + StandardInput=socket diff --git a/frontend/.gitignore b/frontend/.gitignore index 90f73a953..e42f6b03a 100644 --- a/frontend/.gitignore +++ b/frontend/.gitignore @@ -1,2 +1,6 @@ saned +saned@.service +saned.xinetd.conf scanimage +test +tstbackend diff --git a/frontend/Makefile.am b/frontend/Makefile.am index 9b926459e..8573aba31 100644 --- a/frontend/Makefile.am +++ b/frontend/Makefile.am @@ -44,5 +44,20 @@ tstbackend_LDADD += -lstdc++ endif endif -clean-local: - rm -f test tstbackend +BUILT_SOURCES = saned@.service saned.xinetd.conf + +EXTRA_DIST = saned.socket saned@.service.in saned.xinetd.conf.in + +CLEANFILES = $(EXTRA_PROGRAMS) $(BUILT_SOURCES) + +SUFFIXES = .in +.in: + $(AM_V_GEN) + @if $(AM_V_P); then echo Generating $@ from $^; fi + @sed -e 's|@DATADIR@|$(datadir)|g' \ + -e 's|@CONFIGDIR@|$(configdir)|g' \ + -e 's|@DOCDIR@|$(docdir)|g' \ + -e 's|@LIBDIR@|$(libdir)/sane|g' \ + -e 's|@BINDIR@|$(bindir)|g' \ + -e 's|@SBINDIR@|$(sbindir)|g' \ + -e 's|@PACKAGEVERSION@|$(PACKAGE_VERSION)|g' $? > $@ diff --git a/frontend/saned.socket b/frontend/saned.socket new file mode 100644 index 000000000..1aa19e703 --- /dev/null +++ b/frontend/saned.socket @@ -0,0 +1,10 @@ +[Unit] +Description=saned incoming socket + +[Socket] +ListenStream=6566 +Accept=yes +MaxConnections=1 + +[Install] +WantedBy=sockets.target diff --git a/frontend/saned.xinetd.conf.in b/frontend/saned.xinetd.conf.in new file mode 100644 index 000000000..3465dee68 --- /dev/null +++ b/frontend/saned.xinetd.conf.in @@ -0,0 +1,13 @@ +# default: off +# description: The sane server accepts requests +# for network access to a local scanner via the +# network. +service sane-port +{ + port = 6566 + socket_type = stream + wait = no + user = saned + group = saned + server = @SBINDIR@/saned +} diff --git a/frontend/saned@.service.in b/frontend/saned@.service.in new file mode 100644 index 000000000..1682109b3 --- /dev/null +++ b/frontend/saned@.service.in @@ -0,0 +1,11 @@ +[Unit] +Description=Scanner Service +Requires=saned.socket + +[Service] +ExecStart=@SBINDIR@/saned +User=saned +Group=saned + +[Install] +Also=saned.socket