Skip to content

Add support for custom VCL prepend/append file inclusion#119

Open
peterjaap with Copilot wants to merge 10 commits into
masterfrom
copilot/add-custom-vcl-inclusion
Open

Add support for custom VCL prepend/append file inclusion#119
peterjaap with Copilot wants to merge 10 commits into
masterfrom
copilot/add-custom-vcl-inclusion

Conversation

Copilot AI commented Dec 15, 2025 •
edited
Loading

Copy link
Copy Markdown
Contributor

Enables including custom VCL snippets at the start and end of generated VCL files via admin configuration, allowing VCL customization without modifying the base template.

Changes

  • Configuration: Added custom_vcl_prepend_file and custom_vcl_append_file admin fields under Varnish settings
  • VCL Generation: Extended VCLGenerator to read and inject file contents at template boundaries:
    • Prepend: After imports, before backend definition
    • Append: After all subroutines
  • Security: 1MB file size limit, blocks access to sensitive paths (/etc/passwd, /root, etc.) with symlink resolution and directory boundary checks
  • Template: Added {{var custom_vcl_prepend}} and {{var custom_vcl_append}} placeholders in varnish6.vcl

Usage

Configure absolute paths in admin panel:

Stores > Configuration > System > Full Page Cache > Varnish Configuration
├── Custom VCL Prepend File: /path/to/prepend.vcl
└── Custom VCL Append File: /path/to/append.vcl

Example prepend file for custom backend:

backend custom_api {
    .host = "api.example.com";
    .port = "8080";
}

Example append file for helper subroutines:

sub custom_security_check {
    if (req.http.X-Custom-Header) {
        # Custom logic here
    }
}

Empty or invalid paths are silently ignored. VCL hook subroutines defined in append files override earlier definitions per Varnish behavior.

Original prompt

This section details on the original issue you should resolve

<issue_title>Add support to include custom VCL at the start & end of the VCL</issue_title>
<issue_description>We now have app/etc/varnish6.vcl in our Git repo, in which we update our VCL configuration.

It would be nice to keep this repo with the main VCL in here, and do modifications to the VCL through inclusion.

We would need to add a before and an after inclusion to cover all cases.

How VCL Subroutine Prepend/Append Works

  • Only one definition per VCL hook subroutine (e.g., vcl_deliver) is active in the final compiled VCL. Later definitions override earlier ones.
  • Use return to prevent fallthrough to builtin VCL logic.
  • Use prepend/append files to structure reusable logic (e.g., define shared sub blocks), but call them explicitly in the active vcl_* subroutine.
  • If composing VCLs via includes, make sure only one file defines a given vcl_* unless you understand the override order.
  • Use varnishd -C -f composed.vcl to inspect what actually gets compiled.

Examples;

# prepend.vcl
# This file is *prepended* to the main VCL during composition.
# Define or partially override VCL subroutines here.
# These definitions will be overridden if the same subroutine is defined later in the main VCL.

sub vcl_deliver {
    # This runs *before* any later vcl_deliver definitions (if they don't override this).
    set resp.http.X-Prepended = "set in prepend.vcl";

    # Important: Without return(), control will fall through to the next vcl_deliver definition
    # (e.g., in main.vcl or builtin.vcl).
    # To stop further execution, add an explicit return:
    # return (deliver);
}

# main.vcl
# The core VCL logic, included after prepend.vcl.
# Subroutine definitions here will OVERRIDE any previous ones with the same name.

include "prepend.vcl";

sub vcl_deliver {
    set resp.http.X-Main = "set in main.vcl";

    # This will replace the previous vcl_deliver unless it was only partial logic (e.g., in a called sub).
    return (deliver);
}

# append.vcl
# This file is *appended* to the main VCL.
# Useful for shared subroutines or logic you want to call from within the main subroutines.
# Avoid declaring VCL hook subroutines (like vcl_recv, vcl_deliver) here unless you are *not* redefining them elsewhere.

sub my_append_logic {
    set resp.http.X-Appended = "logic in append.vcl";
}
```</issue_description>

## Comments on the Issue (you are @copilot in this section)

<comments>
<comment_new><author>@toonvd</author><body>
`prepend.vcl` - Avoid returns at all costs unless you want to override all core logic!
Subroutines that do not have returns in default vcl can also be overridden in `append.vcl`.</body></comment_new>
<comment_new><author>@peterjaap</author><body>
Yes I know. Of course, hic sunt dracones, but we definitely need this in some cases.</body></comment_new>
</comments>

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Copilot AI and others added 3 commits December 15, 2025 09:51
@peterjaap
Add custom VCL prepend/append file configuration and implementation
f872de1 
Co-authored-by: peterjaap <431360+peterjaap@users.noreply.github.com>
@peterjaap
Add test for custom VCL prepend/append functionality
f796523 
Co-authored-by: peterjaap <431360+peterjaap@users.noreply.github.com>
@peterjaap
Add documentation for custom VCL prepend/append feature
20dbc19 
Co-authored-by: peterjaap <431360+peterjaap@users.noreply.github.com>
@peterjaap peterjaap marked this pull request as ready for review December 15, 2025 09:56
Copilot AI and others added 6 commits December 15, 2025 09:59
@peterjaap
Add security checks for custom VCL file reading
3776280 
Co-authored-by: peterjaap <431360+peterjaap@users.noreply.github.com>
@peterjaap
Improve security path blocking to handle symlinks and remove redundan…
54eaabf 
…t checks

Co-authored-by: peterjaap <431360+peterjaap@users.noreply.github.com>
@peterjaap
Optimize security checks with caching and fix trailing slash issues
e841f08 
Co-authored-by: peterjaap <431360+peterjaap@users.noreply.github.com>
@peterjaap
Final security improvements: move blocked paths to constant and impro…
698ad20 
…ve boundary checks

Co-authored-by: peterjaap <431360+peterjaap@users.noreply.github.com>
@peterjaap
Improve code quality: extract helper method and use constant for file…
4908820 
… size limit

Co-authored-by: peterjaap <431360+peterjaap@users.noreply.github.com>
@peterjaap
Remove trailing whitespace for code formatting consistency
2791fe1 
Co-authored-by: peterjaap <431360+peterjaap@users.noreply.github.com>
Copilot AI changed the title [WIP] Add support to include custom VCL at start and end Add support for custom VCL prepend/append file inclusion Dec 15, 2025
Copilot AI requested a review from peterjaap December 15, 2025 10:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@peterjaap peterjaap Awaiting requested review from peterjaap

At least 1 approving review is required to merge this pull request.

Assignees

@peterjaap peterjaap

Copilot code review Copilot

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Add support to include custom VCL at the start & end of the VCL

2 participants

@peterjaap