FAQ - kvic-z/pixelserv-tls GitHub Wiki

General

Running pixelserv-tls

Servstats Page

General

1. What is pixelserv-tls?

pixelserv-tls is a tiny bespoke webserver for adblock with HTTP/1.1 and HTTPS support that can act on behalf of hundreds of thousands of adv and tracker servers. It responds to all requests with nothing and can be configured to capture what adv and trackers intend to send them about you.

2. Why would I want pixelserv-tls

You'll already understand the benefit of DNS-based adblock over adblock plugin in browsers. pixelserv-tls is an important component in a DNS-based adblock solution. The other three important components are:

a DNS server e.g. DNSmasq
a list of known hostnames identified as adv and tracker servers, and
a script to prepare and manage the hostnames for use in DNS server.

pixelserv-tls speeds up browsing. Without pixelserv-tls, adv and tracer hostnames are commonly set to IP address, 0.0.0.0 - a special address that browsers connect and fail quickly. With pixelserv-tls, the same hostnames are set to hit a IP address where pixelserv-tls listens and serves adv requests.

A study of speed-up by pixelserv-tls is available here.

3. What is Root CA certificate and what are the other certificates?

An explanation of PKI is beyond this question. A Root CA certificate is installed and trusted by browsers and operating systems. It's the basis of all trust. Hence, the creation of a Root CA certificate is tightly controlled by industry authorities. A Root CA is used to issue certificates for webservers that require HTTPS connections.

A Root Certificate issued by an industrial authority e.g. VeriSign can be used with pixelserv-tls. Perhaps no one is doing that in practice. All users manually create a self-signed CA certificate and use it in pixelserv-tls.

pixelserv-tls loads this CA certificate (and its associated private key) on startup, and generates certificates for webservers on-demand. Once a certificate is generated on its first request e.g. to doubleclick.com, the certificate is saved and reused in subsequent requests.

This self-signed CA certificate requires to be manually imported into clients just like other Root CA certificates are done for you by browser and OS vendors.

4. Does pixelserv-tls exposure to MITM attacks?

pixelserv-tls is not exposed to MITM attacks. Since you are in sole control of both pixelserv-tls and the CA certificate (and its private key) on your home network, no one is able to spoof you by using this CA certificate.

In a large organisation, your admin may run pixelserv-tls on your organisation's network, and use a Root CA issued by industrial authority or use a self-signed CA certificate, and have the CA certificate installed in your managed client device, then your client may be talking to e.g. doubleclick.com which is actually not the real one but pixelserv-tls. In this scenario though your IT team shall be fully aware of what they're doing.

Last but not least, you should be very cautious about being asked to import a self-signed certificate by a person who you do not trust. That is good practice in general.

5. What is about the v2 naming scheme change in versions?

To clean up the clutter, v2 reverts back to the traditional MAJOR.MINOR.MICRO naming scheme. The first version number for v2 release is v2.0.0. Previous versions (v35.HZ12.Kc to v35.HZ12.Kk) from the past two years were considered pixelserv-tls v1.x.

To retain the spirit of alphabet soup that pixelserv-tls started with, Km, Kn, Ko...etc will continue their life as code name for development. For example, the next development will be "Km" (circa Nov 2017) in which primary focus will be further efficiency in HTTPS.

Running pixelserv-tls

6. When will the CA and other certificates expire?

If you follow the instructions, your manually created CA certificate will be good for TEN years. The certificates generated by pixelserv-tls will also be good for TEN years, counting from the day a certificate is generated.

Feel free to purge the automatically generated certificates in CERT_PATH from time to time though of no merits. They will be generated on-demand when you visit the adv server of the deleted certificates.

WARNING

You may want to backup ca.crt and ca.key to another PC or directory. This will save you lots of hassle on re-importing a new CA certificate into client devices if the original CA certificate in CERT_PATH is lost or damaged.

7. Can I use an intermediate CA certificate as the CA certificate in pixelserv-tls?

Yes. You can 👍

If it is an intermediate CA certificate issued by an industry authority, then simply save it as ca.crt and its associated private key as ca.key under CERT_PATH.

If it's an intermediate CA certificate issued by a self-signed CA certificate, then save it together with the self-signed CA certificate in ca.crt, and the private key of the intermediate CA in ca.key under CERT_PATH.

8. How do I capture access log to file?

You can specify -l 4 (or above) to start pixelserv-tls. URL access will be logged to syslog (as of v2).

Ensure that you have a robust syslog running. The access log is chatty and could well swamp your typical home router's syslog. If you are running pixelserv-tls on a full-blown Linux system, you are fine and can further filter pixelserv-tls log to its own log files.

For home routers supporting Entware-ng, you can consider replace your stock syslog with syslog-ng. You can find some pointers on this blog.

9. Why is there still white space left over for advertisements?

When people use an adblock add-on in browsers, the space used for advertisement is not in view. Using pixelserv-tls with a DNS-based adblocker (e.g. AB-Solution), there is still white space left over for the eliminated advertisement.

That's normal. It is because pixelserv-tls only substitutes one pixel or empty content in for whatever the original content was to be. There are no modifications to a page's HTML code that a browser add-on usually does. Some advertisements are embedded using DIV, TABLE or even IFRAME tags with fixed size to format the content around an expected advertisement to be received from major ad networks. When they are subbed for only one pixel or empty content, you have that otherwise empty fixed space left over. A browser add-on cleans up the HTML formatting by removing those tags and fixed size specification so that the empty space is eliminated as well.

For other advertisements which are more logically and perhaps advancedly embedded in a page, the white space will collapse into nothing as a result of receiving one pixel or empty content from pixelserv-tls.

Servstats Page

10. What is the servstats page?

The servstats page displays statistical data about your adv and tracker URL requests e.g. total requests, failed HTTPS requests and etc. You can check out the sample page.

11. Why is my 'rmx' a few hundred kilobytes?

'rmx' indicates the largest size in byte of URL requests e.g. HTTP GET and HTTP POST that ever hit pixelserv-tls. HTTP GET requests max out around 16KiB. High 'rmx' in hundreds of KiB indicates HTTP POST requests. Adv and tracker vendors use HTTP POST to send data collected about you back to their servers.

You can refer to the above question on how to capture access log. HTTP POST contents are usually base64 encoded and thus require decode to be comprehensible.

12. Why is my 'tav' 0ms?

pixelserv-tls significantly increases its processing efficiency with v2 release. On a fast AMD64 system, requests usually finish in <1ms. Hence, they're registered as 0ms on the counter.

On a 800MHz ARM Cortex-A9, a new HTTP request takes only a few ms. A burst of plain HTTP requests to the same adv host will sink tav below 1ms.