pixelserv-tls.1

.TH PIXELSERV-TLS 1
.SH NAME
pixelserv-tls \- a tiny bespoke HTTP/1.1 server for adblock and accelerating web browsing.
.SH SYNOPSIS
.B pixelserv-tls 
[\fIip_addr\fR | \fIhostname\fR]
[\fB\-2\fR]
[\fB\-A\fR \fIPORT\fR]
[\fB\-B\fR \fI[CERT_FILE]\fR]
[\fB\-c\fR \fICERT_CACHE_SIZE\fR]
[\fB\-f\fR]
[\fB\-k\fR \fIHTTPS_PORT\fR]
[\fB\-l\fR]
[\fB\-l\fR \fILEVEL\fR]
[\fB\-n\fR \fIIFACE\fR]
[\fB\-O\fR \fIKEEPALIVE_TIME\fR]
[\fB\-p\fR \fIHTTP_PORT\fR]
[\fB\-R\fR]
[\fB\-s\fR \fISTATS_HTML_URL\fR]
[\fB\-t\fR \fISTATS_TXT_URL\fR]
[\fB\-T\fR \fIMAX_THREADS\fR]
[\fB\-u\fR \fIUSER\fR]
[\fB\-z\fR \fICERT_PATH\fR]

.SH DESCRIPTION
.B 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.

.B 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.

.B 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.

.SH OPTIONS
.TP
.BR \fIip_addr\fR ", " \fIhostname\fR
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.
.TP
.BR \-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.
.TP
.BR \-A " " \fIPORT\fR
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.
.TP
.BR \-B " " \fI[CERT_FILE]\fR
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.
.TP
.BR \-c " " \fICERT_CACHE_SIZE\fR
Specify the maximum number of certificates to be cached in memory. More cache certificates imply higher maximum RAM usage. If omitted, default is 100.
.TP
.BR \-f
Stay in foreground. Do not daemonize the process.
.TP
.BR \-k " " \fIHTTPS_PORT\fR
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.
.TP
.BR \-l
For backward compatibility. Equivalent to '-l 4'.
.TP
.BR \-l " " \fILEVEL\fR
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.
.TP
.BR \-n " " \fIIFACE\fR
The network interface pixelserv-tls shall listen on. If omitted and no ip_addr or hostname specified, pixelserv-tls will listen on all interfaces.
.TP
.BR \-o " " \fISELECT_TIMEOUT\fR
Deprecated since v2.2.1.
.TP
.BR \-O " " \fIKEEPALIVE_TIME\fR
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.
.TP
.BR \-p " " \fIHTTP_PORT\fR
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.
.TP
.BR \-R
Disable redirection to encoded path in tracker URLs if specified.
.TP
.BR \-s " " \fISTATS_HTML_URL\fR
Customize the path where pixelserv-tls shall respond with the HTML verson of server statistics page. If omitted, default is '/servstats'.
.TP
.BR \-t " " \fISTATS_TXT_URL\fR
Customize the path where pixelserv-tls shall respond with the plain text verson of server statistics page. If omitted, default is '/servstats.txt'.
.TP
.BR \-T " " \fIMAX_THREADS\fR
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.
.TP
.BR \-u " " \fIUSER\fR
Set the user account pixelserv-tls shall use after dropping root. Default is 'nobody'.
.TP
.BR \-z " " \fICERT_PATH\fR
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.

.SH SUPPORTED URI/API
.SS \fI/ca.crt\fR
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.
.SS \fI/favicon.ico\fR
pixelserv-tls favicon.
.SS \fI/log=LEVEL\fR
Change the log LEVEL without restarting \fIpixelserv-tls\fR. LEVEL is an integer between 0 and 5 inclusive. The same definition as in command line option `-l LEVEL`. See above.
.SS \fI/servstats\fR \fI/servstats.txt\fR
Retrieve the servstats page in HTML and plain text formats respectively.
.PP
Example: http://<your pixelserv ip>/servstats.txt
.PP
This will retrieve the servstats page in plain text.

.SH SERVSTATS COUNTERS

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

.SS 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 \fIKEEPALIVE_TIME\fR 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. 
.TP
.BR \fIkcc\fR
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.
.TP
.BR \fIkmx\fR
This registers the largest \fIkcc\fR ever hit.
.TP
.BR \fIkvg\fR
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.
.TP
.BR \fIkrq\fR
This counter registers the largest number of requests ever processed by one service thread.

.SS 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 \fIslh\fR. Otherwise, one of the \fIslm\fR, \fIsle\fR, and \fIslu\fR will be incremented by one. Counts in \fIslu\fR is broken down further to assist users in diagnosing issues and inspecting privacy breaches.
.TP
.BR \fIslh\fR
Incremented by one when a requested is received over HTTPS and successfully processed.
.TP
.BR \fIslm\fR
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.
.TP
.BR \fIsle\fR
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, \fIsle\fR is very rare.
.TP
.BR \fIslu\fR
If TLS handshakes fail other than above reasons, this counter is incremented by one. \fIslu\fR is further classified into two common types, \fIuca\fR and \fIuce\fR. Note that \fIslu\fR includes more than these two types.
.TP
.BR \fIuca\fR
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.
.TP
.BR \fIucb\fR
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.
.TP
.BR \fIuce\fR
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 \fIuca\R.. 
.TP
.BR \fIush\fR
Similiar to \fIucb\fR but the clients abruptly shuts down the connection without providing any reason.

.SS Other TLS related events
.TP
.BR \fIv13\fR " " \fIv12\fR " " \fIv10\fR
Indicates number of HTTPS requests that are transmitted in a particular TLS version, v1.3, v1.2 and v1.0 respectively.
.TP
.BR \fIzrt\fR
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.

.SS Flags next to version string
.TP
.BR \fItfo\fR
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.
.TP
.BR \fItls1_3\fR
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.

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

.SH 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.

.SH COPYRIGHT
Copyright \(co 2015\-2019 kvic aka kvic-z on GitHub
.br
Copyright \(co 2013\-2015 HunterZ on GitHub
.br
Copyright \(co 2009\-2013 mstombs on GitHub
.PP
This is free software; see the source for copying conditions.  There is NO warranty;  not  even  for  MERCHANTABILITY  or FITNESS FOR A PARTICULAR PURPOSE.

.SH BUGS
.SS Reporting Bugs
Please submit a ticket at https://github.com/kvic-z/pixelserv-tls/issues
.SS Known Bugs
None at the moment