Initial import of sane-backends version 1.0.24-1.2

1 files changed, 325 insertions, 0 deletions

diff --git a/doc/saned.man b/doc/saned.man
new file mode 100644
index 0000000..d8e8983
--- /dev/null
+++ b/doc/saned.man
@@ -0,0 +1,325 @@
+.TH saned 8 "20 Apr 2009" "@PACKAGEVERSION@" "SANE Scanner Access Now Easy"
+.IX saned
+.SH NAME
+saned \- SANE network daemon
+.SH SYNOPSIS
+.B saned
+.B [ \-a 
+.I [ username ]
+.B | \-d 
+.I [ n ]
+.B | \-s
+.I [ n ]
+.B | \-h
+.B ]
+.SH DESCRIPTION
+.B saned
+is the SANE (Scanner Access Now Easy) daemon that allows remote clients
+to access image acquisition devices available on the local host.
+.SH OPTIONS
+.PP
+The
+.B \-a
+flag requests that
+.B saned
+run in standalone daemon mode. In this mode, 
+.B saned
+will detach from the console and run in the background, listening for incoming
+client connections; 
+.B inetd
+is not required for
+.B saned
+operations in this mode. If the optional
+.B username
+is given after
+.B \-a
+,
+.B saned
+will drop root privileges and run as this user (and group).
+.PP
+The
+.B \-d
+and
+.B \-s
+flags request that
+.B saned
+run in debug mode (as opposed to
+.BR inetd (8)
+daemon mode).  In this mode,
+.B saned
+explicitly waits for a connection request.  When compiled with
+debugging enabled, these flags may be followed by a number to request
+debug info. The larger the number, the more verbose the debug output.
+E.g.,
+.B \-d128
+will request printing of all debug info. Debug level 0 means no debug output
+at all. The default value is 2. If flag
+.B \-d
+is used, the debug messages will be printed to stderr while
+.B \-s
+requests using syslog.
+.PP
+If 
+.B saned
+is run from inetd, xinetd or systemd, no option can be given.
+.PP
+The
+.B \-h
+flag displays a short help message.
+.SH CONFIGURATION
+First and foremost: 
+.B saned
+is not intended to be exposed to the internet or other non-trusted
+networks. Make sure that access is limited by tcpwrappers and/or a firewall
+setup. Don't depend only on 
+.BR saned 's
+own authentication. Don't run
+.B saned
+as root if it's not necessary. And do
+.B not
+install
+.B saned
+as setuid root.
+.PP
+The 
+.I saned.conf
+configuration file contains both options for the daemon and the access
+list.
+.TP
+\fBdata_portrange\fP = \fImin_port\fP - \fImax_port\fP
+Specify the port range to use for the data connection. Pick a port
+range between 1024 and 65535; don't pick a too large port range, as it
+may have performance issues. Use this option if your \fBsaned\fP
+server is sitting behind a firewall. If that firewall is a Linux
+machine, we strongly recommend using the Netfilter
+\fInf_conntrack_sane\fP module instead.
+.PP
+The access list is a list of host names, IP addresses or IP subnets
+(CIDR notation) that are permitted to use local SANE devices. IPv6
+addresses must be enclosed in brackets, and should always be specified
+in their compressed form. Connections from localhost are always
+permitted. Empty lines and lines starting with a hash mark (#) are
+ignored. A line containing the single character ``+'' is interpreted
+to match any hostname. This allows any remote machine to use your
+scanner and may present a security risk, so this shouldn't be used
+unless you know what you're doing.
+.PP
+A sample configuration file is shown below:
+.PP
+.RS
+# Daemon options
+.br
+data_portrange = 10000 - 10100
+.br
+# Access list
+.br
+scan\-client.somedomain.firm
+.br
+# this is a comment
+.br
+192.168.0.1
+.br
+192.168.2.12/29
+.br
+[::1]
+.br
+[2001:db8:185e::42:12]/64
+.RE
+.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 
+.I (x)inetd or systemd.
+(see below).
+Note that your inetd must support IPv6 if you
+want to connect to saned over IPv6 ; xinetd, openbsd-inetd and systemd 
+are known to support IPv6, check the documentation for your inetd daemon.
+.PP
+In the sections below the configuration for 
+.I inetd, xinetd
+and
+.I systemd
+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 inetd 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
+.E
+.PP
+However, if your system uses
+.BR tcpd (8)
+for additional security screening, you may want to disable 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 xinetd is installed on your system instead of inetd 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
+for systemd we need to add 2 configuation files in 
+.I /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@ SANE_DEBUG_DLL=255
+.fi
+.ft R
+.RE
+.PP
+Is you need to set an environment variable for saned like
+.B SANE_CONFIG_DIR
+you will have to remove the # on the last line and set the variable 
+appropriately.  Multiple variables can be set by separating the assignments 
+by spaces as shown in the example above.
+.PP
+Unlike 
+.I (x)inetd
+systemd allows debugging output from backends set using
+.B SANE_DEBUG_<backend_name> 
+to be captured. With the service unit as described above, the debugging output is 
+forwarded to the system log.
+.SH FILES
+.TP
+.I /etc/hosts.equiv
+The hosts listed in this file are permitted to access all local SANE
+devices.  Caveat: this file imposes serious security risks and its use
+is not recommended.
+.TP
+.I @CONFIGDIR@/saned.conf
+Contains a list of hosts permitted to access local SANE devices (see
+also description of
+.B SANE_CONFIG_DIR
+below).
+.TP
+.I @CONFIGDIR@/saned.users
+If this file contains lines of the form
+
+user:password:backend
+
+access to the listed backends is restricted. A backend may be listed multiple
+times for different user/password combinations. The server uses MD5 hashing
+if supported by the client.
+.SH ENVIRONMENT
+.TP
+.B SANE_CONFIG_DIR
+This environment variable specifies the list of directories that may
+contain the configuration file.  Under UNIX, the directories are
+separated by a colon (`:'), under OS/2, they are separated by a
+semi-colon (`;').  If this variable is not set, the configuration file
+is searched in two default directories: first, the current working
+directory (".") and then in @CONFIGDIR@.  If the value of the
+environment variable ends with the directory separator character, then
+the default directories are searched after the explicitly specified
+directories.  For example, setting
+.B SANE_CONFIG_DIR
+to "/tmp/config:" would result in directories "tmp/config", ".", and
+"@CONFIGDIR@" being searched (in this order).
+
+.SH "SEE ALSO"
+.BR sane (7),
+.BR scanimage (1),
+.BR xscanimage (1),
+.BR xcam (1),
+.BR sane\-dll (5),
+.BR sane\-net (5),
+.BR sane\-"backendname" (5)
+.br
+.I http://www.penguin-breeder.org/?page=sane\-net
+.SH AUTHOR
+David Mosberger