astraproxy/README.md

209 lines
8.6 KiB
Markdown
Raw Normal View History

2020-05-19 21:59:46 +02:00
dumbproxy
=========
2020-05-25 00:13:31 +02:00
[![dumbproxy](https://snapcraft.io//dumbproxy/badge.svg)](https://snapcraft.io/dumbproxy)
2020-05-19 21:59:46 +02:00
Dumbiest HTTP proxy ever.
## Features
* Cross-platform (Windows/Mac OS/Linux/Android (via shell)/\*BSD)
2020-05-24 00:23:44 +02:00
* Deployment with a single self-contained binary
2020-05-19 21:59:46 +02:00
* Zero-configuration
* Supports CONNECT method and forwarding of HTTPS connections
2020-05-20 00:00:59 +02:00
* Supports `Basic` proxy authentication
2020-05-24 00:18:01 +02:00
* Supports TLS operation mode (HTTP(S) proxy over TLS)
2022-09-05 00:01:00 +02:00
* Native ACME support (can issue TLS certificates automatically using Let's Encrypt or BuyPass)
2020-05-24 23:24:46 +02:00
* Supports client authentication with client TLS certificates
2020-05-24 14:34:16 +02:00
* Supports HTTP/2
2020-05-24 18:42:20 +02:00
* Resilient to DPI (including active probing, see `hidden_domain` option for authentication providers)
2020-05-19 21:59:46 +02:00
## Installation
#### Binary download
Pre-built binaries available on [releases](https://github.com/Snawoot/dumbproxy/releases/latest) page.
#### From source
Alternatively, you may install dumbproxy from source. Run within source directory
```
go install
```
#### Docker
Docker image is available as well. Here is an example for running proxy as a background service:
```sh
docker run -d \
--security-opt no-new-privileges \
-p 8080:8080 \
--restart unless-stopped \
--name dumbproxy \
yarmak/dumbproxy
```
#### Snap Store
[![Get it from the Snap Store](https://snapcraft.io/static/images/badges/en/snap-store-black.svg)](https://snapcraft.io/dumbproxy)
```bash
sudo snap install dumbproxy
```
2020-05-19 21:59:46 +02:00
## Usage
2020-05-20 00:00:59 +02:00
Just run program and it'll start accepting connections on port 8080 (default).
2022-09-05 00:01:00 +02:00
### Example: plain proxy
Run proxy on port 1234 with `Basic` authentication with username `admin` and password `123456`:
2020-05-20 00:00:59 +02:00
```sh
dumbproxy -bind-address :1234 -auth 'static://?username=admin&password=123456'
```
2022-09-05 00:01:00 +02:00
### Example: HTTP proxy over TLS (LetsEncrypt automatic certs)
Run HTTPS proxy (HTTP proxy over TLS) with automatic certs from LetsEncrypt on port 443 with `Basic` authentication with username `admin` and password `123456`:
```sh
dumbproxy -bind-address :443 -auth 'static://?username=admin&password=123456' -autocert
```
### Example: HTTP proxy over TLS (BuyPass automatic certs)
Run HTTPS proxy (HTTP proxy over TLS) with automatic certs from BuyPass on port 443 with `Basic` authentication with username `admin` and password `123456`:
```sh
2022-09-05 00:33:12 +02:00
dumbproxy \
-bind-address :443 \
-auth 'static://?username=admin&password=123456' \
-autocert \
-autocert-acme 'https://api.buypass.com/acme/directory' \
-autocert-email YOUR-EMAIL@EXAMPLE.ORG \
-autocert-http :80
2022-09-05 00:01:00 +02:00
```
2020-05-25 02:38:02 +02:00
## Using HTTP-over-TLS proxy
2022-09-05 00:01:00 +02:00
It's quite trivial to set up program which supports proxies to use dumbproxy in plain HTTP mode. However, using HTTP proxy over TLS connection with browsers is little bit tricky. Note that TLS must be enabled (`-cert` and `-key` options or `-autocert` option) for this to work.
2020-05-25 02:38:02 +02:00
2020-05-29 14:20:00 +02:00
### Routing all browsers on Windows via HTTPS proxy
Open proxy settings in system's network settings:
![win10-proxy-settings](https://user-images.githubusercontent.com/3524671/83258553-216f7700-a1bf-11ea-8af9-3d8aed5b2e71.png)
2020-05-29 14:22:30 +02:00
Turn on setup script option and set script address:
2020-05-29 14:20:00 +02:00
```
data:,function FindProxyForURL(u, h){return "HTTPS example.com:8080";}
```
where instead of `example.com:8080` you should use actual address of your HTTPS proxy.
Note: this method will not work with MS Edge Legacy.
2020-05-29 14:26:26 +02:00
### Using with Firefox
2020-05-25 02:38:02 +02:00
2020-05-29 14:26:26 +02:00
#### Option 1. Inline PAC file in settings.
Open Firefox proxy settings, switch proxy mode to "Automatic proxy configuration URL". Specify URL:
2020-05-25 02:38:02 +02:00
```
data:,function FindProxyForURL(u, h){return "HTTPS example.com:8080";}
```
![ff_https_proxy](https://user-images.githubusercontent.com/3524671/82768442-afea9e00-9e37-11ea-80fd-1eccf55b89fa.png)
2020-05-29 14:26:26 +02:00
#### Option 2. Browser extension.
Use any proxy switching browser extension which supports HTTPS proxies like [this one](https://addons.mozilla.org/ru/firefox/addon/switchyomega/).
2020-05-25 02:38:02 +02:00
2020-05-29 14:26:26 +02:00
### Using with Chrome
2020-05-25 02:38:02 +02:00
2020-05-29 14:26:26 +02:00
#### Option 1. CLI option.
Specify proxy via command line:
2020-05-25 02:38:02 +02:00
```
chromium-browser --proxy-server='https://example.com:8080'
```
2020-05-29 14:26:26 +02:00
#### Option 2. Browser extension.
Use any proxy switching browser extension which supports HTTPS proxies like [this one](https://chrome.google.com/webstore/detail/proxy-switchyomega/padekgcemlokbadohgkifijomclgjgif).
2020-05-25 02:38:02 +02:00
2020-05-29 14:26:26 +02:00
### Using with other applications
2020-05-25 02:38:02 +02:00
It is possible to expose remote HTTPS proxy as a local plaintext HTTP proxy with help of external application which performs remote communication via TLS and exposes local plaintext socket. [steady-tun](https://github.com/Snawoot/steady-tun) appears to be most suitable for this because it supports connection pooling to hide connection delay.
2022-09-05 00:49:58 +02:00
### Using with Android
1. Run proxy as in [examples](#usage) above.
2. Install Adguard on your Android: [Guide](https://adguard.com/en/adguard-android/overview.html).
3. Follow [this guide](https://adguard.com/en/blog/configure-proxy.html#configuringproxyinadguardforandroid), skipping server configuration. Use proxy type HTTPS if you set up TLS-enabled server or else use HTTP type.
4. Enjoy!
2020-05-20 00:00:59 +02:00
## Authentication
Authentication parameters are passed as URI via `-auth` parameter. Scheme of URI defines authentication metnod and query parameters define parameter values for authentication provider.
* `none` - no authentication. Example: `none://`. This is default.
* `static` - basic authentication for single login and password pair. Example: `static://?username=admin&password=123456`. Parameters:
2020-05-24 18:42:20 +02:00
* `username` - login.
* `password` - password.
* `hidden_domain` - if specified and is not an empty string, proxy will respond with "407 Proxy Authentication Required" only on specified domain. All unauthenticated clients will receive "400 Bad Request" status. This option is useful to prevent DPI active probing from discovering that service is a proxy, hiding proxy authentication prompt when no valid auth header was provided. Hidden domain is used for generating 407 response code to trigger browser authorization request in cases when browser has no prior knowledge proxy authentication is required. In such cases user has to navigate to any hidden domain page via plaintext HTTP, authenticate themselves and then browser will remember authentication.
2022-09-06 23:25:38 +02:00
* `basicfile` - use htpasswd-like file with login and password pairs for authentication. Such file can be created/updated with command like this: `dumbproxy -passwd /etc/dumbproxy.htpasswd username password` or with `htpasswd` utility from Apache HTTPD utils. `path` parameter in URL for this provider must point to a local file with login and bcrypt-hashed password lines. Example: `basicfile://?path=/etc/dumbproxy.htpasswd`.
* `path` - location of file with login and password pairs. File format is similar to htpasswd files. Each line must be in form `<username>:<bcrypt hash of password>`. Empty lines and lines starting with `#` are ignored.
2020-05-24 21:20:12 +02:00
* `hidden_domain` - same as in `static` provider
2022-09-06 20:49:36 +02:00
* `reload` - interval for conditional password file reload, if it was modified since last load. Use negative duration to disable autoreload. Default: `15s`.
2020-05-24 23:19:48 +02:00
* `cert` - use mutual TLS authentication with client certificates. In order to use this auth provider server must listen sockert in TLS mode (`-cert` and `-key` options) and client CA file must be specified (`-cacert`). Example: `cert://`.
2020-05-19 21:59:46 +02:00
## Synopsis
```
$ ~/go/bin/dumbproxy -h
2020-05-20 00:09:16 +02:00
-auth string
auth parameters (default "none://")
2022-09-05 00:01:00 +02:00
-autocert
issue TLS certificates automatically
-autocert-acme string
custom ACME endpoint (default "https://acme-v02.api.letsencrypt.org/directory")
-autocert-dir string
path to autocert cache (default "/home/user/.dumbproxy/autocert")
-autocert-email string
email used for ACME registration
-autocert-http string
listen address for HTTP-01 challenges handler of ACME
-autocert-whitelist value
restrict autocert domains to this comma-separated list
2020-05-19 21:59:46 +02:00
-bind-address string
HTTP proxy listen address (default ":8080")
2020-05-25 00:10:37 +02:00
-cafile string
CA file to authenticate clients with certificates
2020-05-24 00:18:01 +02:00
-cert string
enable TLS and use certificate
2021-02-26 08:37:58 +01:00
-ciphers string
colon-separated list of enabled ciphers
-disable-http2
disable HTTP2
2020-05-24 00:18:01 +02:00
-key string
key for TLS certificate
2021-02-26 08:37:58 +01:00
-list-ciphers
list ciphersuites
2022-09-06 23:25:38 +02:00
-passwd string
update given htpasswd file and add/set password for username. Username and password can be passed as positional arguments or requested interactively
-passwd-cost int
bcrypt password cost (for -passwd mode) (default 4)
2020-05-19 21:59:46 +02:00
-timeout duration
timeout for network operations (default 10s)
-verbosity int
logging verbosity (10 - debug, 20 - info, 30 - warning, 40 - error, 50 - critical) (default 20)
2021-06-09 16:19:44 +02:00
-version
show program version and exit
2020-05-19 21:59:46 +02:00
```