forked from HunterZ/pixelserv
-
Notifications
You must be signed in to change notification settings - Fork 23
Command Line Options
kvic-z edited this page Dec 29, 2018
·
11 revisions
PIXELSERV-TLS(1) General Commands Manual PIXELSERV-TLS(1)
NAME
pixelserv-tls - a tiny bespoke HTTP/1.1 server for adblock and acceler-
ating 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 expe-
rience 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 pro-
vided, 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 pro-
vide 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 expen-
sive but considered a rare event. If not in cache but on disk,
the certificate is loaded into cache. The loading is less expen-
sive 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 certifi-
cates from disk is also considered rare events.
-c CERT_CACHE_SIZE
Specify the maximum number of certificates to be cached in mem-
ory. 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 per-
sistent 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 speci-
fied.
-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. pix-
elserv-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 omit-
ted, 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/pix-
elserv' 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 respec-
tively.
Example: http:///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 pro-
cessed 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 incre-
mented 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 pre-
sented by pixelserv-tls and then shuts down the connection. Usu-
ally this indicates a client is proactively checking the certfi-
ciate'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 connec-
tion 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 pix-
elserv-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, auto-
matic certificate generation, access logging, HTTP/1.1 persistent con-
nections, TLS session cache and resumption, build with GNU Autotools
and etc. pixelserv was renamed to pixelserv-tls to signify HTTPS func-
tionality, and has since undergone extensive optimization for speed and
lightweight.
COPYRIGHT
Copyright (C) 2015-2019 kvic aka kvic-z on GitHub
Copyright (C) 2013-2015 HunterZ on GitHub
Copyright (C) 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 PARTIC-
ULAR PURPOSE.
BUGS
Reporting Bugs
Please submit a ticket at https://github.com/kvic-z/pixelserv-
tls/issues
Known Bugs
None at the moment
PIXELSERV-TLS(1)