View on GitHub

Tinyproxy
lightweight http(s) proxy daemon
Tinyproxy
Tinyproxy is a light-weight HTTP/HTTPS proxy daemon for POSIX operating systems. Designed from the
ground up to be fast and yet small, it is an ideal solution for use cases such as embedded deployments where a
full featured HTTP proxy is required, but the system resources for a larger proxy are unavailable.

Tinyproxy is distributed using the GNU GPL license (version 2 or above).

Features
Tinyproxy has a small footprint and requires very little in the way of system resources. The memory footprint
tends to be around 2 MB with glibc, and the CPU load increases linearly with the number of simultaneous
connections (depending on the speed of the connection). Thus, Tinyproxy can be run on an older machine, or on
a network appliance such as a Linux-based broadband router, without any noticeable impact on performance.

Tinyproxy requires only a minimal POSIX environment to build and operate. It can use additional libraries to
add functionality though.

Tinyproxy allows forwarding of HTTPS connections without modifying traffic in any way through the CONNECT
method (see the ConnectPort directive, which you should disable, unless you want to restrict the users).

Tinyproxy supports being configured as a transparent proxy, so that a proxy can be used without requiring any
client-side configuration. You can also use it as a reverse proxy front-end to your websites.

Using the AddHeader directive, you can add/insert HTTP headers to outgoing traffic (HTTP only).

If you're looking to build a custom web proxy, Tinyproxy is easy to modify to your custom needs. The source is
straightforward, adhering to the KISS principle. As such, it can be used as a foundation for anything you may
need a web proxy to do.

Tinyproxy has privacy features which can let you configure which HTTP headers should be allowed through,
and which should be blocked. This allows you to restrict both what data comes to your web browser from the
HTTP server (e.g., cookies), and to restrict what data is allowed through from your web browser to the HTTP
server (e.g., version information). Note that these features do not affect HTTPS connections.

Using the remote monitoring facility, you can access proxy statistics from afar, letting you know exactly how
busy the proxy is.

You can configure Tinyproxy to control access by only allowing requests from a certain subnet, or from a
certain interface, thus ensuring that random, unauthorized people will not be using your proxy.

With a bit of configuration (specifically, making Tinyproxy created files owned by a non-root user and running it
on a port greater than 1024), Tinyproxy can be made to run without any special privileges, thus minimizing the
chance of system compromise. In fact, it is recommended to run it as a regular/restricted user. Furthermore, it
was designed with an eye towards preventing buffer overflows. The simplicity of the code ensures it remains
easy to spot such bugs.

Downloads
Note that many distributions ship horribly outdated versions of tinyproxy, therefore it is recommended to
compile it from source.

On Red Hat Enterprise Linux, or its derivatives such as CentOS, install Tinyproxy from the EPEL
repository by running yum install tinyproxy.
On Fedora, install Tinyproxy by running yum install tinyproxy.
On Debian and derived distributions, run apt-get install tinyproxy to install Tinyproxy.
For openSUSE run: zypper in tinyproxy
Arch users can install the Tinyproxy package from the community repository. Run pacman -S tinyproxy to
install it.
FreeBSD, OpenBSD or NetBSD users can use the pkg_add utility to install the tinyproxy package.
Mac OS X users can check MacPorts to see if the Tinyproxy port there is recent enough.

If you feel that the Tinyproxy binary package in your operating system is not recent (likely), please contact the
package maintainer for that particular operating system. If this fails, you can always compile the latest stable, or
even better, the latest git master version, from source code.

We distribute Tinyproxy in source code form, and it has to be compiled in order to be used on your system.
Please see the INSTALL file in the source code tree for build instructions. The current stable version of
Tinyproxy is available on the releases page. The Tinyproxy NEWS file contains the release notes. You can verify
the tarball using its PGP signature. You can also browse the older releases of Tinyproxy.

We use Git as the version control system for the Tinyproxy source code repository. To get a copy of the
Tinyproxy repository, use the command:

git clone https://github.com/tinyproxy/tinyproxy.git

Quickstart
The quickest way to get started is using a minimal config file like the below:

Port 8888
Listen 127.0.0.1
Timeout 600
Allow 127.0.0.1

And then simply run tinyproxy -d -c tinyproxy.conf as your current user. This starts tinyproxy in
foreground mode with tinyproxy.conf as its config, while logging to stdout. Now, all programs supporting a
HTTP proxy can use 127.0.0.1:8888 as a proxy. You can try it out using http_proxy=127.0.0.1:8888 curl
example.com.

Documentation
NAME

tinyproxy.conf - Tinyproxy HTTP proxy daemon configuration file

tinyproxy.conf

DESCRIPTION

tinyproxy(8) reads its configuration file, typically stored in `/etc/tinyproxy/tinyproxy.conf` (or passed to
Tinyproxy with -c on the command line). This manpage describes the syntax and contents of the configuration
file.

The Tinyproxy configuration file contains key-value pairs, one per line. Lines starting with `#` and empty lines
are comments and are ignored. Keywords are case-insensitive, whereas values are case-sensitive. Values may be
enclosed in double-quotes (") if they contain spaces.

The possible keywords and their descriptions are as follows:

User

The user which the Tinyproxy process should run as, after the initial port-binding has been done as the
`root` user. Either the user name or the UID may be specified.

Group

The group which the Tinyproxy process should run as, after the initial port-binding has been done as the
`root` user. Either the group name or the GID may be specified.

Port

The port which the Tinyproxy service will listen on. If the port is less than 1024, you will need to start the
Tinyproxy process as the `root` user.

Listen

By default, Tinyproxy listens for connections on all available interfaces (i.e. it listens on the wildcard
address `0.0.0.0`). With this configuration parameter, Tinyproxy can be told to listen only on one specific
address.

Bind

This allows you to specify which address Tinyproxy will bind to for outgoing connections to web servers
or upstream proxies. This parameter may be specified multiple times, then Tinyproxy will try all the
specified addresses in order.

BindSame

If this boolean parameter is set to `yes`, then Tinyproxy will bind the outgoing connection to the IP
address of the incoming connection that triggered the outgoing request.

Timeout

The maximum number of seconds of inactivity a connection is allowed to have before it is closed by
Tinyproxy.

ErrorFile
 This parameter controls which HTML file Tinyproxy returns when a given HTTP error occurs. It takes two
arguments, the error number and the location of the HTML error file.

DefaultErrorFile

This parameter controls the HTML template file returned when an error occurs for which no specific error
file has been set.

StatHost

This configures the host name or IP address that is treated as the `stat host`: Whenever a request for this
host is received, Tinyproxy will return an internal statistics page instead of forwarding the request to that
host. The template for this page can be configured with the `StatFile` configuration option. The default
value of `StatHost` is `tinyproxy.stats`.

StatFile

This configures the HTML file that Tinyproxy sends when a request for the stathost is received. If this
parameter is not set, Tinyproxy returns a hard-coded basic statistics page. See the STATHOST section in
the tinyproxy(8) manual page for details.

Note that the StatFile and the error files configured with ErrorFile and DefaultErrorFile are template files
that can contain a few template variables that Tinyproxy expands prior to delivery. Examples are "
{cause}" for an abbreviated error description and "{detail}" for a detailed error message. The tinyproxy(8)
manual page contains a description of all template variables.

LogFile

This controls the location of the file to which Tinyproxy writes its debug output. Alternatively, Tinyproxy
can log to syslog -- see the Syslog option.

Syslog

When set to `On`, this option tells Tinyproxy to write its debug messages to syslog instead of to a log file
configured with `LogFile`. These two options are mutually exclusive.

LogLevel

Sets the log level. Messages from the set level and above are logged. For example, if the LogLevel was set
to Warning, then all log messages from Warning to Critical would be output, but Notice and below would
be suppressed. Allowed values are:

Critical (least verbose)

Error

Warning

Notice

Connect (log connections without Info's noise)

Info (most verbose)

PidFile
 This option controls the location of the file where the main Tinyproxy process stores its process ID for
signaling purposes.

XTinyproxy

Setting this option to `Yes` tells Tinyproxy to add a header `X-Tinyproxy` containing the client's IP
address to the request.

Upstream

This option allows you to set up a set of rules for deciding whether an upstream proxy server is to be used,
based on the host or domain of the site being accessed. The rules are stored in the order encountered in the
configuration file and the LAST matching rule wins. The following forms for specifying upstream rules
exist:

upstream type host:port turns proxy upstream support on generally.

upstream type user:pass@host:port does the same, but uses the supplied credentials for
authentication.

upstream type host:port "site_spec" turns on the upstream proxy for the sites matching `site_spec`.

`type` can be one of `http`, `socks4`, `socks5`, `none`.

upstream none "site_spec" turns off upstream support for sites matching `site_spec`, that means the
connection is done directly.

The site can be specified in various forms as a hostname, domain name or as an IP range:

name matches host exactly

.name matches any host in domain "name"

. matches any host with no domain (in 'empty' domain)

IP/bits matches network/mask

IP/mask matches network/mask

Note that the upstream directive can also be used to null-route a specific target domain/host, e.g.:
`upstream http 0.0.0.0:0 ".adserver.com"`

MaxClients

Tinyproxy creates one thread for each connected client. This options specifies the absolute highest number
processes that will be created. With other words, only MaxClients clients can be connected to Tinyproxy
simultaneously.

Allow
Deny

The `Allow` and `Deny` options provide a means to customize which clients are allowed to access
Tinyproxy. `Allow` and `Deny` lines can be specified multiple times to build the access control list for
Tinyproxy. The order in the config file is important. If there are no `Allow` or `Deny` lines, then all clients
are allowed. Otherwise, the default action is to deny access. The argument to `Allow` or `Deny` can be a
single IP address of a client host, like `127.0.0.1`, an IP address range, like `192.168.0.1/24` or a string
 that will be matched against the end of the client host name, i.e, this can be a full host name like
`host.example.com` or a domain name like `.example.com` or even a top level domain name like `.com`.
Note that by adding a rule using a host or domain name, a costly name lookup has to be done for every
new connection, which could slow down the service considerably.
BasicAuth

Configure HTTP "Basic Authentication" username and password for accessing the proxy. If there are any
entries specified, access is only granted for authenticated users.

BasicAuth user password

AddHeader

Configure one or more HTTP request headers to be added to outgoing HTTP requests that Tinyproxy
makes. Note that this option will not work for HTTPS traffic, as Tinyproxy has no control over what
headers are exchanged.

AddHeader "X-My-Header" "Powered by Tinyproxy"

ViaProxyName

RFC 2616 requires proxies to add a `Via` header to the HTTP requests, but using the real host name can be
a security concern. If the `ViaProxyname` option is present, then its string value will be used as the host
name in the Via header. Otherwise, the server's host name will be used.

DisableViaHeader

When this is set to yes, Tinyproxy does NOT add the `Via` header to the requests. This virtually puts
Tinyproxy into stealth mode. Note that RFC 2616 requires proxies to set the `Via` header, so by enabling
this option, you break compliance. Don't disable the `Via` header unless you know what you are doing...

Filter

Tinyproxy supports filtering of web sites based on URLs or domains. This option specifies the location of
the file containing the filter rules, one rule per line.

Rules are specified as POSIX basic regular expressions (BRE), unless another FilterType is specified.
Comment lines start with a `#` character.

Example filter file contents:

# filter exactly cnn.com

# filter all subdomains of cnn.com, but not cnn.com itself

# filter any domain that has cnn.com in it, like xcnn.comfy.org

# filter any domain that ends in cnn.com

# filter any domain that starts with adserver

This option can be set to one of `bre`, `ere`, or `fnmatch`. If `bre` is set, the rules specified in the filter file
are matched using POSIX basic regular expressions, when set to `ere`, using POSIX extended regular
expressions, and when set to `fnmatch` using the `fnmatch` function as specified in the manpage `man 3p
fnmatch`. `fnmatch` matching is identical to what's used in the shell to match filenames, so for example
`*.google.com` matches everything that ends with `.google.com`. If you don't know what regular
expressions are or you're using filter lists from 3rd party sources, `fnmatch` is probably what you want. It's
also the fastest matching method of the three.

FilterURLs

If this boolean option is set to `Yes` or `On`, filtering is performed for URLs rather than for domains. The
default is to filter based on domains.

Note that filtering for URLs works only in plain HTTP scenarios. Since HTTPS has become ubiquitous
during the last years, this will only work on a tiny fraction of websites, so it is recommended not to use
this option.

FilterExtended

Deprecated. Use `FilterType ere` instead. If this boolean option is set to `Yes`, then extended POSIX
regular expressions are used for matching the filter rules. The default is to use basic POSIX regular
expressions.

FilterCaseSensitive

If this boolean option is set to `Yes`, then the filter rules are matched in a case sensitive manner. The
default is to match case-insensitively, unfortunately. If you set this to `Yes`, then your matching will be
almost twice as fast. This setting affects only `bre` and `ere` FilterTypes, fnmatch is always case sensitive.

FilterDefaultDeny

The default filtering policy is to allow everything that is not matched by a filtering rule. Setting
`FilterDefaultDeny` to `Yes` changes the policy do deny everything but the domains or URLs matched by
the filtering rules. In other words, if set to `No` the Filter list acts as a blacklist, if set to `Yes` as a
whitelist.

Anonymous

If an `Anonymous` keyword is present, then anonymous proxying is enabled. The headers listed with
`Anonymous` are allowed through, while all others are denied. If no Anonymous keyword is present, then
all headers are allowed through. You must include quotes around the headers.

Most sites require cookies to be enabled for them to work correctly, so you will need to allow cookies
through if you access those sites.

Example:

Anonymous "Host"
Anonymous "Authorization"
Anonymous "Cookie"

ConnectPort
 This option can be used to specify the ports allowed for the CONNECT method. If no `ConnectPort` line
is found, then all ports are allowed. To disable CONNECT altogether, include a single ConnectPort line
with a value of `0`.

ReversePath

Configure one or more ReversePath directives to enable reverse proxy support. With reverse proxying it's
possible to make a number of sites appear as if they were part of a single site.

If you uncomment the following two directives and run Tinyproxy on your own computer at port 8888,
you can access example.com, using http://localhost:8888/example/.

ReversePath "/example/" "http://www.example.com/"

ReverseOnly

When using Tinyproxy as a reverse proxy, it is STRONGLY recommended that the normal proxy is turned
off by setting this boolean option to `Yes`.

ReverseMagic

Setting this option to `Yes`, makes Tinyproxy use a cookie to track reverse proxy mappings. If you need to
reverse proxy sites which have absolute links you must use this option.

ReverseBaseURL

The URL that is used to access this reverse proxy. The URL is used to rewrite HTTP redirects so that they
won't escape the proxy. If you have a chain of reverse proxies, you'll need to put the outermost URL here
(the address which the end user types into his/her browser). If this option is not set then no rewriting of
redirects occurs.

Support
Feel free to report a new bug or suggest features via github issues.
Tinyproxy developers hang out in #tinyproxy on irc.libera.chat.

Published with GitHub Pages