PIXELSERV-TLS(1)

NAME
pixelserv-tls - a tiny bespoke HTTP/1.1 server for adblock and accelerating web browsing.

SYNOPSIS
pixelserv-tls [ip_addr | hostname] [-2] [-A PORT] [-B [CERT_FILE]] [-c CERT_CACHE_SIZE] [-f] [-k HTTPS_PORT] [-l] [-l LEVEL] [-n IFACE] [-O KEEPALIVE_TIME] [-p HTTP_PORT] [-R] [-s STATS_HTML_URL] [-t STATS_TXT_URL] [-T MAX_THREADS] [-u USER] [-z CERT_PATH]

DESCRIPTION
pixelserv-tls is a tiny bespoke webserver supporting HTTPS and SNI. It acts on behalf of hundreds of thousands of advert/tracker servers and responds to all requests with nothing. It speeds up your browsing experience as well as eliminating page errors. pixelserv-tls supports TLS 1.0, TLS 1.2 and TLS 1.3 and accepts a wide range of browsers and client devices. It automatically generates server certificate for blocked domains on their first visits and saved to disk for reuse. pixelserv-tls could log tracker URLs and uploading attemps to syslog. It is a useful tool for inspecting wrongly blocked domains that cause page trouble and exposing privacy breaches by rogue websites.

OPTIONS

ip_addr, hostname
    Specify an IP address pixelserv-tls shall listen on. Hostname can be used in place of IP address. If omitted and no '-n IFACE' specified, pixelserv-tls will listen on 0.0.0.0.

-2  Disable HTTP 204 response to '/generate_204' requests. In the event that Chrome detects network issues that might be caused by a captive portal, Chrome will make a cookieless request to http://www.gstatic.com/generate_204 and check the response code. If that request is redirected, Chrome will open the redirect target in a new tab on the assumption that it's a login page.

-A PORT
    Specify a port where administrative URIs will be accepted and processed. If specified, URIs '/servstats', '/servstats.txt', '/log=LEVEL' (but not '/ca.crt') are only allowed on this port and over HTTPS. Default is none. When not specified, these URIs are allowed on any ports and work over both HTTP and HTTPS. An admin port facilitates firewall rules to impose better control over who could access these URIs.

-B [CERT_FILE]
    Conduct crypto and disk benchmark. If optional CERT_FILE is provided, it is looked up in CERT_PATH and used instead. The benchmark repeats the process of generating certficate to disk and loading certificate from disk. The same time sensitive routines from normal operation are re-used and measured to provide an estimate of performance. The result is mainly good for comparing CPU power. Disk access is a little portion of the total time. When a new client connects, a certificate lookup is performed in cache and then CERT_PATH. If not found in both, the certificate will be generated asychronously. The generation is time expensive but considered a rare event. If not in cache but on disk, the certificate is loaded into cache. The loading is less expensive but yet consist a sizeable portion of total overhead before the client can actually send its requests. With SSL cache and session resumption in v2.1.0, load certificates from disk is also considered rare events.

-c CERT_CACHE_SIZE
    Specify the maximum number of certificates to be cached in memory. More cache certificates imply higher maximum RAM usage. If omitted, default is 100.

-f  Stay in foreground. Do not daemonize the process.

-k HTTPS_PORT
    Specify a port pixelserv-tls shall accept HTTPS connections. This option can be set multiple times to specify more than one port. If omitted, default is 443.

-l  For backward compatibility. Equivalent to '-l 4'.

-l LEVEL
    Set log level. Messages will be output to syslog. pixelserv-tls has six tiers of logging with increasing verbosity. 0 - critical 1 -error 2 - warning 3 - notice 4 - info 5 debug. To log request URLs and POST contents, set level to 4 or higher. If omitted, default is set to 1.

-n IFACE
    The network interface pixelserv-tls shall listen on. If omitted and no ip_addr or hostname specified, pixelserv-tls will listen on all interfaces.

-o SELECT_TIMEOUT
    Deprecated since v2.2.1.

-O KEEPALIVE_TIME
    Set the minimum amount of time in seconds that a HTTP/1.1 persistent connection shall be kept alive. The connection will be closed if client side shuts down or this amount of time expires without receiving any request.

-p HTTP_PORT
    Specify a port pixelserv-tls shall accept HTTP connections. This option can be set multiple times to specify more than one port. If omitted, default is 80.

-R  Disable redirection to encoded path in tracker URLs if specified.

-s STATS_HTML_URL
    Customize the path where pixelserv-tls shall respond with the HTML verson of server statistics page. If omitted, default is '/servstats'.

-t STATS_TXT_URL
    Customize the path where pixelserv-tls shall respond with the plain text verson of server statistics page. If omitted, default is '/servstats.txt'.

-T MAX_THREADS
    Set the limit on maximum number of concurrent threads. pixelserv-tls currently handles one HTTP/1.1 persistent connection in each thread. This limit will prevent overloading the system if pixelserv-tls happens to be serving many clients. If omitted, default is 1200. Default is more than enough for all SOHO environemnts.

-u USER
    Set the user account pixelserv-tls shall use after dropping root. Default is 'nobody'.

-z CERT_PATH
    Specify the directory where the CA certificate (ca.crt) and its private key (ca.key) are loaded on startup. Certificates that are automatically generated are also saved to CERT_PATH. If omitted, default is '/var/cache/pixelserv' ('/opt/var/cache/pixelserv' on Entware). 'nobody' or 'USER' if '-u USER' is set should have read/write permission to CERT_PATH.

SUPPORTED URI/API

  /ca.crt
Retrieve ca.crt file located in CERT_PATH. On mobile client devices, the OS will prompt you and guide you through the installation of the CA cert.

  /favicon.ico
pixelserv-tls favicon.

  /log=LEVEL
Change the log LEVEL without restarting pixelserv-tls. LEVEL is an integer between 0 and 5 inclusive. The same definition as in command line option `-l LEVEL`. See above.

  /servstats /servstats.txt
Retrieve the servstats page in HTML and plain text formats respectively.

Example: http://<your pixelserv ip>/servstats.txt

This will retrieve the servstats page in plain text.

SERVSTATS COUNTERS
Servstats counters measure various aspect of pixelserv-tls operations. Most counters are self-explanatory on the servstats page, accessible through URI '/servstats'. More subtle counters are described below.

  Service Threads
A service thread is responsible for one HTTP/1.1 persistent connection. Both a client and the server have to keep it alive. If a client is idle without sending any requests within KEEPALIVE_TIME seconds, the server will close the connection and end the service thread. If a client decides to close a connection, the server will end the service thread.

kcc This is the number of service threads currently active. In other words, number of active connections. On a busy instance, this counter could be in tens or close to a hundred. The longer the KEEPALIVE_TIME the higher this counter would usually appear to be.

kmx This registers the largest kcc ever hit.

kvg Some service threads will process more requests than others. The number of requests processed in a thread is completely decided by clients. This counter calculates the average number of requests done in one service thread. It's an exponential moving average.

krq This counter registers the largest number of requests ever processed by one service thread.

  TLS Handshake
A new client connecting to pixelserv-tls over HTTPS has to pass TLS protocol handshakes. If successful, then the client could make one or more requestst that will register in slh. Otherwise, one of the slm, sle, and slu will be incremented by one. Counts in slu is broken down further to assist users in diagnosing issues and inspecting privacy breaches.

slh Incremented by one when a requested is received over HTTPS and successfully processed.

slm If a server cert does not exist on disk, this counter is incremented by one. The new cert will be asynchronouslly generated and saved to disk.

sle If a server cert exists on disk but results in error when loaded for use, this counter is incremented by one. Unless your disk is corrupted or certs are damaged on disk, sle is very rare.

slu If TLS handshakes fail other than above reasons, this counter is incremented by one. slu is further classified into two common types, uca and uce. Note that slu includes more than these two types.

uca When a TLS handshake fails due to the client not recognise your Pixelserv CA cert, this counter is incremented by one. If your clients do not have Pixelserv CA imported, then the error is legitimate. If your clients have Pixelserv CA imported already, it is worth further check. Often a client could be purposely coded not to honour user root CAs for dubious reasons. Users are recommended to turn on log LEVEL 2. Try to catch the client ip and server name in syslog. Check server name against reputable online sources. Check client ip and port to catch the provoking apps on client devices.

ucb Clients report "bad certificate" on the server certificate presented by pixelserv-tls and then shuts down the connection. Usually this indicates a client is proactively checking the certficiate's fingerprint against its hardcoded data. More and more apps are doing so to not exposing their upload contents to users.

uce When a TLS handshake fails due to the client not recognise the server cert, this counter is incremented by one. Very likely such cases are of dubious nature. A client may be purposedly coded to check the server cert against stored fingerprint. If mismatch, the client refuses to proceed. This is alarming and often indicates a client attempts to connect to a rogue server. Users should turn on log LEVEL 2. Catch the client ip and server name in syslog and proceed with similar investigation steps as in uca

ush Similiar to ucb but the clients abruptly shuts down the connection without providing any reason.

  Other TLS related events

v13 v12 v10
    Indicates number of HTTPS requests that are transmitted in a particular TLS version, v1.3, v1.2 and v1.0 respectively.

zrt Indicates number of HTTPS requests that are transmitted in TLS 1.3 Early Data aka zero round-trip or 0-RTT. This significantly speeds up the first request on a resumed HTTPS connection between a client and pixelserv-tls.

  Flags next to version string

tfo Indicates support for TCP Fast Open that is available on Linux kernel >= 3.7 and recent macOS and Windows. If this flag is missing, then TCP Fast Open is not supported in your version of pixelserv-tls.

tls1_3
    Indicates support for TLS 1.3 that is automatically enabled when pixelserv-tls is linked to OpenSSL >= v1.1.1. If this flag is missing, then TLS 1.3 is not available in your version of pixelserv-tls.

AUTHOR
This manpage is authored by kvic (aka kvic-z on GitHub) https://kazoo.ga/pixelserv-tls/

HISTORY
pixelserv first appeared on Internet around 2003. About 30 lines of code written in PERL, it is a minimal webserver that serves a one-pixel GIF over HTTP. mstombs took the idea and rewrote in C for lightweight and speed starting from 2009. HunterZ developed further from 2013 onwards and completed HTTP functionality. Since 2015, kvic added support for HTTPS, SNI, multi-threading, automatic certificate generation, access logging, HTTP/1.1 persistent connections, TLS session cache and resumption, build with GNU Autotools and etc. pixelserv was renamed to pixelserv-tls to signify HTTPS functionality, and has since undergone extensive optimization for speed and lightweight.

COPYRIGHT
Copyright © 2015-2019 kvic aka kvic-z on GitHub
Copyright © 2013-2015 HunterZ on GitHub
Copyright © 2009-2013 mstombs on GitHub

This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

BUGS

  Reporting Bugs
Please submit a ticket at https://github.com/kvic-z/pixelserv-tls/issues

  Known Bugs
None at the moment