USOCKSD(1)

NAME
usocksd - user specific SOCKS5 daemon

SYNOPSIS
usocksd [ -p port ] [ -a accepthost ] [ -u udphost ] [ -i identuser ] [ -U authuser ]

DESCRIPTION
usocksd is a lightweight SOCKS5 daemon. It is intended to be run by the user who wants to use the SOCKS service and facilitates the use of an ssh TCP port redirection to run the SOCKS protocol over. usocksd is useful in situations where the user has access to a host with less restricted connectivity than his own machine, or where the user's own machine is on an insecure network and all connections should be encrypted. usocksd implements all documented commands, the address types IPv4 Address and Domain Name (for domain names that resolve to IPv4 addresses) and the authentication methods No Authentication and Username/Password.

OPTIONS

-p port
    Port to listen on for connections. On a multi-user system, each user has to specify his own port instead of relying on the standard port. Default is 1080, nonetheless.

-a accepthost
    Specify that connections are only accepted from this host. Default: no restriction. It is possible to specify more than one allowed host, they have to be separated with a comma (and nothing else). Hosts are given either as IP address or as resolvable name.

-u udphost
    Specify that UDP packets to be relayed come from this host instead of the default (the connecting host). Why this violation of RFC 1928 is necessary is explained below under "Usage". It is possible to specify more than one host.

-i identuser
    Specify that for each incoming connection an identd query will be made and the connection rejected if it does not resolve to the given user name. Note that identd is not a reliable authentication service.

-U authuser
    Specify that Username/Password authentication be used with the given user name. The password is read from standard input. Without this option, no authentication is requested from clients.

USAGE
The intended usage for running SOCKS5 over an ssh connection is as follows:

ssh -L1080:relayhost:12345 relayhost\
 "usocksd -p12345 -arelayhost -umyhost -Ufred"

where relayhost is the host where usocksd runs and myhost is the client's host. Note the coincidence of the host name and port number arguments. After this connection is established, myhost can be used as its own SOCKS5 server. The SOCKS connections, and therefore all TCP data, will be encrypted. UDP data is not sent over the encrypted SOCKS connection and is not encrypted; it goes directly from myhost to relayhost, while the corresponding SOCKS connection seems to come from relayhost itself. This is the reason why a regular SOCKS5 server can not be used for UDP in this situation (and the original incentive for writing usocksd). The SOCKS clients will use password authentication as user fred. The password to use is read from standard input. Neither user name nor password need to coincide with the real user name and password on any of the machines involved.

usocksd terminates when it encounters EOF on standard input. All other input on stdin is ignored. If the password should be read from a file instead of standard input, the proper way of invocation is

cat ~/.socks-password - |\
 ssh -L1080:relayhost:12345 relayhost\
 "usocksd -p12345 -arelayhost -umyhost -Ufred"

usocksd does not spawn any child processes, it does not detach from the controlling terminal and does produce output on the standard output and error channels.

DIAGNOSTICS
Messages about new connections, operating parameters and statistics are printed on standard output. Messages about connection failures are printed on standard error.

SEE ALSO
ssh(1), RFC 1928: SOCKS Protocol Version 5

BUGS
Most of the permission and sanity checks described in RFC 1928 are not implemented. This may be considered a feature.

Nonblocking I/O is used where applicable. On some systems, where nonblocking I/O does not work, new connections in progress will temporarily suspend data transfer on existing connections. The same applies to diagnostic output if the standard output and standard error channels run on a socket or pipe which can block.

usocksd does not fully support multi-homed servers. Support for multi-homed clients may depend on the client's SOCKS library.

UDP relaying does not work in the following case: Multiple or no addresses are given with the -u argument, and the client does not send any packets (it only receives), and the client binds its socket to address 0.

When multiple addresses are given with the -u argument, UDP relaying between those hosts does or does not work, depending on the exact sequence of packets. It is assumed that all allowed clients connect to each other directly.

There should be a more elegant method of killing an usocksd started via ssh than the EOF handling.

NOTES
The ping and traceroute utilities do not work with SOCKS because they use the ICMP protocol. The reference implementation SOCKS daemon by NEC includes undocumented commands for these applications. These are not supported by this configuration of usocksd.

VERSION
@VERSION@ as of @DATE@.

AUTHOR
Olaf Titz <olaf@bigred.inka.de>.

COPYING
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 2 of the License, or (at your option) any later version.