vcl_miss
The built-in vcl_miss
subroutine is executed when a requested object is not found in the cache by the lookup operation.
The subroutines vcl_pass
and vcl_miss
are very similar in nature. They both run immediately prior to a backend fetch, usually on a fetch node. In preparation for making a request to the backend, a copy of the client request is created, and is available as bereq
. This backend request object is writable, and any changes made to it do not affect the state of the client request, nor the cache address in which the response may be stored. This is therefore a good opportunity to remove any headers that you do not wish to send to the backend or to add authentication data required by the backend.
Key use cases:
- Preparing request headers for a specific origin/backend.
- Adding authentication requirements when the origin is a private bucket at AWS S3, GCS or similar.
- Unsetting request headers that are being used internally in VCL and are not required at origin.
The vcl_miss
subroutine should return(fetch)
to start the backend fetch. It is also possible to return(pass)
, which will transfer control to the vcl_pass
subroutine and ultimately still make a backend fetch, but the resulting response will not qualify for caching. error
may be used in vcl_miss
, but it is not possible to restart
the request from here.
Typically vcl_miss
is executed on a fetch node as a result of clustering.
Using a 'prefetch' custom subroutine
Since it is common for vcl_miss
and vcl_pass
to perform broadly the same tasks, it is often useful to create a custom subroutine and invoke it from both places:
sub miss_pass { # Common logic goes here}sub vcl_pass {#FASTLY pass call miss_pass;}sub vcl_miss {#FASTLY miss call miss_pass;}
State transitions
| vcl_miss |
To see this subroutine in the context of the full VCL flow, see using VCL.
Example
The code example AWS S3 bucket origin (private) is a good example of the vcl_miss
subroutine in use:
Tokens available in this subroutine
The following limited-scope VCL functions and variables are available for use in this subroutine (those in bold are available only in this subroutine, those available in *all* subroutines are not listed):
- bereq.between_bytes_timeout
- bereq.connect_timeout
- bereq.first_byte_timeout
- bereq.headers
- bereq.http.{NAME}
- bereq.method
- bereq.proto
- bereq.request
- bereq.url
- bereq.url.basename
- bereq.url.dirname
- bereq.url.ext
- bereq.url.path
- bereq.url.qs
- fastly.ff.visits_this_pop_this_service
- req.backend.is_origin
- req.digest.ratio
- waf.anomaly_score
- waf.blocked
- waf.counter
- waf.executed
- waf.failures
- waf.http_violation_score
- waf.inbound_anomaly_score
- waf.lfi_score
- waf.logdata
- waf.logged
- waf.message
- waf.passed
- waf.php_injection_score
- waf.rce_score
- waf.rfi_score
- waf.rule_id
- waf.session_fixation_score
- waf.severity
- waf.sql_injection_score
- waf.xss_score