Varnish Enterprise

https://docs.varnish-software.com/varnish-enterprise
Admin
Varnish Enterprise is a paid, enhanced version of Varnish Cache developed by Varnish Software,...
Tokens:235,201
Snippets:1,454
Trust Score:10
Update:1 year ago
Show doc for...
Tokens:
Raw
### Automated Varnish Enterprise Installation

Source: https://docs.varnish-software.com/varnish-enterprise/installation

This script automates the installation of Varnish Enterprise by fetching and executing a setup script. It can be configured with a repository token and specific packages for installation.

```bash
# this will ask you for you repository token,
# then install the default set of Enterprise packages
curl https://docs.varnish-software.com/scripts/setup.sh | bash

```

```bash
curl https://docs.varnish-software.com/scripts/setup.sh | TOKEN=$TOKEN bash

```

```bash
curl https://docs.varnish-software.com/scripts/setup.sh | TOKEN=$TOKEN INSTALL="varnish-plus varnish-broadcaster-1.2.0-1.el7" bash

```

--------------------------------

### Enable and Verify Varnish Service Status

Source: https://docs.varnish-software.com/varnish-enterprise/installation

This command enables the Varnish service to start on boot and immediately starts it. It then displays the status of the Varnish service, indicating if it is active and running, along with process details and recent log entries. This is crucial for confirming the service is operational after installation.

```bash
[root@Your-Machine ~]# systemctl enable --now varnish && systemctl status varnish
 ● varnish.service - Varnish Cache Plus, a high-performance HTTP accelerator
   Loaded: loaded (/usr/lib/systemd/system/varnish.service; disabled; vendor preset: disabled)
        Active: active (running) since Wed 2023-08-09 23:26:28 UTC; 13min ago
        Process: 16004 ExecStart=/usr/sbin/varnishd -a :6081 -a
localhost:8443,proxy -T localhost:6082 -S /etc/varnish/secret -p feature=+http2 -r vcc_allow_inline_c -r allow_exec >
        Main PID: 16005 (varnishd)
         Tasks: 223
        Memory: 156.4M
        CGroup: /system.slice/varnish.service
            ├─16005 /usr/sbin/varnishd -a :6081 -a localhost:8443,proxy -T localhost:6082 -S /etc/varnish/secret -p feature=+http2 -r vcc_allow_inline_c -r allow_exec -f /etc/>
            └─16015 /usr/sbin/varnishd -a :6081 -a localhost:8443,proxy -T localhost:6082 -S /etc/varnish/secret -p feature=+http2 -r vcc_allow_inline_c -r allow_exec -f /etc/>

        Aug 09 23:26:28 AMSI-Machine varnishd[16005]: Debug: Version: varnish-plus-6.0.11r4 revision 676b15e5f7393eb5d5700df47ea504055db032d4
        Aug 09 23:26:28 AMSI-Machine varnishd[16005]: Debug: Platform: Linux,4.18.0-477.10.1.el8_8.x86_64,x86_64,-junix,-smse,-hcritbit
        Aug 09 23:26:28 AMSI-Machine varnishd[16005]: Version: varnish-plus-6.0.11r4 revision 676b15e5f7393eb5d5700df47ea504055db032d4
        Aug 09 23:26:28 AMSI-Machine varnishd[16005]: Platform: Linux,4.18.0-477.10.1.el8_8.x86_64,x86_64,-junix,-smse,-hcritbit
        Aug 09 23:26:28 AMSI-Machine varnishd[16005]: Debug: Child (16015) Started
        Aug 09 23:26:28 AMSI-Machine varnishd[16005]: Child (16015) Started
        Aug 09 23:26:28 AMSI-Machine varnishd[16005]: Child launched OK
        Aug 09 23:26:28 AMSI-Machine varnishd[16005]: Child (16015) said
Child starts
        Aug 09 23:26:28 AMSI-Machine systemd[1]: Started Varnish Cache Plus,
a high-performance HTTP accelerator.
        Aug 09 23:26:28 AMSI-Machine; varnishd[16005]: Child (16015) said
Environment mse fully populated in 0.00 seconds. (0.00 0.00 0.00 0 0 0/1 0 0 0 0)

```

--------------------------------

### Display Operating System Release Information

Source: https://docs.varnish-software.com/varnish-enterprise/installation

This command displays the contents of the '/etc/os-release' file, which provides detailed information about the operating system, including its name, version, and other identifiers. This is useful for understanding the environment in which Varnish is running.

```bash
[root@Your-Machine ~]# cat /etc/os-release

```

--------------------------------

### Inhomogeneous MSE Setup with Default Store Selection

Source: https://docs.varnish-software.com/varnish-enterprise/features/mse

This example illustrates an inhomogeneous MSE setup where stores within books have different sizes. It also demonstrates how to specify a default set of stores using the `default_stores` parameter, which influences object insertion. This is useful for optimizing storage based on drive types and access patterns.

```configuration
env: {
	id = "myenv";
	memcache_size = "auto";

	books = ( { 
		id = "book1";
		directory = "/var/lib/mse/book1";
		database_size = "1G";

		stores = ( { 
			id = "store-1-1";
			filename = "/var/lib/mse/stores/disk1/store-1-1.dat";
			size = "1T";
		}, { 
			id = "store-1-2";
			filename = "/var/lib/mse/stores/disk2/store-1-2.dat";
			size = "1T";
		} );
	}, { 
		id = "book2";
		directory = "/var/lib/mse/book2";
		database_size = "1G";

		stores = ( { 
			id = "store-2-1";
			filename = "/var/lib/mse/stores/disk3/store-2-1.dat";
			size = "10T";
		}, { 
			id = "store-2-2";
			filename = "/var/lib/mse/stores/disk4/store-2-2.dat";
			size = "10T";
		} );
	} );
	default_stores = "book1";
};

```

--------------------------------

### Install Akamai Connector on Ubuntu

Source: https://docs.varnish-software.com/varnish-enterprise/vmods/akamai

Installs the Akamai Connector for Varnish Enterprise on Ubuntu systems using apt-get. This command requires prior setup of the connector repository.

```bash
apt-get install varnish-plus-akamai-connector
```

--------------------------------

### Install Varnish Enterprise (RHEL)

Source: https://docs.varnish-software.com/varnish-enterprise/installation

Installs the Varnish Enterprise package along with its necessary dependencies on RHEL-based systems using yum. Ensure the repositories are correctly configured prior to running this command.

```bash
yum install -y varnish-plus

```

--------------------------------

### Install Varnish Enterprise (Debian/Ubuntu)

Source: https://docs.varnish-software.com/varnish-enterprise/installation

Updates the apt package list and installs the 'varnish-plus' package on Debian/Ubuntu systems. This command should be run after configuring the Varnish Enterprise apt repository.

```bash
apt-get update
apt-get install -y varnish-plus

```

--------------------------------

### Starting Varnish with Hitch Configuration

Source: https://docs.varnish-software.com/varnish-enterprise/features/core-ssl

This command demonstrates how to start the Varnish daemon using an existing Hitch configuration file with the `-A` argument. It specifies the configuration file path and the listening address and storage.

```bash
varnishd -A /etc/hitch/hitch.conf -a :80 -s mse
```

--------------------------------

### Install Varnish Modules (VMODs) on EL9+

Source: https://docs.varnish-software.com/varnish-enterprise/installation

This set of commands outlines the process for installing Varnish modules that have third-party dependencies, specifically on EL9-based systems. It includes enabling the CodeReady Builder (CRB) repository, which is often required for these dependencies, and then installing the `varnish-plus-vmods-extra` package. It also provides guidance for RHEL 9 where the CRB repository name might vary.

```bash
# Only needed if dnf config-manager is not installed
sudo dnf install -y 'dnf-command(config-manager)'

sudo dnf config-manager --set-enabled crb
sudo dnf install varnish-plus-vmods-extra

sudo dnf config-manager --set-enabled '*codeready-builder-for-rhel*'
```

--------------------------------

### Install epel-release Repository (RHEL)

Source: https://docs.varnish-software.com/varnish-enterprise/installation

Installs the 'epel-release' package, which provides 'Extra Packages for Enterprise Linux'. This repository is often required for Varnish Enterprise dependencies on RHEL-based systems, but not for Amazon Linux 2023.

```bash
yum install -y epel-release

```

--------------------------------

### Configure Yum Repository for Varnish Enterprise (RHEL)

Source: https://docs.varnish-software.com/varnish-enterprise/installation

Sets up the yum repository configuration for Varnish Enterprise on RHEL-based systems. This involves creating or editing a .repo file with the correct baseurl and GPG key information. Remember to replace TOKEN with your Packagecloud token.

```ini
[varnish-enterprise-60]
name=varnish-enterprise-60
baseurl=https://TOKEN:@packagecloud.io/varnishplus/60/el/$releasever/$basearch
repo_gpgcheck=1
gpgcheck=0
enabled=1
gpgkey=https://TOKEN:@packagecloud.io/varnishplus/60/gpgkey
sslverify=1
sslcacert=/etc/pki/tls/certs/ca-bundle.crt
metadata_expire=300

```

```ini
[varnish-enterprise-60]
name=varnish-enterprise-60
baseurl=https://TOKEN:@packagecloud.io/varnishplus/60/amazon/2023/$basearch
repo_gpgcheck=1
gpgcheck=0
enabled=1
gpgkey=https://TOKEN:@packagecloud.io/varnishplus/60/gpgkey
sslverify=1
sslcacert=/etc/pki/tls/certs/ca-bundle.crt
metadata_expire=300

```

--------------------------------

### Install APT HTTPS Support and GPG Key (Debian/Ubuntu)

Source: https://docs.varnish-software.com/varnish-enterprise/installation

Installs the 'apt-transport-https' package to enable HTTPS support for the package manager and adds the Varnish Enterprise public GPG key. This is necessary for fetching packages securely from the Varnish Enterprise repositories on Debian/Ubuntu systems. Replace TOKEN with your Packagecloud token.

```bash
apt-get install -y apt-transport-https
curl -L https://TOKEN:@packagecloud.io/varnishplus/60/gpgkey | apt-key add -

```

--------------------------------

### urlplus VMOD Examples

Source: https://docs.varnish-software.com/varnish-enterprise/vmods/urlplus

Practical examples demonstrating the usage of the `urlplus` VMOD for common tasks like query filtering, parameter removal, sorting, and file extension specific logic.

```APIDOC
## urlplus VMOD Examples

### Query Filtering (Keep only `page_id`)

```vcl
vcl 4.0;

import urlplus;

sub vcl_recv
{
  //Keep page_id
  urlplus.query_keep("page_id");

  //Sort query string and write URL out to req.url
  //Any query that is not kept is not written to req.url
  urlplus.write();
}
```

### Remove Google Analytics

```vcl
vcl 4.0;

import urlplus;

sub vcl_recv
{
  //Remove all Google Analytics
  urlplus.query_delete_regex("utm_");

  //Sort query string and write URL out to req.url
  urlplus.write();
}
```

### Remove `random` query parameter

```vcl
vcl 4.0;

import urlplus;

sub vcl_recv
{
  urlplus.query_delete("random");

  // Write URL out to req.url without sorting
  urlplus.write(sort_query = false);
}
```

### Normalize, sort and write query string to `req.url`

```vcl
vcl 4.0;

import urlplus;

sub vcl_recv
{
  // Write URL out to req.url
  urlplus.write();
}
```

### File Extension Specific Logic (Specify TTL by file type)

```vcl
vcl 4.0;

import urlplus;

sub vcl_backend_response
{
  //Give files with these extensions a TTL of 1 day
  if (urlplus.get_extension() ~ "gif|jpg|jpeg|bmp|png|tiff|tif|img") {
      set beresp.ttl = 1d;
  }
}
```
```

--------------------------------

### Configure Multiple Books with Multiple Stores in Varnish MSE

Source: https://docs.varnish-software.com/varnish-enterprise/features/mse

This example demonstrates configuring two books, each containing two stores, with specified metadata and object data sizes. It's a basic setup for distributing data across multiple storage volumes within the MSE.

```configuration
env: {
	id = "myenv";
	memcache_size = "auto";

	books = ( { 
		id = "book1";
		directory = "/var/lib/mse/book1";
		database_size = "1G";

		stores = ( { 
			id = "store-1-1";
			filename = "/var/lib/mse/stores/disk1/store-1-1.dat";
			size = "1T";
		}, { 
			id = "store-1-2";
			filename = "/var/lib/mse/stores/disk2/store-1-2.dat";
			size = "1T";
		} );
	}, { 
		id = "book2";
		directory = "/var/lib/mse/book2";
		database_size = "1G";

		stores = ( { 
			id = "store-2-1";
			filename = "/var/lib/mse/stores/disk3/store-2-1.dat";
			size = "1T";
		}, { 
			id = "store-2-2";
			filename = "/var/lib/mse/stores/disk4/store-2-2.dat";
			size = "1T";
		} );
	} );
};

```

--------------------------------

### Configure APT Repository for Varnish Enterprise (Debian/Ubuntu)

Source: https://docs.varnish-software.com/varnish-enterprise/installation

Configures the apt package manager to use the Varnish Enterprise repositories. This involves adding a line to a sources.list file, specifying the distribution and release codename. Replace DIST with 'ubuntu' or 'debian' and RELEASE with your specific OS release codename (e.g., 'jammy', 'bookworm').

```bash
# be sure to replace "DIST" with "ubuntu" or "debian", and "RELEASE" with
# "jammy", "noble" or "bookworm" depending on your exact platform

# Varnish Enterprise 6.0 and VMODs
deb https://TOKEN:@packagecloud.io/varnishplus/60/DIST/ RELEASE main

```

--------------------------------

### VCL: Advanced goto to udo Migration with Probes

Source: https://docs.varnish-software.com/varnish-enterprise/vmods/udo

Illustrates an advanced migration from 'goto' to 'udo' in VCL, incorporating health probes and connection timeouts. The 'goto' example defines a probe separately and passes it to 'goto.dns_director'. The 'udo' example defines a probe template and a backend template, then applies them to the 'activedns.dns_group' which is then subscribed to the 'udo.director'.

```vcl
vcl 4.1;

import goto;

probe example_probe {
  .url = "/healthcheck";
  .interval = 5s;
  .initial = 3;
  .timeout = 1s;
  .window = 5;
  .threshold = 3;
}

sub vcl_init {
  new example_http = goto.dns_director(
    "http://subdomain.example.com:1234", 
    ip_version = ipv4, 
    probe = example_probe, 
    connect_timeout = 5s, 
    first_byte_timeout = 10s
  );
}

sub vcl_backend_fetch {
  set bereq.backend = example_http.backend();
}
```

```vcl
vcl 4.1;

import udo;
import activedns;

# Define the health probe for the backends
probe example_probe {
  .url = "/healthcheck";
  .interval = 5s;
  .initial = 3;
  .timeout = 1s;
  .window = 5;
  .threshold = 3;
}

# Define a generic backend template for DNS resolutions
backend example_http_template {
  .host = "0.0.0.0"; 
  .connect_timeout = 5s;
  .first_byte_timeout = 10s;
}

sub vcl_init {
  # Create a DNS group called origin_group_example with ActiveDNS, 
  # using a template and IPv4 rule from the goto example
  new origin_group_example = activedns.dns_group("http://subdomain.example.com:1234");
  origin_group_example.set_ipv_rule(ipv4);
  origin_group_example.set_backend_template(example_http_template);
  origin_group_example.set_probe_template(example_probe);
  # Create an udo director for dynamic backend routing, where each backend 
  # created by example_http gets a probe.
  new example_http = udo.director();
  example_http.subscribe(origin_group_example.get_tag());
}
sub vcl_backend_fetch {
  # Assign the backend dynamically from UDO's director
  set bereq.backend = example_http.backend();
}

**Note: The** .host **attribute under the backend template must be set to make the VCL compiler happy, but this field is ignored by the DNS group, hence the “0.0.0.0” value.**
```

--------------------------------

### KVStore Memory Calculation Example

Source: https://docs.varnish-software.com/varnish-enterprise/vmods/kvstore-4

Illustrates the memory usage calculation for a KVStore based on the number of buckets, keys, and their sizes. This example provides a concrete breakdown for a million keys with specific average sizes, helping to estimate resource requirements.

```plaintext
100000 buckets * 100 bytes = 10MB
1000000 keys * 100 bytes = 100MB
1000000 keys * 1KB size = 1GB

TOTAL = 1.11GB

```

--------------------------------

### Install Akamai Connector on RHEL

Source: https://docs.varnish-software.com/varnish-enterprise/vmods/akamai

Installs the Akamai Connector for Varnish Enterprise on Red Hat Enterprise Linux systems using yum. This command requires prior setup of the connector repository.

```bash
yum install varnish-plus-akamai-connector
```

--------------------------------

### Varnish Configuration Example

Source: https://docs.varnish-software.com/varnish-enterprise/vmods/geolocation

An example VCL snippet demonstrating how to import and use the mmdb VMOD to restrict access based on country.

```APIDOC
## Varnish Configuration Example

### Description
This VCL configuration demonstrates how to import the `mmdb` VMOD, initialize a database object, and use it to retrieve and check the country of a client's IP address.

### Method
N/A (VCL Configuration)

### Endpoint
N/A (VCL Configuration)

### Parameters
N/A

### Request Example
```vcl
vcl 4.0;

import mmdb;

backend default {
    .host = "192.0.2.11";
    .port = "8080";
}

# create a database object
sub vcl_init {
    new geodb = mmdb.init("/path/to/db");
}

sub vcl_recv {
    # retrieve the name of the request's origin
    set req.http.Country-Name = geodb.country_name(client.ip);

    # if the country doesn't come from Germany or Belgium, deny access
    if (req.http.Country-Name != "Germany" ||
        req.http.Country-Name != "Belgium") {
        return (synth(403, "Sorry, only available in Germany and Belgium"));
    }

    # for logging purposes, log the geoname_id field of the country
    set req.http.geoname_id = geodb.lookup(client.ip, "country/geoname_id");
}
```

### Response
N/A (VCL Configuration)
```

--------------------------------

### VCL: Basic goto to udo Migration

Source: https://docs.varnish-software.com/varnish-enterprise/vmods/udo

Demonstrates migrating a basic VCL configuration from the 'goto' module to the 'udo' module for dynamic backend management. The 'goto' example uses 'goto.dns_director', while the 'udo' example utilizes 'activedns.dns_group' and 'udo.director' for similar functionality.

```vcl
vcl 4.1;

import goto;

backend default none;

sub vcl_init {
  new example_http = goto.dns_director("http://subdomain.example.com:1234");
}
```

```vcl
vcl 4.1;

import udo;
import activedns;

# No static VCL backends are needed here,
# but we declare a "none" backend to satisfy the VCL compiler
backend default none;

sub vcl_init {
  # Create a DNS group called origin_group_example with ActiveDNS, then
  # create an udo director and subscribe it to DNS updates from origin_group_example
  new origin_group_example = activedns.dns_group("http://subdomain.example.com:1234");
  new example_http = udo.director();
  example_http.subscribe(origin_group_example.get_tag());
}
```

--------------------------------

### Test Varnish HTTP Connectivity with cURL

Source: https://docs.varnish-software.com/varnish-enterprise/installation

This command uses cURL to send a HEAD request to the Varnish service running on localhost:6081. The output, particularly the 'X-Varnish' and 'Via' headers, confirms that Varnish is receiving and responding to HTTP traffic. A '503 Backend fetch failed' status is expected if no backend is configured yet, but the presence of Varnish headers is the key indicator.

```bash
[root@Your-Machine ~]# curl -I localhost:6081

HTTP/1.1 503 Backend fetch failed
Date: Wed, 09 Aug 2023 23:29:22 GMT
Server: Varnish
Content-Type: text/html; charset=utf-8
Retry-After: 5
X-Varnish: 2
Age: 0
Via: 1.1 varnish (Varnish/6.0)
Content-Length: 278
Connection: keep-alive

```

--------------------------------

### MSE4 Environment Configuration Example

Source: https://docs.varnish-software.com/varnish-enterprise/features/mse_4/configuration

Provides an example of environment configuration in MSE4. It illustrates setting a global default subdivision value for all categories.

```mse4-config
env: {
	# Set a default subdivision of 2 for all categories
	default_subdivisions = 2;
};

```

--------------------------------

### VCL Example: Tenant-Specific Statistics with Namespaces

Source: https://docs.varnish-software.com/varnish-enterprise/vmods/accounting

This VCL example demonstrates how to use namespaces to separate statistics for different tenants. It initializes namespaces in `vcl_init`, sets the appropriate namespace in `vcl_recv` based on the host, and adds keys in `vcl_backend_response`.

```vcl
import accounting;

sub vcl_init {
  accounting.create_namespace("tenant1");
  accounting.create_namespace("tenant2");
  accounting.create_namespace("generic");
}

sub vcl_recv {
  if (req.http.host ~ "tenant1.com$") {
    accounting.set_namespace("tenant1");
    return(vcl(tenant1));
  } else if (req.http.host ~ "tenant2.com$") {
    accounting.set_namespace("tenant2");
    return(vcl(tenant2));
  } else {
    accounting.set_namespace("generic");
  }
}

```

```vcl
import accounting;

sub vcl_backend_response {
  if (beresp.http.Content-Type ~ "^image") {
    accounting.add_keys("images");
  } else {
    accounting.add_keys("generic");
  }
}

```

--------------------------------

### Install DeviceAtlas VMOD on Ubuntu/Debian

Source: https://docs.varnish-software.com/varnish-enterprise/vmods/deviceatlas3

Installs the DeviceAtlas Varnish Enterprise VMOD on Ubuntu and Debian systems using apt-get. This command assumes the DeviceAtlas repository has been enabled.

```bash
sudo apt-get install varnish-plus-deviceatlas3

```

--------------------------------

### Install DeviceAtlas VMOD on Ubuntu/Debian

Source: https://docs.varnish-software.com/varnish-enterprise/vmods/deviceatlas

Installs the DeviceAtlas Varnish Module on Ubuntu and Debian systems. This command assumes the DeviceAtlas repository has already been enabled.

```bash
sudo apt-get install varnish-plus-deviceatlas
```

--------------------------------

### KV Store Example: Keys without Key Group (VCL)

Source: https://docs.varnish-software.com/varnish-enterprise/vmods/kv

Demonstrates setting a key-value pair in the Varnish Enterprise KV store without specifying a key group. The key is directly mapped to a Redis key, and its TTL is applied individually. This example shows basic initialization and setting a string value with a TTL.

```vcl
vcl 4.1;

import kv;

sub vcl_init {
    new store = kv.init();
    store.add_redis_server("1.2.3.4:6379");
}

sub vcl_recv {
    store.set("mykey", "mystr", ttl = 100);
}
```

--------------------------------

### Check Varnish Version

Source: https://docs.varnish-software.com/varnish-enterprise/installation

Checks the installed Varnish Enterprise version using the '-V' flag with the 'varnishd' command. This is useful for support requests and confirming the correct version has been installed.

```bash
varnishd -V

```

--------------------------------

### Initialize kvstore from a configuration file

Source: https://docs.varnish-software.com/varnish-enterprise/vmods/kvstore

Initializes a kvstore from a configuration file that follows an INI format. Keys and values are separated by an equal sign, and section names are used as prefixes for keys. Comments start with '#'. Modifications are not synced back to the file. Returns an integer.

```vcl
INT .init_conf(STRING path, INT buckets = 0)
```

--------------------------------

### VCL: Dynamic Backend Pool using goto.dns_director

Source: https://docs.varnish-software.com/varnish-enterprise/vmods/goto

This VCL snippet demonstrates how to initialize a dynamic backend pool using the `goto.dns_director` function in `vcl_init`. It creates a pool of backends by resolving DNS records for 'api.example.com' and then uses this pool in `vcl_recv` to set the backend hint for incoming requests. A static 'default' backend is required, even if null.

```vcl
import goto;

# varnish needs at least one static backend, even if it's null
backend default none;

sub vcl_init {
	new apipool = goto.dns_director("api.example.com");
}

sub vcl_recv {
	set req.backend_hint = apipool.backend();
}

```

--------------------------------

### Varnish Stat VMOD Prometheus Metrics Output Example

Source: https://docs.varnish-software.com/varnish-enterprise/vmods/stat

This example shows the typical output format for Prometheus metrics exposed by the Varnish `stat` VMOD when accessed via `curl`. It includes help text, type information, and metric values for uptime and bytes.

```shell
$ curl http://localhost:6081/metrics -v
# HELP varnish_uptime Child process uptime
# TYPE varnish_uptime counter
varnish_uptime{host="varnish1",section="MAIN"} 0

# HELP varnish_s0_g_bytes Bytes outstanding
# TYPE varnish_s0_g_bytes gauge
varnish_s0_g_bytes{host="varnish1",section="SMA"} 2941248

# HELP varnish_Transient_g_bytes Bytes outstanding
# TYPE varnish_Transient_g_bytes gauge
varnish_Transient_g_bytes{host="varnish1",section="SMA"} 2244

```

--------------------------------

### NUMA Statistics Output Example

Source: https://docs.varnish-software.com/varnish-enterprise/features/numa

This example demonstrates the typical output of the `numastat(8)` command, which is used to evaluate a system's page allocation performance on NUMA architectures. It provides counters for memory hits, misses, and interleaving, helping to diagnose NUMA-related performance issues.

```text
                             node0         node1
numa_hit                  76557759      92126519
numa_miss                 30772308      30827638
numa_foreign              30827638      30772308
interleave_hit              106507        103832
local_node                76502227      92086995
other_node                30827840      30867162

```

--------------------------------

### Disable Varnish DNF Module (RHEL 8)

Source: https://docs.varnish-software.com/varnish-enterprise/installation

Disables the Varnish DNF module on RHEL 8 based distributions to prevent conflicts during installation. This is a prerequisite for a clean Varnish Enterprise installation on these systems.

```bash
dnf -y module disable varnish

```

--------------------------------

### KVStore Initialization API

Source: https://docs.varnish-software.com/varnish-enterprise/vmods/kvstore

Provides methods for initializing and re-initializing the KVStore, with options for setting bucket counts, scope, and loading data from files or configuration.

```APIDOC
## KVStore Initialization

### Description
Initializes a `kvstore`. Can be used to re-initialize an active `kvstore`. The resulting `kvstore` is empty. This can be used as both a constructor and a method.

### Method
`OBJECT init(INT buckets = 250, ENUM {STATIC, GLOBAL, REQUEST} scope = GLOBAL)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "buckets": 250,
  "scope": "GLOBAL"
}
```

### Response
#### Success Response (200)
- **Object** (Object) - The initialized kvstore object.

#### Response Example
```json
{
  "message": "KVStore initialized successfully"
}
```

## .init Method

### Description
Initializes a `kvstore`. If `buckets` is non-zero, the number of buckets is changed. If `scrub` is `true`, memory for the stored data prior to the call is wiped.

### Method
`VOID .init(INT buckets = 0, BOOL scrub = 0)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "buckets": 0,
  "scrub": false
}
```

### Response
#### Success Response (200)
- **None** - This method does not return a value.

#### Response Example
```json
{}
```

## .init_file Method

### Description
Equivalent to `init()`, but initializes from a file. Can be used to rebuild an active `kvstore`. Modifications to the `kvstore` are not synced back to the file. The delimiter is the string used to separate the key and the value. Only the first occurrence of the delimiter is used as the key value separator.

### Method
`INT .init_file(STRING path, STRING delimiter, INT buckets = 0)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "path": "/path/to/your/file.txt",
  "delimiter": "=",
  "buckets": 0
}
```

### Response
#### Success Response (200)
- **Int** (Int) - Returns an integer indicating success or failure.

#### Response Example
```json
{
  "status": 0
}
```

## .init_conf Method

### Description
Equivalent to `init()`, but initializes from a configuration file. Can be used to rebuild an active `kvstore`. Modifications to the `kvstore` are not synced back to the file. A configuration file uses ini file format. Comments start with `#`, whitespace is stripped, keys and values are separated with an `=` (equal) sign, and section names are surrounded with `[ ]` and are prepended to key names with `_` as a separator.

### Method
`INT .init_conf(STRING path, INT buckets = 0)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "path": "/path/to/your/config.ini",
  "buckets": 0
}
```

### Response
#### Success Response (200)
- **Int** (Int) - Returns an integer indicating success or failure.

#### Response Example
```json
{
  "status": 0
}
```
```

--------------------------------

### Get Starting Delimiter (VCL)

Source: https://docs.varnish-software.com/varnish-enterprise/vmods/edgestash

Retrieves the starting delimiter used by Edgestash. An optional quote character can be provided. This function is restricted to the `backend` context.

```vcl
STRING get_sdelimiter(STRING quote_char = "")
```

--------------------------------

### VCL: HTTP Proxy with goto.dns_backend

Source: https://docs.varnish-software.com/varnish-enterprise/vmods/goto

This VCL example shows how to create an HTTP proxy by resolving the request's Host header to a backend using `goto.dns_backend`. This function is specifically designed for use within backend-side VCL subroutines like `vcl_backend_fetch`. It directly returns a backend to be used immediately, without needing to pre-define a director.

```vcl
import goto;
backend default none;
# goto.dns_backend() can only be used in vcl_backend_* routines
sub vcl_backend_fetch {
        set bereq.backend = goto.dns_backend(bereq.http.host);
}

```

--------------------------------

### KVSTORE Get Backend Method

Source: https://docs.varnish-software.com/varnish-enterprise/vmods/kvstore

Retrieves a backend associated with a key from the KVSTORE. Returns a default backend if the key is not found.

```APIDOC
## .get_backend

### Description
This method returns the backend associated with `key` in the `kvstore`. If it’s not found, `default` is returned.

### Method
BACKEND .get_backend(STRING key, BACKEND default = 0)

### Parameters
#### Arguments
- **key** (STRING) - Required - The key to look up.
- **default** (BACKEND) - Optional - The default backend to return if the key is not found. Defaults to 0.

### Returns
The backend associated with the key, or the default backend if not found.
```

--------------------------------

### Initialize MSE 3.0 Configuration File

Source: https://docs.varnish-software.com/varnish-enterprise/features/mse

This command initializes the MSE 3.0 configuration file, typically located at '/var/lib/mse/mse.conf'. This step is crucial for setting up the MSE bookstore, which includes the book (metadata) and store (cache content) directories and files. Ensure the ext4 filesystem is used for optimal performance.

```bash
mkfs.mse -c /var/lib/mse/mse.conf

```

--------------------------------

### File VMOD - Initialization and Configuration

Source: https://docs.varnish-software.com/varnish-enterprise/vmods/file

Details the initialization parameters and methods for the file VMOD, including setting root directories and MIME databases.

```APIDOC
## File VMOD Initialization and Configuration

### `init` Function:

```vmod
OBJECT init(STRING rootdir = 0, STRING mimedb = "/etc/mime.types", BOOL disable_symlinks = 0)
```

Initializes a file system root for the VMOD. This function creates an object that manages file operations.

#### Arguments:
- `rootdir` (STRING, optional): The base directory for the file system hierarchy. If not provided, paths are treated as absolute or relative based on a leading slash.
- `mimedb` (STRING, optional): Path to the MIME types database. Defaults to `/etc/mime.types`.
- `disable_symlinks` (BOOL, optional): If true, symbolic links are disabled. Defaults to `0` (false).

#### Returns:
An `OBJECT` representing the initialized file system root.

### `.backend` Method:

```vmod
BACKEND .backend()
```

Returns a backend reference that can be used in `vcl_backend_fetch` for serving files through Varnish's caching mechanisms.

#### Arguments:
None.

#### Returns:
A `BACKEND` reference.
```

--------------------------------

### Initialize and Set Variables in kvstore

Source: https://docs.varnish-software.com/varnish-enterprise/vmods/kvstore

This snippet demonstrates how to initialize a kvstore instance and set key-value pairs within the `vcl_init` subroutine. It then retrieves these values in the `vcl_recv` subroutine.

```vcl
vcl 4.0;

import kvstore;

sub vcl_init
{
  new kvs = kvstore.init();

  kvs.set("alpha", "one");
  kvs.set("beta", "two");
}

sub vcl_recv
{
  set req.http.alpha = kvs.get("alpha", "error");
  set req.http.beta = kvs.get("beta", "error");
}

```

--------------------------------

### Get Type of internal_observatory

Source: https://docs.varnish-software.com/varnish-enterprise/vmods/stat

Returns the type of the internal variable associated with the internal_observatory object ('counter' or 'gauge'), or NULL if the parameter was invalid during creation. The example demonstrates how to handle invalid names by failing VCL loading.

```vcl
STRING .get_type()
```

```vcl
vcl 4.1;
import stat;

sub vcl_init {
new threads_limited = stat.internal_observatory("MAIN.threads_limited");

if (!threads_limited.get_type()) {
	# We have no way of getting the counter through the
              # observatory object, so we just give up loading the VCL.
	return (fail);
}
}
```

--------------------------------

### Basic DeviceAtlas VMOD Initialization and Lookup

Source: https://docs.varnish-software.com/varnish-enterprise/vmods/deviceatlas3

A fundamental VCL example demonstrating how to load the DeviceAtlas database file in vcl_init and perform a basic lookup for device vendor information in vcl_deliver using the User-Agent header.

```vcl
import deviceatlas3;

sub vcl_init {
  if (deviceatlas3.loadfile("/full/path/to/file.json") != 0) {
    return (fail);
  }
}

sub vcl_deliver {
  set resp.http.Vendor = deviceatlas3.lookup(req.http.User-Agent, "vendor");
}

```

--------------------------------

### Reset Formatting State

Source: https://docs.varnish-software.com/varnish-enterprise/vmods/format

The `reset` function clears the current formatting state, effectively preparing for a new string construction. This is typically called after retrieving a formatted string with `get()` or when starting a new formatting sequence.

```vcl
VOID reset()
```

--------------------------------

### Enable NUMA Awareness in Varnish Enterprise

Source: https://docs.varnish-software.com/varnish-enterprise/features/numa

Enables NUMA awareness in Varnish Enterprise by setting the `reuseport` and `numa_aware` parameters. These must be set before starting Varnish and cannot be changed dynamically. It also includes an example of the `varnishd` command to apply these settings.

```shell
varnishd -a :80 -f /etc/varnish/default.vcl -p reuseport=on -p numa_aware=on

```

--------------------------------

### Get URL Basename

Source: https://docs.varnish-software.com/varnish-enterprise/vmods/urlplus

The `get_basename` function extracts the basename from a URL. For example, given `/foo/bar.baz`, it returns `bar.baz`. If no extension is present, it returns the last URL segment. This function is restricted to client and backend contexts and returns a `STRING`.

```vcl
STRING get_basename()
```

--------------------------------

### File VMOD - Serving Local Files

Source: https://docs.varnish-software.com/varnish-enterprise/vmods/file

Demonstrates how to initialize the file VMOD with a root directory and configure VCL to serve static files from the filesystem.

```APIDOC
## Introduction to File Serving

The `file` vmod allows Varnish to serve static files directly from the filesystem. It acts as a backend, enabling VCL to specify a root directory from which files are served. Cached files are handled like any other backend fetch, respecting TTL, grace, and keep settings.

### Key Features:
- Serves static files with VCL.
- Caches files similar to backend fetches.
- Adds `Last-Modified`, `Content-type`, and `Content-Length` headers based on file attributes.
- Provides error handling for unreadable files or access restrictions.
- Supports executable files with `varnishd` started with `-p allow_exec=true`.

### Example: Serving a local file system:

```vcl
import file;

sub vcl_init {
  # Initialize the file vmod with a root directory
  new root = file.init("/var/www/html/");
}

sub vcl_backend_fetch {
  # Set the file system as the backend for fetching
  set bereq.backend = root.backend();
}
```
```

--------------------------------

### Get Current Request Loop Iteration

Source: https://docs.varnish-software.com/varnish-enterprise/vmods/http

Retrieves the current loop iteration for a given request. The first request starts at 0, and subsequent loops increment from 1. This function is useful for tracking request processing stages. Accepts the request name as an integer argument.

```varnish-vcl
INT req_get_loops(INT name)
```

--------------------------------

### Initialization Functions

Source: https://docs.varnish-software.com/varnish-enterprise/vmods/headerplus

Functions for setting up and initializing the header management state.

```APIDOC
## init

### Description
Set up the internal state of headers. This is required to be called before any of the below functions can be used.

### Method
N/A (VMOD function)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
VOID init(HTTP scope)
```

### Response
#### Success Response (200)
None

#### Response Example
None

## init_req

### Description
A variant of `init` that targets the appropriate scope between `req` or `bereq` depending on where it is called. This can be useful for code reuse across contexts.

### Method
N/A (VMOD function)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
VOID init_req()
```

### Response
#### Success Response (200)
None

#### Response Example
None

## init_resp

### Description
The counterpart of `init_req` for respectively `resp` or `beresp`.

### Method
N/A (VMOD function)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
VOID init_resp()
```

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### nodes vmod VCL integration with cluster.vcl

Source: https://docs.varnish-software.com/varnish-enterprise/vmods/nodes

This VCL example illustrates using the 'nodes' vmod with a 'cluster.vcl' setup. It imports the 'nodes' vmod, includes 'cluster.vcl', and subscribes the cluster director to the 'nodes' configuration. It also shows setting cluster options.

```vcl
vcl 4.1;

import nodes;

include "cluster.vcl";

backend origin { .host = "ip:port"; }

sub vcl_init {
  new conf = nodes.config_group("/path/to/nodes.conf");
  cluster.subscribe(conf.get_tag());

  cluster_opts.set("token", "secret");
}

< the rest of your code goes here >


```

--------------------------------

### Initialize MSE Storage Files

Source: https://docs.varnish-software.com/varnish-enterprise/features/mse

The `mkfs.mse` utility is used to initialize the data files for MSE books and stores before the Varnish daemon starts for the first time. This ensures the on-disk format is correct.

```bash
mkfs.mse <path-to-config-file>
```

--------------------------------

### Mount Shared Memory Log as tmpfs

Source: https://docs.varnish-software.com/varnish-enterprise/installation

This command mounts a temporary file system (tmpfs) on the '/var/lib/varnish/' directory. Using tmpfs for the shared memory log can improve performance by avoiding disk I/O bottlenecks. The 'mode=1777' option sets appropriate permissions for the mount point.

```bash
[root@Your-Machine ~]# mount -t tmpfs -o mode=1777 vworkdir /var/lib/varnish/

```

--------------------------------

### Varnish Enterprise Content Categories and Persisted Caching Configuration

Source: https://docs.varnish-software.com/varnish-enterprise/features/mse_4/categories

Example configuration for Varnish Enterprise demonstrating the setup of Content Categories and persisted caching. It defines categories, associates stores with them, and provisions disk space for caching objects. This configuration is used within the VCL environment.

```json
env: {
	categories = {
		other = {
			*memory_weight* = 1;
			*stores* = ("other");
		};
		media = {
			*memory_weight* = 5;
			images = {
				*memory_weight* = 1;
				icons = {};
				pictures = {};
			};
			video = {
				*memory_weight* = 3;
				*stores* = ("video_disk1", "video_disk2");
			};
		};
	};
	default_category = "other";

	books = ( {
		id = "book_disk1";
		filename = "/var/lib/mse/disk1/book_disk1";
		size = "2g";

		stores = ( {
			id = "other";
			filename = "/var/lib/mse/disk1/store_other";
			size = "100g";
		}, {
			id = "video_disk1";
			filename = "/var/lib/mse/disk1/store_video";
			size = "400g";
		} );
	}, {
		id = "book_disk2";
		filename = "/var/lib/mse/disk2/book_disk2";
		size = "2g";

		stores = ( {
			id = "video_disk2";
			filename = "/var/lib/mse/disk2/store_video";
			size = "500g";
		} );
	} );
   };
};
```
Tokens:
Raw