LeProxy
, (*1)
LeProxy is the HTTP/SOCKS proxy server for everybody!, (*2)
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., (*3)
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., (*4)
Table of contents, (*5)
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!, (*6)
Install
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:, (*7)
$ 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:, (*8)
$ curl -OL https://leproxy.org/leproxy-latest.php
Downloaded the leproxy-{version}.php file?
You did it!! Really simple, huh?, (*9)
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., (*10)
Usage
Once installed, you can start LeProxy by simply running:, (*11)
$ 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:, (*12)
$ php leproxy.php 127.0.0.1:8080
The listening address MUST be in the form ip:port or just ip or :port,
with the above defaults being applied (or you can use a Unix domain socket
path)., (*13)
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:, (*14)
$ php leproxy.php username:password@0.0.0.0:8080
If the username or password contains special characters, make sure to use
URL encoded values (percent-encoding) such as p%40ss for p@ss., (*15)
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):, (*16)
$ 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., (*17)
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:, (*18)
$ 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:, (*19)
$ php leproxy.php --proxy=socks://user:pass@127.0.0.1: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, the http:// scheme will be assumed.
If no port is given, port 8080 will be assumed regardless of scheme.
The http:// and socks[5]:// schemes support optional username/password
authentication as in the above example., (*20)
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:, (*21)
$ 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:, (*22)
$ php leproxy.php | tee -a leproxy.log
Clients
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., (*23)
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:, (*24)
- 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., (*25)
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:, (*26)
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., (*27)
Development
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!, (*28)
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:, (*29)
$ 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:, (*30)
$ php leproxy.php
See also usage for more details., (*31)
LeProxy uses a sophisticated test suite for functional tests and integration
tests.
To run the test suite, go to the project root and run:, (*32)
$ 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:, (*33)
$ 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 as leproxy-1.0.0.php., (*34)
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:, (*35)
$ 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., (*36)
Made some changes to your local development version?, (*37)
Make sure to let the world know! :shipit:
We welcome PRs and would love to hear from you!, (*38)
Happy hacking!, (*39)
License
LeProxy is an open source project released under the permissive
MIT license., (*40)
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., (*41)
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., (*42)
Wallogit.com
