TINYPROXY.CONF(5)

💖 NAME 💖

Okay bestie, welcome to the TINYPROXY.CONF(5) page from the Tinyproxy manual — it's literally all about tinyproxy.conf, the Tinyproxy HTTP proxy daemon configuration file. Periodt. 💅

✨ SYNOPSIS ✨

tinyproxy.conf

🦋 DESCRIPTION 🦋

So tinyproxy(8) reads its configuration file, and that file is usually chillin' at /etc/tinyproxy/tinyproxy.conf — or you can pass it to Tinyproxy with -c on the command line. This manpage is here to explain the syntax and contents of that config file, no cap. 🫶

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. Some string values must be enclosed in double quotes (") as noted below. Slay. 🌸

The possible keywords and their descriptions are as follows:

• User — the user that the Tinyproxy process should run as, after the initial port-binding has been done as the root user. You can specify either the user name or the UID. 👑
• Group — the group that the Tinyproxy process should run as, after the initial port-binding has been done as the root user. You can specify either the group name or the GID. 🎀
• Port — the port that 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 lets you specify which address Tinyproxy will bind to for outgoing connections. This parameter may be specified multiple times, and 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. Enclose the file location in double quotes. 🍓
• DefaultErrorFile — the HTML template file returned when an error occurs for which no specific error file has been set. Enclose in double quotes. 🎀
• StatHost — the host name or IP address that is treated as the stat host. Enclose in double quotes. Whenever Tinyproxy receives a request for the stat host, it returns 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 — the HTML file that Tinyproxy sends in response to a request for the stat host. Enclose in double quotes. 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 — the location of the file to which Tinyproxy writes its debug output. Enclose in double quotes. 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 — the location of the file where the main Tinyproxy process stores its process ID for signaling purposes. Enclose in double quotes. 🫶
• 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.
    • a site_spec is either a full domain name, a domain name starting with a ., in which case it is treated as a suffix, or an ip/mask tuple. the site_spec needs to be double-quoted. 🦋
  • upstream none "site_spec" turns off upstream support for sites matching site_spec; that means the connection is done directly.

It's recommended to use raw IP addresses to specify the upstream host, so no costly DNS lookup has to be done everytime it is used. IPv6 addresses need to be enclosed in square brackets. 🌈

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 or ::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

• BasicAuthRealm — in case "BasicAuth" is configured, the "realm" information. "Proxy Authentication Required" status http 407 "error-response" can be customized. 💖
  • defaults in code to "Tinyproxy" (PACKAGE_NAME), if not configured.
• 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. Enclose in double quotes. 🦋
• 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... 😭

Bestie, for real, this one is a compliance-breaking stealth-mode move — do not touch it unless you know exactly what you're 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
^cnn\.com$

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

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

# filter any domain that ends in cnn.com
cnn\.com$

# filter any domain that starts with adserver
^adserver

🌸 FilterType 🌸

Okay so this one lets you pick how your filter rules get matched, and you've got three flavors: bre, ere, or fnmatch.

• bre — your rules in the filter file get matched with POSIX basic regular expressions
• ere — same idea but POSIX extended regular expressions
• fnmatch — matching happens via the fnmatch function, exactly like man 3p fnmatch says. It's literally the same matching your shell uses to glob filenames, so for example *.google.com catches everything ending in .google.com ✨

Ngl, if you have no clue what a regular expression even is, or you're just importing filter lists from 3rd party sources, fnmatch is probably your girl. It's also the fastest of the three, so like… win-win 💅

🦋 FilterURLs 🦋

Set this boolean to Yes or On and filtering happens on URLs instead of domains. Default? Domain-based filtering, bestie.

Heads up! URL filtering only works in plain HTTP situations. HTTPS is literally everywhere these days, so this'll only work on a tiny fraction of websites — so like, don't use this option, fr fr 🙈

🎀 FilterExtended 🎀

Deprecated. Use FilterType ere instead — that's the whole vibe now.

If you still set this boolean to Yes, extended POSIX regular expressions get used to match your filter rules. Default is basic POSIX regular expressions.

⭐ FilterCaseSensitive ⭐

Set this to Yes and your filter rules match in a case sensitive way. The default is case-insensitive matching, unfortunately 😭

The glow-up: set it to Yes and your matching is almost twice as fast. Obsessed.

Quick note though — this setting only affects the bre and ere FilterTypes. fnmatch is always case sensitive, no exceptions, periodt.

💜 FilterDefaultDeny 💜

The default filtering policy is: everything that isn't matched by a rule is allowed through. Setting FilterDefaultDeny to Yes flips that — now everything is denied except the domains or URLs your rules matched.

So in other words:

• set it to No → your filter list is a blacklist
• set it to Yes → your filter list is a whitelist

🧚 Anonymous 🧚

If an Anonymous keyword shows up, anonymous proxying is enabled 👑. The headers you list with Anonymous are allowed through, and every other header gets denied. If there's no Anonymous keyword at all, then all headers are allowed through.

You must put double quotes around the headers, iykyk.

Most sites need cookies enabled to work right, so if you're hitting those sites, you'll need to let cookies through.

Example:

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

🌈 ConnectPort 🌈

This one lets you specify which ports are allowed for the CONNECT method. No ConnectPort line anywhere? Then all ports are allowed. Wanna kill CONNECT entirely? Just include a single ConnectPort line with a value of 0 💀

🍓 ReversePath 🍓

Configure one or more ReversePath directives and boom — reverse proxy support is on. With reverse proxying you can make a bunch of sites appear as if they were all part of a single site. Main character energy for real.

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

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

🌸 ReverseOnly 🌸

When you're using Tinyproxy as a reverse proxy, it is STRONGLY recommended that you turn the normal proxy off by setting this boolean option to Yes. Like, please. For me. 🫶

✨ ReverseMagic ✨

Set this to Yes and Tinyproxy uses a cookie to track reverse proxy mappings. If you need to reverse proxy sites that have absolute links, you must use this option. Non-negotiable.

🦋 ReverseBaseURL 🦋

The URL used to access this reverse proxy. It gets used to rewrite HTTP redirects so they don't escape the proxy. Got a chain of reverse proxies? Then put the outermost URL here — the address the end user types into his/her browser. If you don't set this option, then no rewriting of redirects happens at all.

---

💀 BUGS 💀

To report bugs in Tinyproxy, please visit <https://tinyproxy.github.io/>.

👀 SEE ALSO 👀

tinyproxy(8)

💖 AUTHOR 💖

This manpage was written by the Tinyproxy project team.

🎀 COPYRIGHT 🎀

Copyright (c) 1998-2024 the Tinyproxy authors.

This program is distributed under the terms of the GNU General Public License version 2 or above. See the COPYING file for additional information.

---

And that's a wrap, bestie! 🫶 This little beauty is from Tinyproxy Version 1.11.3, dated 2026-06-18, and it lives its best life as TINYPROXY.CONF(5). Go configure something iconic 💅✨