rpm and deb packages
====================

These are not the same packages as the ones from various distributions'
repositories. They carry an internal higher revision level in order to
prevent them from getting upgraded by the distribution packaging. This
packaging exists in order to have a convenient way of updating after a
release without waiting for the distribution's package to get built.

NOTE: If a distribution package is already installed it should be removed
completely before switching to the upstream version (dnf remove or apt
purge). Preserve any existing configuration files, beforehand, in order to
reconfigure the package

NOTE: These packages use their own, generic, installation layout that may
deviate slightly from the package installation conventions preferred by
the distributions.

rpm
===

It is not necessary to unpack this tarball in order to build this tarball.

Run "dnf install rpm-build", if it's not installed already, then:

$ rpmbuild -ta courier-sox-VERSION.tar.bz2

If this fails due to any missing dependencies, install them.

This creates rpms that can be installed with 'rpm -U':

- the main "courier-sox" package installs configuration files, scripts, and
  shared libraries

- the "courier-sox-server" package installs the Socks server.

- The "courier-sox-deve;" package installs development libraries and header
  files for building software that uses the Socks library.

- The "courier-sox-utils" package installs an additional script that has
dependencies on other Perl modules.

Rocky/RHEL 8 notes
------------------

Courier packages require at least C++17 support, but the default version
of gcc does not fully support it, and a newer gcc is needed:

$ dnf install --enablerepo=crb -y gcc-toolset-14
$ scl enable gcc-toolset-14 "rpmbuild -ta courier-sox-VERSION.tar.bz2"

deb
===

Run "apt install devscripts debhelper", if it's not installed already, then:

Create an empty directory, and copy/move the tarball into it:

$ mkdir tmp
$ cp courier-sox-VERSION.tar.bz2 tmp/courier-sox-VERSION.orig.tar.bz2
$ cd tmp

Unpack the tarball and cd into the unpacked subdirectory:

$ tar xvf courier-sox-VERSION.tar.bz2
$ cd courier-sox-VERSION

Run the courier-debuild script. Its parameters get forwarded to debuild.

$ ./courier-debuild -us -uc

NOTE: the above sequence must be followed strictly. The courier-debuild
script expects the distributed tarball in its parent directory.

The deb subdirectory now contains *deb packages that can be installed with
"dpkg -i":

- The "libcourier-sox" package installs configuration files and scripts.

- The "libcourier-sox" package installs the Socks server.

- The "libcourier-soxN" package installs shared libraries.

- The "libcourier-sox-dev" package installs development libraries and header
files for building software that uses the Socks library.

- The "libcourier-sox-utils" package installs an additional script that has
dependencies on other Perl modules.

   NOTE: All Courier packages should be built with the same version of gcc,
   which is selected by the DEBGCC environment variable before running
   courier-debuild. See courier-unicode's INSTALL for more information.

Ubuntu 20
---------

Courier packages require at least C++17 support, but the default version
of gcc does not fully support it, and a newer gcc is needed:

$ sudo apt install -y gcc-10 g++-10
$ DEBGCC=10 ./courier-debuild -us -uc

Maintainer Mode (see README in the git repository to set up)
============================================================

make rpm or make deb, as appropriate, will:

    1. Increment an internal release number.

    2. Run make dist.

    3. Proceed and build a new release, creating the native packages in the
       rpm or deb subdirectory.

    4. Execute either $HOME/bin/rpmrepos.sh or $HOME/bin/debrepos.sh. This
       can be a script that does nothing, or it's intended to be the
       maintainer's script that pushes out the packages to a repository.


Manual installation
===================

You need to install the following software before building this package
(if it's not already installed).

GNU make (gmake)
GNU libtool
Courier Authentication Library (https://www.courier-mta.org/authlib).
Net::CIDR Perl module from www.cpan.org (required for blacklist support)

This package uses the GNU toolchain, and uses the typical installation
sequence:

./configure [option]
make
make install

GNU libtool must be installed prior to installing this package. Also,
the libtool's libltdl library must be installed, together with its development
headers. On some platforms this is a separate package. On Fedora, for example,
this is the libtool-ltdl-devel package.

Q: Do I need to install the Courier Authentication Library even if I will
use only anonymous Socks 5 proxy connection, and don't need authentication?

A: Yes.  Courier-sox uses some utilities in the courier-authlib package
(specifically, courierlogger).  You need courier-authlib installed on any
machine used to build courier-sox.  You will also need courier-authlib
installed on a machine that runs server daemon, sockd.  Courier-authlib
is not required to be installed on a machine that only uses the client-side
libraries (but courier-authlib still needs to be installed when building
this package, in all cases).

If you don't need authentication, you still need to have courier-authlib
installed on a machine that's running the server daemon, sockd.  You don't
need to actually start the courier-authlib daemon process.

NOTE: The Courier authentication library communicates authentication requests
through a filesystem socket that's created in a directory without global
access rights (the default location is /usr/local/var/spool/authdaemon,
or /var/spool/authdaemon).  Only the userid that's reserved by courier-authlib
can access this directory (typically "courier" or "daemon").

The server daemon therefore has to be run as a userid or groupid that has
permissions to access the filesystem socket. With courier-authlib's default
configuration, add "user nobody" and "group daemon" to the socksrc
configuration file or directory (see the socksrc man page for more
information). Running sockd as user nobody and group daemon should be
sufficient, as the courier-authlib socket's default permissions are
accessible to the daemon group.

The other alternative is to manually change the permissions on the socket
directory to 755.  Note that the courier-authlib daemon provides access to
account passwords, and this approach will expose account passwords to anyone
with a shell account (which is a non-issue if the server does not provide
generic shell access).

It is the system administrator's responsibility to choose the appropriate
security policy with using the Courier Authentication Library, and the
socks server.

Note that this is an issue that's particular to the Socks 5 server component.
This issue is moot when only the client library of the Courier Socks 5
package is used.

NOTE: When using the Courier Authentication Library with PAM authentication,
authentication requests from courier-sox will be sent as the "socks" service.
Your PAM library needs to be explicitly configured to authenticate the
"socks" service.  There are different PAM libraries, that use different
ways to configure PAM services.  In most situations you need to install
/etc/pam.d/socks.  On modern Linux systems, this file's typical contents would
be:

#%PAM-1.0

auth       required     pam_nologin.so
auth       required     pam_stack.so service=system-auth
account    required     pam_stack.so service=system-auth
session    required     pam_stack.so service=system-auth

Check your PAM library's documentation for more information.

The default options to the configure script will:

* Install the Socks 5 client libraries in /usr/local/lib,
  called "libsocks.so" and "libsockswrap.so" (actual names vary, depending
  on your system).

* The socksify and mkbl4 scripts in /usr/local/bin

* A lone header file: /usr/local/include/socks.h

* A couple of manual pages in /usr/local/man

* The configuration directory /usr/local/etc/socksrc will be created

* The server daemon, /usr/local/libexec/sockd, and its startup helper
script, /usr/sbin/sockd

The usual options may be used to change these filenames (--prefix,
--exec-prefix, etc...)

If you are not familiar with the GNU toolchain options, run ./configure --help
for a summary.

Use the following procedure to verify that the Socks library was correctly
installed.

* Run 'make check' (this doesn't do much, yet, but every little bit helps)

* If you want to test the Socks client library against the Socks server
itself, create a second installation of the Courier Sox library on the
firewall, see "The socks server" below for more information.

Otherwise you can configure the client library to talk to some other,
existing Socks server:

* Set up your Socks 5 client configuration in /usr/local/etc/socksrc according
to the socksrc man page.

The following test programs will be built in the source code directory, but not
installed:

* Run 'testconnect HOSTNAME', where HOSTNAME is a well-known web server
(www.yahoo.com, www.cnn.com, and the like, are good choices).

testconnect tries to connect to the web server at the given address and
display its robots.txt file.  If all goes well, you should see the robots.txt
from the web server (or a 404 message if the server does not have a
robots.txt file).

* Run 'testbind' as root.  testbind attempts to reserve a privileged port on
the local machine, then open the same port on the Socks server.  If all goes
well 'testbind' will print the local port number, then the Socks server's IP
address and the port number it opened on the Socks server:

port 1023
Real port: 0.0.0.0;1023
Listening on: 192.168.0.15;47683

Not all Socks servers have the ability to reserve the same privileged port
that the Socks client reserved locally.  It's possible that the second message
from 'testbind' will show that its listening on a non-reserved port.

After 'testbind' displays the Socks server's IP address and the port, it
will wait for an incoming connection.  Use 'telnet' to connect to the
indicated IP address and port:

telnet 192.168.0.15 47683

(Note: it is possible that the shown IP address may not be reachable via TCP
from this machine.  This is outside the scope of the test.  The 'telnet'
connection does not have to originate from the same machine that's running
testbind.  Use any appropriate machine to connect to the listening port.)

After the connection goes through, anything typed in telnet should be
printed by testbind (the reverse isn't true, after the connection is
established testbind enters a simple loop where it prints everything received
on the socket, until it is closed).

* If the above tests succeed, chances are that everything is working correctly.
For the final example, pick a well known FTP server, and try to use the
socksify script with the ftp command:

socksify ftp ftp.example.com

You should be able to establish an FTP connection, and log in.  You should be
able to use the 'dir' command in both the active and passive FTP modes,
as well as transfer files.


The socks server

The server startup/shutdown script is, by default, installed in
/usr/local/sbin.  To start the server: /usr/local/sbin/sockd start

To stop the server: /usr/local/sbin/sockd stop

Also: /usr/local/sbin/sockd restart - reread the configuration file.
The server reads the updated "port", "anonproxy", "authproxy", and "prefork"
settings from the configuration file (default: /usr/local/etc/socksrc).
Any other changes in the configuration file only take effect by stopping and
starting sockd.

See the socksrc(5) and sockd(8) man pages for more information.

Add the start command to your system startup script to have the socks server
automatically start at system boot time.

Use the courier-sox.sysvinit script (not installed, take it from the source
directory) as an example of a SysV init script.
