• tinyproxy

Tinyproxy is a non-caching, HTTP proxy and TCP tunnel. Its main feature is the ability to restrict Internet access to a list of approved sites (thus keeping the kiddies' eyes clean). If access control is your only requirement, then tinyproxy is a worthwhile alternative to Squid, a more full-featured proxy that is ten times larger.

• Project Homepage: http://tinyproxy.sourceforge.net/

• Package: http://openwrt.alphacore.net/tinyproxy_1.6.3_mipsel.ipk
  (Note: This is not an official OpenWrt package, but was put together by florian, one of the developers.)

1. Configuration

• The configuration file is line-oriented
• Pathspecs must be enclosed in double-quotes.
• Case-insensitive

• The official (upstream) configuration file (whose comments provide the only official documentation) is at /tinyproxy.conf.

1.1. Daemon Settings

User username
Group groupname

• Drop privileges, changing EUID/EGID to this user/group.
  (Caveat: must be name, not number) Example:

  • user nobody
    group nogroup

  Default:
  • Don't change effective ID.

Port port_number
Listen ip_address

• Sets the TCP port and interface on which to listen for new connections. Example:

  • Port 8888
    Listen 192.168.0.1

  Defaults:

  • Port MUST be defined.

  • Listens to all interfaces.

Bind ip_address

• Set the interface to use for outgoing connections, such as to origin servers or upstream proxies. Example:

  • Bind 192.168.0.1

  Default:
  • none. OS decides.

PidFile "pathspec"

• (todo: find out what signals tinyproxy accepts) Example:

  • PidFile /var/run/tinyproxy.pid

  Default:
  • Don't create a pidfile.

1.2. Spawn Settings

StartServers integer
MinSpareServers integer
MaxSpareServers integer
MaxClients integer

• Manages how many child processes to keep around. Tinyproxy spawns StartServers children on startup, maintains the number of idle children between MinSpareServers and MaxSpareServers (by spawning or killing as necessary), but will never have more than MaxClients children at any given moment. Example:

  • StartServers 5
    MinSpareServers 5
    MaxSpareServers 10
    MaxClients 100
    

  Default:
  • ??

MaxRequestsPerChild integer

• The number of connections a child will accept before quitting. 0 = no limit, and should be used unless you experience memory leaks, in which case 10000 is a recommended value. Example:

  • MaxRequestsPerChild 0

  Default:
  • ??

Timeout seconds

• The maximum number of seconds of inactivity a connection is allowed to have before it is closed by tinyproxy. Example:

  • Timeout 600

  Default:
  • ??

1.3. Logging

LogLevel {info,connect,notice,warning,error,critical}
SysLog {On,Off}
LogFile "pathspec"

• Log all events of level LogLevel or greater. Strangely, 'debug' is not one of the available log levels. Also, note the unusual level connect, which logs at syslog-level info but isn't chatty at startup.
  If Syslog is set to On, it will log the events to syslogd using facility kern; this does not seem to be configurable. If Logfile is set, it will log directly to that file. If Syslog is On, Logfile is ignored. Example:

  • LogLevel Info
    Syslog On
    Logfile "/var/log/tinyproxy.log"

1.4. HTTP Headers

ViaProxyName string

• The HTTP RFC requires proxies to add a "Via:" header. ViaProxyName sets the value for that header. Example:

  • ViaProxyName "Tinyproxy Content-Filter"
    

  Default:
  • hostname

XTinyproxy host

• A header "X-Tinyproxy: client_ip_addr" is added to any request to host. Multiple XTinyproxy directives are allowed. Example:

  • XTinyproxy local.net

Anonymous "http_header"

• If any Anonymous directives are supplied, then all HTTP headers (from the server? from the client?) are filtered out except for those listed with Anonymous directives. (Personally, it seems backwards of how it ought to work.) Exception: Content-Length and Content-Type are always allowed through. Note: The quotes are part of the syntax and must be included. Example:

  • Anonymous "Cookie"

Upstream proxy_addr:port [domain or network]

• Supports going through another (upstream) proxy, potentially chosen based on which site is being accessed. For further examples, see the source distribution's /tinyproxy.conf. Example:

  • Upstream upstream.proxy.net:8080

1.5. Access Control -- clients

Allow host/network
Deny host/network

• Controls who may use the proxy. Networks may be specified in CIDR notation, or by name. Example:

  • Allow 10.0.0.0/24
    Allow localhost

1.6. Access Control -- servers

FilterDefaultDeny {Yes|No}
Filter "pathspec"
FilterURLs {On|Off}
FilterExtended {On|Off}
FilterCaseSensitive {On|Off}

• Controls what sites the user agent may access. FilterDefaultDeny sets whether we are taking a whitelist (Yes) or blacklist (No) approach to site blocking. Filter gives the path of the whitelist/blacklist file. By default, we filter based on hostname of the website, but URL regexp matches can also be supported, including using Extended (perl5?) regular expressions. Example:

  • FilterDefaultDeny Yes
    Filter "/etc/tinyproxy/filter"
    FilterURLs Off
    FilterExtended On
    FilterCaseSensitive Off
    

ConnectPort port

• The HTTP proxy protocol supports tunneling any type of TCP traffic through it via the CONNECT method. If there are any ConnnectPort directives, Tinyproxy will only tunnel the specified ports. Filtering (by hostname) also applies to such traffic. Example:

  • ConnectPort 443

1.7. Web Pages

ErrorFile staus_code "pathspec"
DefaultErrorFile "pathspec"

• If the request made by the client to tinyproxy generates an error, we can return an error-specific page or a generic error page. Example:

  • ErrorFile 403 "/tmp/tinyproxy/www/403-filtered.html"
    DefaultErrorFile "/tmp/tinyproxy/www/debug.html"

StatHost hostname
StatFile "pathspec"

• Any requests for the website hostname will return the file pathspec. Example:

  • StatHost tinyproxy.stats
    StatFile "/tmp/tinyproxy/www/stats.html"

1.8. Surrogate (Reverse Proxy)

ReverseOnly {Yes|No}
ReversePath "URI" "URL"
ReverseMagic {Yes|No}
ReverseBaseURL "URL"

• (requires v1.7.0) Example:

  • ReverseOnly Yes
    ReversePath "/google/" "http://www.google.com/"
    ReverseMagic Yes
    ReverseBaseURL "http://localhost:8888/"
    

2. Troubleshooting

If you find the message "Could not allocate memory for child counting." in /etc/tinyproxy/tinyproxy.log, make sure the /tmp directory has the right permissions and is writable for nobody. The easiest way is to do a "chmod 1777 /tmp".

CategoryPackage