go-proxies

README

What is this?
=============
A simple implementation of HTTP and SOCKSv5 proxy servers in golang.
The proxy is expected to scale well on a modern multi-processor box.
It runs on any platform that is supported by Go.

Building the servers
---------------------
You need a reasonably new Golang toolchain (1.8+). And the ``go``
executable needs to be in your path. Then run::

    make


The Makefile is exceedingly simple; it invokes::

    ./build


``build`` is the primary script responsible for building ``goproxy``.
It places the binary in TARGET specific directory. e.g., for linux-amd64,
the binaries will be in ``./bin/linux-amd64``; and OS X, it will be in
``./bin/darwin-amd64`` and so on.

You can cross-compile by passing appropriate architecture names to
the script. e.g., to build on host OS X for openbsd-amd64::

    ./build --arch=openbsd-amd64 

You can build a statically linked executable (with no other runtime dependency)::

    ./build -s

The script also has other options. To see them::

    ./build --help


Usage
-----
The server takes a YAML config file as its sole command line argument. The server
does not fork itself into the background. If you need that capability, explore your
platform's init toolchain (e.g., ``start-stop-daemon``).

The server can run in debug mode::

    ./bin/linux-amd64/goproxy -d etc/goproxy.conf


In debug mode, the logs are sent to STDOUT and the debug level is set to DEBUG
(i.e., verbose).

In the absence of the ``-d`` flag, the default log level is INFO.

Config File
-----------
The server config file is a YAML v2 document. It has a section for HTTP proxy and a
separate section for SOCKSv5 proxy. An example is below::

    # Log file; can be one of:
    #  - Absolute path
    #  - SYSLOG
    #  - STDOUT
    #  - STDERR
    #log: /tmp/goproxy.log
    log: STDOUT

    # Logging level - "DEBUG", "INFO", "WARN", "ERROR"
    loglevel: DEBUG

    # Path to URL Log and response codes
    #urllog:

    # drop privileges as soon as listeners are setup to the uid/gid below.
    # Only meaningful if go-proxy is started as root.
    uid: nobody
    gid: nobody

    # Listeners
    http:
        -
            listen: 127.0.0.1:8080

            # if you want this listener to use a specific outbound IP, then set that
            # here
            #bind:

            # ACL
            allow: [127.0.0.1/8, 11.0.1.0/24, 11.0.2.0/24]
            deny: []

            # limit to N reqs/sec globally and M requests per-host
            ratelimit:
                global: 2000
                perhost: 30


    socks:
        -
            listen: 127.0.0.1:2080
            #bind:
            allow: [127.0.0.1/8, 11.0.1.0/24, 11.0.2.0/24]
            deny: []
            # limit to N reqs/sec globally
            ratelimit:
                global: 2000
                perhost: 30



Major features
--------------
- No authentication (yes, its a feature)
- flexible allow/deny rules for discriminating clients
- multiple listeners - each with their own ACL
- Rate limiting incoming connections (global and per-host)

Access Control Rules
--------------------
Go-socksd implements a flexible ACL by combination of
allow/deny rules. The rules are evaluated in the following order:

- If explicitly denied, the host is blocked
- If explicitly allowed, the host is allowed
- Explicit denial takes precedence over explicit allow
- Empty allow list is the same as "allow all"

Example of allow/deny combinations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Only allow specific subnets and deny everyone else:

    allow: [ 192.168.55.0/24, 172.16.10.0/24, 127.0.0.1/8 ],
    deny: []


2. Allow all except selected subnets:

    allow: [],
    deny: [ 192.168.80.0/24", 172.16.5.0/24 ]


3. Expliclty block certain hosts and explicitly allow certain
   subnets and block everyone else:

    allow: [ 192.168.55.0/24, 172.16.10.0/24, 127.0.0.1/8 ],
    deny:  [ 192.168.1.1/32, 192.168.80.0/24, 172.16.5.0/24 ]


Development Notes
=================
If you are a developer, the notes here will be useful for you:

* We use go module support; so you will need go 1.10+ for this to work.

* The build script ``build`` is a shell script to build the program.
  It does two very important things:
    * Puts the binary in an OS/Arch specific directory
    * Injects a git version-tag into the final binary ("linker resolved symbol")

* Example config files is in the ``etc/goproxy.conf`` directory.


Redirect Error
--------------
If you are receiving some error like::

  gopkg.in/h2non/bimg.v1: Cloning and checking out v1.0.6..
  error: RPC failed; HTTP 301 curl 22 The requested URL returned error: 301
  fatal: The remote end hung up unexpectedly

It is because something in git around version 2.11.1 stops following redirects.
A popular repository of golang packages uses this. To workaround, try::

  git config --global http.https://gopkg.in.followRedirects true

.. vim: ft=rst:sw=4:ts=4:expandtab:tw=84: