Neverblock Proxy

What is it?

NeverBlock Proxy is a cross platform application with the purpose of handling API requests and caching of advertisements. This service runs in the background to provide the user with a more direct endpoint through which to fetch advertisements. It is not recommended to choose NeverBlock Proxy over the standard NeverBlock PHP solution, as it is not as extensive.

Occasionally adblockers will aggressively target sites which means NeverBlock PHP will no longer work. If this is the case for your site then consider NeverBlock Proxy.


Download a pre-built archive for your specific platform

The files necessary to run NeverBlock ads are:

  • neverblock-conf.toml
  • redirect.html
  • neverblock-proxy


Put the files on the server

Once the files have been downloaded you can put them in a directory on your server as shown in the below screenshot:


Create the cache

Create a writable directory which will store the downloaded files. This can be created in the same folder, as we will be setting the path at a later point.


Update Mandatory Configuration

At the top of the neverblock-conf.toml there is a section marked Mandatory. In this section we will set our paths based on the configuration shown in the above screenshots. Be aware that it will be unique to your configuration

#     Mandatory     #

## Cache path (CAUTION: ALL files here will be purged at regular intervals!)
cache_path = "nb-cache/"

## Relative path to cache from web serving root (i.e "images/cache/", will default to cache_path if not set)
www_cache_path = "nb-proxy/nb-cache/"

## Path & filename to redirect html file (relative to web serving root - i.e. "misc/redirect.html")
www_redirect_path = "nb-proxy/redirect.html"

Start the service

Start the binary from a cmd prompt / terminal - this must be done inside the directory where it resides. This will start the service and you should now be able to make curl requests to localhost on port 8080.


A cURL request is used to get the zones. This request can be implemented in any chosen language. The cURL request will return a JSON payload with a click URL as well as a relevant image path. The image has also been downloaded to your specified path. When passing the user_ip be aware of the points made in Passing IPs. The structure of this request is as follows:

curl -X POST http://localhost:8080/serve \
    -H "Content-Type: application/json" \
    -d '{
  "user_ip": "",
  "user_agent": "curl/7.43.0",
  "language": "en;q=0.9",
  "referer": "",
  "zones": [
      "idzone": "1813348"
      "idzone": "1813348"
      "idzone": "1813348"

Using this structure we can see an example of this being used for PHP:

if (array_key_exists('HTTP_X_FORWARDED_FOR', $_SERVER)) {
    $ip = array_shift(explode(',', $_SERVER['HTTP_X_FORWARDED_FOR']));

$referer = "";
if (array_key_exists('HTTP_REFERER', $_SERVER)) {
    $referer = array_shift(explode(',', $_SERVER['HTTP_REFERER']));

$language = "";
if (array_key_exists('HTTP_ACCEPT_LANGUAGE', $_SERVER)) {
    $language = array_shift(explode(',', $_SERVER['HTTP_ACCEPT_LANGUAGE']));
$data = [
    "user_ip" => $ip,
    "user_agent" => $_SERVER['HTTP_USER_AGENT'],
    "language" => $language,
    "referer" => $referer,
    "zones" => [
        ["idzone" => "1813348"],
        ["idzone" => "1813348"],
        ["idzone" => "1813348"]

$request = json_encode($data);

$ch = curl_init('http://localhost:8080/serve');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");                                                                     
curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);                                                                      
curl_setopt($ch, CURLOPT_HTTPHEADER, array(                                                                          
    'Content-Type: application/json',                                                                                
    'Content-Length: ' . strlen($request))                                                                       

$result = json_decode(curl_exec($ch), true);

Optional Configuration

There are a number of optional configs in neverblock-conf.toml. These

  • debug - Enable debug mode
  • port - Service listening port
  • log - Application log
  • http_timeout - HTTP Request Timeout (secs)
  • cache_ttl - Time to live (mins) for the cached files
  • cache_purge_frequency - Cache purge run interval (mins)
  • syndication - Exoclick Syndication URL. See Domain Base for details on when to change this


Flags are available to override the configuration file

heisenberg:neverblock-proxy craig$ ./neverblock-proxy -h
Neverblock-Proxy - the AdBlock trafficker

  neverblock-proxy [flags]

  -c, --cache-path string    Image Cache path
  -C, --config-file string   Config file
  -l, --log string           Log file
  -p, --port string          Service port