README
======

socket2unix is a simple 'LD_PRELOAD' wrapper to ``convert'' network sockets to
UNIX sockets. Useful on remote systems with untrusted users (but trusted root)
to be able to launch a server which is accessible only by the user. Normal
sockets are usable by everyone on the system.

It works for both servers (`listen(3)`) and clients (`connect(3)`).

These UNIX sockets can also be forwarded over SSH with `socat` (see below).


DEPENDENCIES
------------

- C99 compiler
- dynamic linker/loader which supports 'LD_PRELOAD' (e.g. GNU/Linux's or
  FreeBSD's ld.so)


INSTALLATION
------------

    ./configure && make && make check

Then either install the library with `make install` or just copy it from
`src/.libs/` to wherever you want to install it:

    rm -f /destination/path/for/library/libsocket2unix.so
    cp -L src/.libs/libsocket2unix.so /destination/path/for/library/

*Important:* Don't overwrite an existing `libsocket2unix.so` file which is in
use by any program or the program may crash. Instead remove the file first and
then copy the new version. This is not a bug in socket2unix, but a general
problem.


USAGE
-----

Set 'LD_PRELOAD' to include the _absolute_ path to `libsocket2unix.so`:

    LD_PRELOAD=/absolute/path/to/libsocket2unix.so

The 'SOCKET2UNIX_PATH' environment variable must be set to the path of the
UNIX socket to use (client) or create (server). The IP version ("v4" or "v6")
and the port number (if applicable) is appended to create a unique path.


Example (server):

    $ LD_PRELOAD=/path/to/libsocket2unix.so \
        SOCKET2UNIX_PATH=`pwd`/test nc -l -p 5000

This creates two sockets named `socket-v4-5000` and `socket-v6-5000` in the
current directory. If the files already exist and are sockets, they are
overwritten. Other file types are not touched.

Example (client):

    $ LD_PRELOAD=/path/to/libsocket2unix.so \
        SOCKET2UNIX_PATH=`pwd`/test nc localhost 5000

`nc` connects to the server socket created above and both instances can talk
to each other without knowing they use an UNIX socket instead of a TCP
connection on port 5000.


The following additional environment variables are available:

- 'SOCKET2UNIX_DEBUG':
  Control debug level. 1 = errors only, 2 = warnings only, 3 = debug messages.
  Default: 2
- 'SOCKET2UNIX_OPTIONS':
  Comma separated list of options for socket2unix. Valid options are (without
  quotes):
  - 'client_only': Don't intercept calls to `listen()` and `accept()`.
  - 'server_only': Don't intercept calls to `connect()`.
    These options are useful if a program has both client and server
    functionality but only one part should be redirected.


EXAMPLES
--------

`socat` can be used to forward UNIX sockets over SSH. Thanks to [1] for the
necessary commands.

[1]: http://www.debian-administration.org/users/dkg/weblog/68

`socat` is required on both local and remote system.

To forward the server socket `path/to/socket/remote` from `remote-host` to
`path/to/socket/local` on the local host run this command on the local system:

    $ socat UNIX-LISTEN:path/to/socket/local,reuseaddr,fork \
        EXEC:'ssh remote-host socat STDIO UNIX-CONNECT\:path/to/socket/remote'

Any program on the local host can then connect to `path/to/socket/local` and
the connection gets forwarded to `remote-host`.

To use the forwarding with socket2unix the sockets must be named appropriately
(see above). For example to use socket2unix on the client-side:

    $ socat UNIX-LISTEN:socket-v4-4711,reuseaddr,fork ...

Connect to the forwarded socket:

    $ LD_PRELOAD=/path/to/libsocket2unix.so \
        SOCKET2UNIX_PATH=`pwd`/socket nc -4 localhost 3000

The same works for the remote socket.


BUGS
----

If you find any bugs not mentioned in this document please report them to
<simon@ruderich.org> with socket2unix in the subject.


AUTHORS
-------

Written by Simon Ruderich <simon@ruderich.org>.


LICENSE
-------

socket2unix is licensed under GPL version 3 or later.

Copyright (C) 2013  Simon Ruderich

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.