README.md

   1 MicroSocks - multithreaded, small, efficient SOCKS5 server.
   2 ===========================================================
   3
   4 a SOCKS5 service that you can run on your remote boxes to tunnel connections
   5 through them, if for some reason SSH doesn't cut it for you.
   6
   7 It's very lightweight, and very light on resources too:
   8
   9 for every client, a thread with a low stack size is spawned.
  10 the main process basically doesn't consume any resources at all.
  11
  12 the only limits are the amount of file descriptors and the RAM.
  13
  14 It's also designed to be robust: it handles resource exhaustion
  15 gracefully by simply denying new connections, instead of calling abort()
  16 as most other programs do these days.
  17
  18 another plus is ease-of-use: no config file necessary, everything can be
  19 done from the command line and doesn't even need any parameters for quick
  20 setup.
  21
  22 History
  23 -------
  24
  25 This is the successor of "rocksocks5", and it was written with
  26 different goals in mind:
  27
  28 - prefer usage of standard libc functions over homegrown ones
  29 - no artificial limits
  30 - do not aim for minimal binary size, but for minimal source code size,
  31   and maximal readability, reusability, and extensibility.
  32
  33 as a result of that, ipv4, dns, and ipv6 is supported out of the box
  34 and can use the same code, while rocksocks5 has several compile time
  35 defines to bring down the size of the resulting binary to extreme values
  36 like 10 KB static linked when only ipv4 support is enabled.
  37
  38 still, if optimized for size, *this* program when static linked against musl
  39 libc is not even 50 KB. that's easily usable even on the cheapest routers.
  40
  41 command line options
  42 --------------------
  43
  44     microsocks -1 -q -i listenip -p port -u user -P passw -b bindaddr -w wl
  45
  46 all arguments are optional.
  47 by default listenip is 0.0.0.0 and port 1080.
  48
  49 - option -q disables logging.
  50 - option -b specifies which ip outgoing connections are bound to
  51 - option -w allows to specify a comma-separated whitelist of ip addresses,
  52 that may use the proxy without user/pass authentication.
  53 e.g. -w 127.0.0.1,192.168.1.1.1,::1 or just -w 10.0.0.1
  54 to allow access ONLY to those ips, choose an impossible to guess user/pw combo.
  55 - option -1 activates auth_once mode: once a specific ip address
  56 authed successfully with user/pass, it is added to a whitelist
  57 and may use the proxy without auth.
  58 this is handy for programs like firefox that don't support
  59 user/pass auth. for it to work you'd basically make one connection
  60 with another program that supports it, and then you can use firefox too.
  61 for example, authenticate once using curl:
  62
  63     curl --socks5 user:password@listenip:port anyurl
  64
  65
  66 Supported SOCKS5 Features
  67 -------------------------
  68 - authentication: none, password, one-time
  69 - IPv4, IPv6, DNS
  70 - TCP (no UDP at this time)
  71
  72 Troubleshooting
  73 ---------------
  74
  75 if you experience segfaults, try raising the `THREAD_STACK_SIZE` in sockssrv.c
  76 for your platform in steps of 4KB.
  77
  78 if this fixes your issue please file a pull request.
  79
  80 microsocks uses the smallest safe thread stack size to minimize overall memory
  81 usage.