LeProxy is the HTTP/SOCKS proxy server for everybody!
LeProxy is designed for anonymous surfing, improved security and privacy plus circumventing geoblocking. It allows you to enjoy the web like it's meant to work and access your favorite online video platform without annoying country blocks while traveling.
LeProxy is a powerful, lightweight, fast and simple to use proxy server that you can host on your own server or PC at home and then access from anywhere. It supports optional authentication so you can share a server instance with your family and friends without having to worry about third parties. It provides compatibility with a large number of clients and services by accepting both common HTTP and SOCKS proxy protocols on a single listening port.
Table of contents
Note that this is an early beta version and that LeProxy is under active development. Many new features are going to be added in the future!
LeProxy requires only PHP. PHP 7+ is highly recommended, but it runs on any system that uses PHP 5.4+ or HHVM. If you have not installed PHP already, on a recent Ubuntu/Debian system, simply run:
$ sudo apt-get install php7.0-cli
You can simply download the latest leproxy-{version}.php
file from our
releases page.
The latest release can
always be downloaded like this:
$ curl -OL https://leproxy.org/leproxy-latest.php
Downloaded the leproxy-{version}.php
file?
You did it!! Really simple, huh?
LeProxy is distributed as a single PHP file that contains everything you need to run LeProxy. The below examples assume you have saved this file as
leproxy.php
locally, but you can use any name you want. If you're interested in the more technical details of this file, you may want to check out the development instructions below.
Once installed, you can start LeProxy by simply running:
$ php leproxy.php
By default, LeProxy will listen on the public address 0.0.0.0:8080
.
If you want to listen on another address, you can pass an explicit listening
address.
LeProxy will report an error if it fails to listen on the given address,
you may try another address or use port 0
to pick a random free port.
For example, if you do not want to allow accessing LeProxy from the outside and
only want to listen on the local interface:
$ php leproxy.php 127.0.0.1:8080
The listening address MUST be in the form
ip:port
or justip
or:port
, with the above defaults being applied (or you can use a Unix domain socket path).
Note that LeProxy runs in protected mode by default, so that it only forwards
requests from the local host and can not be abused as an open proxy.
If you have ensured only legit users can access your system, you can
pass the --allow-unprotected
flag to forward requests from all hosts.
If you want to require the client to send username/password authentication
details, you can include this as part of the listening address:
$ php leproxy.php username:[email protected]:8080
If the username or password contains special characters, make sure to use URL encoded values (percent-encoding) such as
p%40ss
forp@ss
.
By default, LeProxy allows connections to every destination address as given in
each incoming proxy request.
If you want to block access to certain destination hosts and/or ports, you may
blacklist these by passing the --block=<destination>
argument.
Any number of destination addresses can be given.
Each destination address can be in the form host:port
or just host
or
:port
and host
may contain the *
wildcard to match anything.
Subdomains for each host will automatically be blocked.
For example, the following can be used to block access to youtube.com
(and its
subdomains such as www.youtube.com
) and port 80 on all hosts (standard
plaintext HTTP port):
$ php leproxy.php --block=youtube.com --block=*:80
Note that the block list operates on the destination addresses as given in the incoming proxy request. Some clients use local DNS resolution and do not transmit hostnames, but only the resolved destination IP addresses (particularly common for the SOCKS protocol). Make sure to configure your client to use remote DNS resolution accordingly and/or also block access to relevant IP addresses.
As an alternative to listing each blocked destination as an individual command
line argument, you may also pass a path to a hosts
file instead.
You can either create a hosts file mapping yourself if you only want to block
certain hosts or you may one of the many great hosts files.
For example, you can download a hosts file from https://github.com/StevenBlack/hosts
("hosts files from several well-curated sources like adaway.org, mvps.org,
malwaredomainlist.com, someonewhocares.org, and potentially others")
to use this as a very simple, yet effective adblocker.
Note that LeProxy will only block domains (and all its subdomains) that match
the IP 0.0.0.0
and ignore all other entries:
$ cat hosts.txt
127.0.0.1 localhost
0.0.0.0 ads.example.com
0.0.0.0 socialnetwork.example
…
$ php leproxy.php --block-hosts=hosts.txt
By default, Leproxy creates a direct connection to the destination address for each incoming proxy request. In this mode, the destination doesn't see the original client address, but only the address of your LeProxy instance. If you want a higher level degree of anonymity, you can use proxy forwarding, where the connection will be tunneled through another upstream proxy server. This may also be useful if your upstream proxy address changes regularly (such as when using public proxies), but you do not want to reconfigure your client every time or if your upstream proxy requires a feature that your client does not support, such as requiring authentication or a different proxy protocol. You can simply pass your upstream proxy server address as another URL parameter after the listening address like this:
$ php leproxy.php --proxy=socks://user:[email protected]:8080
The upstream proxy server URI MUST contain a hostname or IP and SHOULD include a port unless the proxy happens to use default port
8080
(or you can use a Unix domain socket path). If no scheme is given, thehttp://
scheme will be assumed. If no port is given, port8080
will be assumed regardless of scheme. Thehttp://
andsocks[5]://
schemes support optional username/password authentication as in the above example.
By appending additional upstream proxy servers, this can effectively be turned into proxy chaining, where each incoming proxy request will be forwarded through the chain of all upstream proxy servers from left to right. This comes at the price of increased latency, but may provide a higher level degree of anonymity, as each proxy server in the chain only sees its direct communication partners and the destination only sees the last proxy server in the chain:
$ php leproxy.php --proxy=127.1.1.1:8080 --proxy=127.2.2.2:8080 --proxy=127.3.3.3:8080
By default, LeProxy prints a log message for every connection attempt to the
console output (STDOUT) for debugging and analysis purposes.
For privacy reasons, it does not persist (store) these log messages on its own.
If you do not want LeProxy to log anything, you may also pass the --no-log
flag.
If you want to persist the log to a log file, you may use standard operating
system facilities such as tee
to redirect the output to a file:
$ php leproxy.php | tee -a leproxy.log
Once LeProxy is running, you can start using it with pretty much any client software. The below example assumes you want to use a web browser, but LeProxy can actually be used with any client software that provides proxy support, such as an email or IM client.
Most clients provide settings to manually configure a proxy server in their settings/preferences dialogs. You can simply set the details from the listening address as configured above:
- Protocol: HTTP or SOCKS
- Server: 127.0.0.1 (or the public hostname or IP where LeProxy runs)
- Port: 8080
Note that these settings have to be adjusted to your actual network settings. If you fail to provide correct settings, no further connection will succeed. In this case, simply remove or disable these settings again. The same may apply if you're roaming in another network or the proxy server is temporarily not available.
Many clients (in particular web browsers and mobile phones) also support Proxy Auto-Configuration (PAC) by specifying a PAC URL. Using PAC is often beneficial because most clients will simply ignore the proxy settings if the PAC URL can not be reached, such as when you're roaming in another network or the proxy server is temporarily not available. Simply use the URL to your LeProxy instance in the following format:
http://127.0.0.1:8080/pac
Note that these settings have to be adjusted to your actual network settings. If you fail to provide correct settings, you may or may not be able to establish further connections, as most clients will simply ignore invalid settings. If your client disallows this, simply remove or disable these settings again. LeProxy's PAC file instructs your client to use LeProxy as an HTTP proxy for all public HTTP requests. This means that hostnames that resolve to IPs from your local network will still use a direct connection without going through a proxy.
LeProxy is an open-source project and encourages everybody to participate in its development. You're interested in checking out how LeProxy works under the hood and/or want to contribute to the development of LeProxy? Then this section is for you!
The recommended way to install LeProxy is to clone (or download) this repository and use Composer to download its dependencies. Therefore you'll need PHP, git and curl installed. For example, on a recent Ubuntu/debian system, simply run:
$ sudo apt-get install php7.0-cli git curl
$ git clone https://github.com/leproxy/leproxy.git
$ cd leproxy
$ curl -s https://getcomposer.org/installer | php
$ sudo mv composer.phar /usr/local/bin/composer
$ composer install
That's it already!
You should now be able to run the development version of LeProxy simply by
running the leproxy.php
file like this:
$ php leproxy.php
See also usage for more details.
LeProxy uses a sophisticated test suite for functional tests and integration tests. To run the test suite, go to the project root and run:
$ vendor/bin/phpunit
If you want to distribute LeProxy as a single standalone release file, you may compile the project into a single file like this:
$ php compile.php
Note that compiling will temporarily uninstall all development dependencies for distribution and then re-install the complete set of dependencies. This should only take a second or two if you've previously installed its dependencies already. The compile script optionally accepts the version number (
VERSION
env) and an output file name or will otherwise try to look up the last release tag, such asleproxy-1.0.0.php
.
In addition to the above test suite, LeProxy uses a simple bash/curl-based acceptance test setup which can also be used to check the resulting release file:
$ tests/acceptance.sh
Note that the acceptance tests will try to locate a
leproxy*.php
file in the project directory to run the tests against. You may optionally supply the output file name to test against.
Made some changes to your local development version?
Make sure to let the world know!
We welcome PRs and would love to hear from you!
Happy hacking!
LeProxy is an open source project released under the permissive MIT license.
LeProxy is standing on the shoulders of giants. Building something like LeProxy probably wouldn't be possible if not for the excellent open source projects that it builds on top of. In particular, it uses ReactPHP for its fast, event-driven architecture.
All of its dependencies are managed through Composer, see also the
development section for more details.
If you're using the development version, you may run
$ composer licenses --no-dev
to get a list of all runtime dependencies and their
respective licenses.
All these requirements are bundled into the single standalone release file.