pixelserv-tls is a fork of pixelserv with added support for HTTPS - the tiny webserver that responds to all requests with “nothing” and yet particularly useful for whitelisting hosts on troubled websites, and for mining “big data” on adservers and trackers.
Certificates for adserver domains are automatically generated at real-time upon first request. All requests to adserver are optionally written to syslogd. The stats in text format are preserved, good for command line parsing. The same stats in HTML format are revamped to be more legible.
Prepare your Root CA cert
pixelserv-tls requires a Root CA cert to run. Assume OpenSSL already installed in your systems. Execute the following statements in a command shell:
openssl genrsa -out ca.key 1024
openssl req -key ca.key -new -x509 -days 3650 -sha256 -extensions v3_ca -out ca.crt -subj "/CN=Pixelserv CA"
These create a 1024-bit CA cert with Common Name “Pixelserv CA” in
Import ca.crt into Clients
Note that installation of
ca.cert on client OS is not mandatory but recommended. Clients without
ca.crt will interact smoothly with pixelserv-tls.
In Terminal, type
sudo security add-trusted-cert -d -r trustRoot -k /System/Library/Keychains/SystemRootCertificates.keychain ca.crt
Note: since OS X El Capitan, System Integrity Protection need to be disabled first. Reboot, then run the above command line. System Integrity Protection can be enabled afterward. Here is a SIP tutorial to disable/enable System Integrity Protection.
ca.crt need to be re-added after every OS update unfortunately.
Multiple ways to get it done. The simplest is to email yourself
ca.crt. Go to your iOS device. Click on the attachment and follow the instructions.
Here is a guide by IBM that provides a bit more details.
Chrome/IE/Edge uses Root CA certs from Windows system-wide repository. Follow this Windows guide carefully to add ca.cert into the system-wide Root CAs.
Firefox manages its own repository of Root CAs. Follow this Firefox guide only if you also run Firefox.
This Android guide looks interesting. I don’t have Android devices. Please provide feedback after you tried.
A few examples of launching pixelserv-tls:
pixelserv-tls 192.168.1.1 -p 80 -p 8080 -k 443 -k 2443 -u admin
The first example runs pixelserv as
nobody with non-root privilege. Listens on port 80 for HTTP and 443 for HTTPS. The second example additionally listens on 8080 for HTTP and 2443 for HTTPS, and runs as
admin - the root account in ASUSWRT.
pixelserv-tls is now (circa April 2016) available on Entware-NG. Use
opkg install pixelserv-tls to install on supported platforms including Asuswrt/Merlin.
Going forward binaries for Asuswrt/Merlin in Releases section will be provided only on requests.
New command line switches
$ pixelserv-tls --help Usage:pixelserv-tls ip_addr/hostname (all if omitted) -2 (disable HTTP 204 reply to generate_204 URLs) -f (stay in foreground - don't daemonize) -k https_port (443 if omitted) -l (log access to syslog) -n i/f (all interfaces if omitted) -o select_timeout (10 seconds) -p http_port (80 if omitted) -r (deprecated - ignored) -R (disable redirect to encoded path in tracker links) -s /relative_stats_html_URL (/servstats if omitted) -t /relative_stats_txt_URL (/servstats.txt if omitted) -u user ("nobody" if omitted) -z path_to_https_certs (/opt/var/cache/pixelserv if omitted)
-z are new options.
-k specifies one https port and use multiple times for more ports.
-l will log all ad requests to syslogd. If we don’t specify in the command line, no logging which is the default. Access logging can generate lots of data. Either use it only when troubleshoot a browsing issue or you have a more capable syslog on your router (e.g. syslog-ng + logrotate from Entware).
-z specifies the path to certs storage. Each ad domain and its sub-domain will require one wildcard cert. Generated certs will be stored and re-used from there.
Stats are viewable by default at http://pixelservip/servstats.txt (for raw text format) or http://pixelservip/servstats for html format), where pixelserv ip is the ip address that pixelserv is listening on.
|uts||uptime in seconds|
|req||number of connection requests|
|avg||average request size in bytes|
|rmx||maximum request size in bytes|
|tav||average request processing time in milliseconds|
|tmx||maximum request processing time in milliseconds|
|err||number of connections resulting in processing errors (syslog may have details)|
|tmo||number of connections that timed out while trying to read a request from the client|
|cls||number of connections that were closed by the client while reading or replying to the request|
|nou||number of requests that failed to include a URL|
|pth||number of requests for a path that could not be parsed|
|nfe||number of requests for a file with no extension|
|ufe||number of requests for an unrecognized/unhandled file extension|
|gif||number of requests for GIF images|
|bad||number of requests for unrecognized/unhandled HTTP methods|
|jpg||number of requests for JPEG images|
|png||number of requests for PNG images|
|swf||number of requests for Adobe Shockwave Flash files|
|ico||number of requests for ICO files (usually favicons)|
|slh||Y||number of HTTPS requests with a good certifcate (cert exists and used)|
|slm||Y||number of HTTPS requests without a certficate (cert missing for ad domain)|
|sle||Y||number of HTTPS requests with a bad cert (error in existing cert)|
|slu||Y||number of unrecognized HTTPS requests (none of slh/slm/sle)|
|sta||number of requests for HTML stats|
|stt||number of requests for plaintext stats|
|204||number of requests for /generate_204 URLs|
|rdr||number of requests resulting in a redirect|
|pst||number of requests for HTTP POST method|
|hed||number of requests for HTTP HEAD method|
|log||Y||status of access loggging|
Forum Discussion for pixelserv-tls
- pixelserv-tls: Pixelserv with support for HTTPS born here.