%@(#)$Id: faq.tex,v 1.50 2003/07/15 15:45:55 karls Exp $
%/*
% * Copyright (c) 1997, 1998, 1999, 2000, 2001
% *      Inferno Nettverk A/S, Norway.  All rights reserved.
% *
% * Redistribution and use in source and binary forms, with or without
% * modification, are permitted provided that the following conditions
% * are met:
% * 1. The above copyright notice, this list of conditions and the following
% *    disclaimer must appear in all copies of the software, derivative works
% *    or modified versions, and any portions thereof, aswell as in all
% *    supporting documentation.
% * 2. All advertising materials mentioning features or use of this software
% *    must display the following acknowledgement:
% *      This product includes software developed by
% *      Inferno Nettverk A/S, Norway.
% * 3. The name of the author may not be used to endorse or promote products
% *    derived from this software without specific prior written permission.
% *
% * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
% * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
% * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
% * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
% * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
% * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
% * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
% * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
% * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
% * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
% *
% * Inferno Nettverk A/S requests users of this software to return to
% *
% *  Software Distribution Coordinator  or  sdc@inet.no
% *  Inferno Nettverk A/S
% *  Oslo Research Park
% *  Gaustadalléen 21
% *  NO-0349 Oslo
% *  Norway
% *
% * any improvements or extensions that they make and grant Inferno Nettverk A/S
% * the rights to redistribute these changes.
% *
% */

\documentclass[a4paper, final, twoside, english]{article}
\usepackage[latin1]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{babel}
\usepackage{html}
\usepackage{url}

\title{Dante FAQ}
\author{
	Inferno Nettverk A/S \\
	Oslo Research Park   \\
	Gaustadalléen 21   \\
	NO-0349 Oslo          \\
	Norway}
\date{$$$$Date: 2003/07/15 15:45:55 $$$$}

\makeindex

\begin{document}

\maketitle

 \begin{center}

  \emph{See
   \htmladdnormallink{
	http://www.inet.no/dante/FAQ/}{http://www.inet.no/dante/FAQ/} for the
	latest version of this faq.}

   Send updates/corrections to the public mailinglist dante-misc@inet.no.
  \end{center}

\section{Reporting problems or bugs in Dante}

 \subsection{Why was I told to read this in response to my superb
  problem/bug report?}
  Because you were unable to provide a usable report.  Since
  there are so many of you, we prefer to refer you to this FAQ rather
  than repeating ourselves over and over.

 \subsection{Why is "it does not work" not a good report?}
  It's a common misconception among users who have never done any
  programming that by stating something along the lines of "it does
  not work", or "I get a segmentation fault" (these are real examples,
  believe it or not), the programmers at Inferno Nettverk will without
  a shred of doubt be able to pin-point that one line, that one line
  among the thousands of other lines, responsible for it "not working"
  or "segmentation faulting".

  The fact is, any one of the tens of thousands of lines could be
  the "bad" line, we don't have time to re-read them all each time
  we get a "it does not work" message.

 \subsection{How can I provide you with the information you need?}
  First of all, look in the config file you are using.
  If you are using the Dante client, it's /etc/socks.conf.
  If you are using the Dante server, it's /etc/sockd.conf.
  Both files contain by default the lines "logoutput:".  Set "logoutput:"
  to some file that Dante can log output to.

  If the problem is with the client, also uncomment the line containing
  "debug".
  If the problem is with the server, also add "-d" to whatever
  arguments you usually start the server with.

  Repeat whatever you did to produce the error and look at the
  log messages.  Do they provide any hints?

  If it looks like a user error, you configured something wrong, etc.
  you can try sending a mail to dante-misc@inet.no, a public mailing
  list where someone might be kind enough to help you if you formulate
  your question in a understandable way.
  And remember, unless you are a customer of Inferno Nettverk, no one
  owes you any support or help, you are the one asking someone to
  spend their time to help you, not the other way around.

  If it looks like a bug, first perform the following step:
  \begin{enumerate}
   \item{} Make sure that you are using the latest
      version of Dante, even if the latest version is a "prerelease"
      and you are using official release.  Always check
      ftp.inet.no:/pub/socks/ to see if there's a later version
      before sending a bugreport.

  Next, depending on whether the suspected bug is in the client
  or sever, do one of the following:

   If it's a bug in the client:
  \begin{enumerate}
    \item{} Compile the program you are trying to socksify with the compiler
       option "-g".
    \item{} Compile Dante with "-g" (--enable-debugging option to configure).
    \item{} Set debug and logoutput as described above.
    \item{} cp /dev/null <logoutput file> (to make sure it's empty.)
    \item{} ktrace/truss/strace/<whatever> socksify <bad program>.
     Save the output to a file.  If you have a program that can
     trace library calls too (late version of Solaris truss and redhat
     Linux apparently do), please include information about that too.
    \item{} If a coredump was generated do
  \begin{verbatim}
	$ gdb <bad program> <coredump>
	(gdb) backtrace 50
  \end{verbatim}

   Save the output to a file.
  \end{enumerate}

   If it's a bug in the server:
  \begin{enumerate}
   \item{} Compile Dante with "-g" (--enable-debugging option to configure).
   \item{} Set debug and logoutput as described above.
   \item{} cp /dev/null <logoutput file> (to make sure it's empty.)
   \item{} If the server crashed/exited due to the bug, a coredump should
	be generated.  If you do not find a coredump in the directory
	you started the Dante server from you need to find out why.
	Some possible reasons are:
	a) your shell has disabled coredumps (check what ulimit(1))
	says.
	b) some systems by default disable coredumps on
	processes that are either setuid, or that are run by root.

    When you have found the coredump do
  \begin{verbatim}
	$ gdb <Dante server> <coredump>
	(gdb) backtrace 50
  \end{verbatim}
       Save the output to a file.
  \end{enumerate}

  Then:
    \item{} In addition to the server/client specific files mentioned below,
      include the output from configure and the file "include/autoconf.h".

    \item{} Collect the output from configure and the file include/autoconf.h,
       the <logoutput file>, gdb/ktrace/truss/strace/whatever output
       in a orderly fashion so it's easy to read and understand, and
       send it to us.  Make sure you include information about what
       all the IP addresses in the logfiles are (10.0.0.1 is "client
       using lynx", 10.0.0.2 is "remote webserver", etc.).

       The address to use for Dante bugs is dante-bugs@inet.no.  See
       the BUGS file coming with Dante.

    \item{} If you have the possibility to create a temporary account for
       one of the Dante developers in the case we are unable to
       reproduce the error on our own systems, please mention that
       in the bugreport (but don't create the account until we ask
       for it, we rarely need it).
  \end{enumerate}

\section{System installation}
 \subsection{How do I configure the client?}
  \subsubsection{Setting up the configuration file}

  The configuration file is usually called \emph{/etc/socks.conf} and
  needs information about where the server can be found. To configure
  it follow these easy steps:

  \begin{enumerate}

   \item Read the manual page (\emph{socks.conf}). It can also be found
     \htmladdnormallink{online}{http://www.inet.no/dante/doc/socks.conf.5.html}.

   \item Read the manual page again.

   \item Determine the IP address and port of the socks server you
	 wish to use.
   \item If the server uses anything but socks version 5 you should
	 probably also determine this.
  \end{enumerate}


 Lets assume that server is at address is 10.1.1.1, port 1080 and that
 it is a normal socks server (such as Dante) which supports socks
 version 5.

 You would then enter the following in \emph{/etc/socks.conf}:
 \begin{verbatim}
route {
       from: 0.0.0.0/0   to: 0.0.0.0/0   via: 10.1.1.1 port = 1080
       proxyprotocol: socks_v5
}
 \end{verbatim}

The Dante socks library should now be able to connect to the socks
server.

 \subsubsection{It doesn't work}

If it doesn't work you might wish to add the lines below to the
beginning of the file. When you try again you should get more
information about what is happening, which will hopefully help you
determine what the problem is:

\begin{verbatim}
debug: 1
logoutput: stdout
\end{verbatim}

 \subsubsection{I want to do something more complicated}

 Reading the
 \htmladdnormallink{manual page}{http://www.inet.no/dante/doc/socks.conf.5.html}
 is a good start. Then have a look at the example configuration-files
 found in the archive (and via \htmladdnormallink{ftp}{ftp://ftp.inet.no/pub/socks/extracted/example/}).

 \subsection{How do I set up the server?}

  \subsubsection{Creating a simple server configuration file}
 Setting up the server is not significantly more difficult than
 setting up the client. The server usually uses the filename
 \emph{/etc/sockd.conf}. To configure the server follow these easy
 steps:

  \begin{enumerate}
   \item Read the manual pages (\emph{sockd.conf} and
     \emph{sockd}). They can also be found
     \htmladdnormallink{online}{http://www.inet.no/dante/doc/}.

   \item Read the manual pages again.

   \item Find out the name or IP address of the interface on the
	 internal side of the network.

   \item Find out the name or IP address of the interface(s) on the
	 external side of the network.

   \item Determine which networks (address/netmask pair) you wish to
	 allow to connect to the server.

   \item Determine if you wish to use or need any special
	 authentication to use the server. If not, the server will
	 most likely not need to be started as root.

   \item Create a user (e.g. \emph{sockd}) which the server can run as
	 when it doesn't need to perform privileged operations. Using
	 \emph{nobody} is not recommended.

   \item Determine what users will be allowed to do via the server
	 (i.e. which ports should they be allowed to use).

  \end{enumerate}

Armed with this knowledge you can now start writing the configuration
file. It generally consists of tree parts:

\begin{itemize}
 \item General configuration; setting external interfaces etc.
 \item Client access rules; who is allowed to connect to the server
 \item Client usage rules; what users can do when they have connected
\end{itemize}

Let's start with the general rules:

\begin{verbatim}
internal: fxp0 port = 1080
external: fxp1
method: username none
#user.privileged: root
user.notprivileged: sockd
logoutput: stderr
\end{verbatim}

This sets the internal and external interfaces and which users should
be used by the server. It allows users to connect with username
authentication, but allows access without authentication. Running as
root might not be necessary if you do not use any authentication
methods.

Then we add the client access rules. These are placed after the first
lines.

\begin{verbatim}
client pass {
	from: 10.1.1.0/24 to: 0.0.0.0/0
	log: connect disconnect
}
\end{verbatim}

These lines allow clients on the 10.1.1.0 network to connect to any
external address. The server logs connects and disconnects.

Finally we add the access rules. This example does not place any
limits upon usage of the server.

\begin{verbatim}
#allow bind to ports greater than 1023
pass {
	from: 0.0.0.0/0 to: 0.0.0.0/0 port gt 1023
	command: bind
	log: connect disconnect
}

#allow outgoing connections (tcp and udp)
pass {
	from: 0.0.0.0/0 to: 0.0.0.0/0
	command: connect udpassociate
	log: connect disconnect
}

#allow replies to bind, and incoming udp packets
pass {
       from: 0.0.0.0/0 to: 0.0.0.0/0
       command: bindreply udpreply
       log: connect error
}

#log the rest
block {
       from: 0.0.0.0/0 to: 0.0.0.0/0
       log: connect error
}
\end{verbatim}

These lines allow all clients (which have been allowed to connect) to
use the socks \emph{bind}, \emph{connect} and \emph{udpassociate}
operations. This gives users full access through the socks server;
clients can bind ports on the server (and receive replies), connect
with TCP through the server, and send (and receive) UDP packets.

The \emph{bind} command is typically used by \emph{ftp} clients (using
active ftp), and the first pass command allows clients to bind a port
(above 1023) on the server.

The second pass command allows outgoing traffic; \emph{connect}
operations (TCP) and transmission of UDP packets.

The third \emph{pass} command controls \emph{replies}; this might be
the reply to a bind request or it may be the reply to a UDP-packet,
since UDP is packetbased.  Note that nothing is done to verify that
it's a \emph{genuine} reply, that is in general not possible anyway.

The \emph{block} command at the end ensures that operations that do
not match any of the above are logged. In the above configuration
there will likely not be many blocked operations since the commands
are very liberal in what they allow. The same result could have been
achieved much simpler by a single \emph{pass} command. The structure
above has been used to make it simpler to make modifications. By
changing the networks matched in the \emph{from} and \emph{to}
commands above it is possible to limit operations to specific subnets,
only allow outgoing connections to some addresses etc.

The complete sockd configuration file should now look like this:

\begin{verbatim}
## general configuration

internal: fxp0 port = 1080
external: fxp1
method: username none
#user.privileged: root
user.notprivileged: sockd
logoutput: stderr

## client access rules

client pass {
	from: 10.1.1.0/24 to: 0.0.0.0/0
	log: connect disconnect
}


## server operation access rules

#allow bind to ports greater than 1023
pass {
	from: 0.0.0.0/0 to: 0.0.0.0/0 port gt 1023
	command: bind
	log: connect disconnect
}

#allow outgoing connections (tcp and udp)
pass {
	from: 0.0.0.0/0 to: 0.0.0.0/0
	command: connect udpassociate
	log: connect disconnect
}

#allow replies to bind, and incoming udp packets
pass {
       from: 0.0.0.0/0 to: 0.0.0.0/0
       command: bindreply udpreply
       log: connect error
}

#log the rest
block {
       from: 0.0.0.0/0 to: 0.0.0.0/0
       log: connect error
}
\end{verbatim}

This was a simple example to get you started. As you probably noticed
when you read the manual page the server can do a lot more.

Remember to test your configuration before you put it into production
usage. When you are sure that the server works you might wish to
redirect the logoutput to a file (by changing the \emph{logoutput}
command).

 \subsection{Where can I find configuration file examples?}

 Several examples are included in the archive. They can also be
 downloaded via
 \htmladdnormallink{ftp}{ftp://ftp.inet.no/pub/socks/extracted/example/}.

 \subsection{SuSE 7}
	\begin{enumerate}
	 \item{} Install the Dante package from SuSE (Version 1.1.2 is included
		 in SuSE 7)
	 \item{} Edit the /etc/rc.config and set the line START\_SOCKD="yes"
	 \item{} Edit the config file /etc/sockd.conf and reboot Linux (or
		 start sockd -D if you know what you are doing).
	      Be sure that you have one client pass rule which allows
	      you client to connect from your internal network and
	      one pass rule that allows a client that is connected
	      to use the proxy to the desired destinations (this
	      is most likely to everywhere = 0.0.0.0/0 )

	  \end{enumerate}
   \emph{Thanks to: Andreas John <dante@systemdesign.net>}

\section{How can I socksify the whole system?}
 On some systems doing the global equivalent of running a program with
 socksify is possible. You should however not do this unless you know
 what you are doing.

 \subsection{Linux}
  In Linux you can easily do the following:
  \begin{verbatim}
   edit the file /etc/ld.so.preload
   and add two lines saying:
      libdl.so
      libdsocks.so
  \end{verbatim}
 \emph{Thanks to: Dag Wieers <dag@wieers.com>.}

 Dag Wieers also has a (RedHat) SPEC file which contains scripts for
 doing this automatically. It can be found at:
 \htmladdnormallink{ftp://dag.wieers.com/home-made/dante/dante.spec}{ftp://dag.wieers.com/home-made/dante/dante.spec}

 \subsection{Generic}
  There is another way that gives you more control over what will and what
  will not be socksified. Instead of using the wrapper-script 'socksify',
  you could add

  \begin{verbatim}
   LD_PRELOAD="libdl.so libdsocks.so"
   export LD_PRELOAD
  \end{verbatim}
  to the environment. (/etc/profile ~/.profile ~/.bashrc)
  \\ \emph{Thanks to: Dag Wieers <dag@wieers.com>.}

  \subsubsection{Why do I want to be able to control this?}
   In same rare cases programs fail to work in a socksified environment
   (e.g. acroread 4.0 for Linux segfaults) or programs like rpm depend on a
   clean build-environment to get its (library) dependencies.
   \\ \emph{Thanks to Dag Wieers <dag@wieers.com>.}


 \subsubsection{How can I easily unsocksify the current shell?}
  By issuing
  \begin{verbatim}
   unset LD_PRELOAD
  \end{verbatim}
  \emph{Thanks to: Dag Wieers <dag@wieers.com>.}


\section{Technical Problems}
 \subsection{Why doesn't the socksify program work with glibc-2?}
  If glibc is not correctly installed (old header files are still
  installed) socksify won't work if logging is enabled. The server will
  also crash when it exits. Upgrade the header files (/usr/include) and
  compile again.

 \subsection{Why doesn't socksify work on cvs?}
  It does work.  A problem however is that cvs usually ends up calling
  a setuid program (rsh, ssh, whatever).  See section~\ref{setuid}.

 \subsection{Why doesn't socksify work on setuid programs like ssh, rsh, etc?}
  \label{setuid}
  The reason is that these programs are setuid.  Most systems will
  ignore the work socksify has done before running these programs and
  the result becomes the the same as not using socksify on them.

  Solution: strip off the suid bit if possible or recompile the binary
  (rsh, ssh, etc) with explicit socks support (adding "-ldsocks"
  to the linkoptions is usually enough.)

 \subsection{Why doesn't socksify work on HP-UX 11.00?}
  You might have to install patch \emph{PHSS\_22478}, or one of its
  successors, which adds \emph{LD\_PRELOAD} support to the loader.

  \emph{Thanks to: albert chin (china@thewrittenword.com)}

 \subsection{Why do I get undefined references to \_\_bswap\_32 during
   compilation on Linux?}
  This is likely due to a bug in one of the system header files. A
  workaround has been added in version 1.1.14.

 \subsection{How do I setup a password file for authenticating users?}
  The Dante server uses the standard system passwordfile.
  Put the server in a chroot jail to manage a separate passwordfile.

 \subsection{How can I more easily get the Dante server to work when the
		  external interface is using dynamic IP addresses?}

   Either specify the external address as a interfacename (available
   since Dante v1.1.7), in which case the Dante server will
   automatically use the new address whenever it changes, or if you
   must use a IP address, try the below.


   Automatically running a script that changes the "external:" line
   in your sockd.conf and then sends the server a SIGHUP when you get
   a new address should be simple enough though.

   A example of such a script is the following, modify to suit.

   \begin{verbatim}
    #!/bin/sh -
    #
    # usage: script.sh <new external ipaddress>

    : {SOCKD_CONF='/etc/sockd.conf'}

    if [ ! -w ${SOCKD_CONF} ]; then
       echo "${SOCKD_CONF} does not exist or is not writable"
       exit 1
    fi

    ex - +'1,$s/^external:.*/external: '$1'/ | wq' ${SOCKD_CONF}
    kill -HUP `cat /var/run/sockd.pid`
   \end{verbatim}

    As you see, this is intended to be called as "<scriptname>
    <external ip>", where <external ip> is your external ip.  We
    assume you can easily get the external ip from your ppp script.
   \emph{Thanks to: Tin Yu Mak <makty@usa.net>.}

 \subsection{I have problems rotating Dante's logfiles.  What can I do
	     except log via syslog?}

   Making Dante reopen the logfiles on SIGHUP would be a way to
   provide support for this.  That however involves adding more
   code to Dante, code that in practice duplicates code that
   already exists in syslog.  Since Dante opens the logfiles in
   appendmode the below may work.

   A quick and dirty solution for dealing with most daemons that
   don't like having their logs rotated. Copy them instead of moving
   the files and then redirect an echo into them. Kick it off via
   cron every day at 11:59.  I get 7 days of rotated logs like this:

   \begin{verbatim}
    sleep 60
    DAY=`date +%a`
    cp /var/log/banned.log /var/log/banned.log.${DAY}
    echo > /var/log/banned.log
   \end{verbatim}
   \emph{Thanks to: James Coe <starascendant@hotmail.com>.}

Another solution:

I use dante under supervise with multilog for log rotation (based on
size, not date).  This will run Dante under supervise (and limit its
memory usage to 5 megabytes) and redirect its logging to
/var/log/dante/current, rotated based on its size.

\url{http://cr.yp.to/daemontools.html}{http://cr.yp.to/daemontools.html}
for more information.

\begin{verbatim}
   /service/dante/run:

#!/bin/sh

exec 2>&1
exec softlimit -m 5000000 -p 30 -c 0 \
         /usr/sbin/sockd -f /etc/sockd.conf -N 1 -l # -d

/service/dante/log/run:

#!/bin/sh

exec setuidgid logging multilog t /var/log/dante
\end{verbatim}
   \emph{Thanks to: Michael T. Babcock" <mbabcock@fibrespeed.net>}


\section{Authentication}
 \subsection{How do I use LDAP authentication with Dante?}

  First, make sure that you compile Dante with support for PAM.  The
  configure script should do this for you if the PAM development libraries
  are installed.  Under RedHat Linux, make sure you have the PAM-devel RPM
  installed.
  
  You will also have to add LDAP support to your PAM implementation, if it
  is not already there.  Check if you have /lib/security/pam\_ldap.so or
  the equivalent. If not, use pam\_ldap from
  \htmladdnormallink{http://www.padl.com/}{http://www.padl.com/}.  
  
  pam\_ldap gets its configuration from /etc/ldap.conf.  Make sure you set
  host to your LDAP server, and base to your base DN.You can also set
  pam\_filter and pam\_group\_dn to restrict logins to particular objecttypes
  or members of particular groups.
  
  Point sockd at LDAP by creating /etc/pam.d/sockd.  An exapmle of this
  files contents is;

  \begin{verbatim}
  #%PAM-1.0
  auth       sufficient /lib/security/pam_ldap.so
  auth       required   /lib/security/pam_unix_auth.so try_first_pass
  account    sufficient /lib/security/pam_ldap.so
  account    required   /lib/security/pam_unix_acct.so
  password   required   /lib/security/pam_ldap.so
  \end{verbatim}
  
  Finally, you need to configure sockd.conf to restrict access based on
  PAM.  this is accomplished with the following:
  
  \begin{verbatim}
  # allowable authentication methods for socks-rules.
  # values are username, none, rfc931 and pam
  method: pam none
  
  # allowable authentication methods for client-rules.
  # values are username, none, rfc931 and pam
  clientmethod: pam none
  
  # Client rules, controls who may connect
  #
  ## everyone who authenticates is allowed to use tcp
  ## and udp
  pass {
         from: 0.0.0.0/0 to: 0.0.0.0/0
         protocol: tcp udp
         log: connect disconnect error
         method: pam
  }
  
  # last line, block everyone else.  This is the default but if you
  provide
  # one  yourself you can specify your own logging/actions
  block {
         from: 0.0.0.0/0 to: 0.0.0.0/0
         log: connect error
  }
  \end{verbatim}

  \emph{Thanks to: Sean Burford <sean.burford@adelaide.edu.au>.}

  \subsubsection{... and against Microsoft Active Directory?}
   To authenticate against a Microsoft Active Directory the following bare
   minimum example configuration for 'test.org' with an active directory
   server
   at 123.123.123.123 of /etc/ldap.conf Directory is what you would
   require:
   
	\begin{verbatim}
   host 123.123.123.123
   base cn=Users,dc=test,dc=org
   rootbinddn cn=Administrator,cn=Users,dc=test,dc=org
   pam_filter objectclass=user
   pam_login_attribute cn
	\end{verbatim}
   
   With the password for the Administrator user in the file
   /etc/ldap.secret and chowned to 0600.


   \emph{Thanks to: Alexander Cohen <A.Cohen@latrobe.edu.au>.}

\end{document}