20 |
21 | ## Configuring Blocking
22 |
23 | ## Blocking modes
24 |
25 | First thing to decide is how you want to block traffic. Two modes are available
26 |
27 | * **Blocklist**: blocks all access for users from selected countries/ACLs
28 | * **Allowlist**: block all access EXCEPT for users from selected countries/ACLs (Available in 1.2.70+)
29 |
30 | Blocklist is the default mode.
31 |
32 | ## Country/ACL selection
33 |
34 | You can select to block by list of countries and/or ACLs. Multiple selections are possible if you hold the Control key
35 | when selecting a list of countries. If you don't see any [ACL](https://github.com/fastly/fastly-magento2/blob/master/Documentation/Guides/ACL.md) listed in the selection box you will need to create one.
36 |
37 | ## Enable Blocking
38 |
39 | To enable Blocking click the **Enable/Disable** button and follow the directions.
40 |
41 | ## Changing blocking config
42 |
43 | After any change to the country list or ACL list you need to click the *Update Blocking Config* button to push the config change.
44 |
45 | If you decide to switch blocking modes you have to save the config before clicking Update Blocking Config.
46 |
47 | ## Turning off Blocking
48 |
49 | Once you are ready to go live you will want to turn off Blocking. This can be achieved by clicking the **Enable/Disable** button then clicking the **Upload button**.
50 |
--------------------------------------------------------------------------------
/Documentation/Guides/DICTIONARIES.md:
--------------------------------------------------------------------------------
1 | # Dictionaries
2 |
3 | This guide will show how to add Fastly Dictionaries to your site.
4 |
5 | To add dictionary, go to:
6 | ```
7 | Magento admin > Stores > Configuration > Advanced > System > Full Page Cache > Fastly Configuration
8 | ```
9 | Under *Edge dictionaries* tab, new dictionary can be created by clicking **Add container** button
10 |
11 | 
12 |
13 | After adding new dictionary container, a popup will appear in which name of dictionary must be entered, and if you want
14 | dictionary active from new version, a checkbox for activation must be ticked.
15 |
16 | 
17 |
18 | After adding dictionary container we can add new items that will belong to this dictionary.
19 | To add new items we click on gear left of newly created entry under *Edge dictionaries* tab which will trigger a popup.
20 |
21 | 
22 |
23 | Once you enter **Key** and **Value**, you can add dictionary item by clicking **Save** button to the right of the item.
24 | To remove dictionary item, click **Delete** button to the right of the item.
--------------------------------------------------------------------------------
/Documentation/Guides/ERROR-MAINTENANCE-PAGE.md:
--------------------------------------------------------------------------------
1 | # Set Error / Maintenance page guide
2 |
3 | The Fastly CDN will sometimes return a 503 error due to various issues that can occur. The generic text associated with a 503 error is “Service Unavailable” and it can mean variety of things. This default error response can be confusing to the customers and have a basic look and feel.
4 |
5 | This guide will show you how to set friendly or prettier 503 custom error page through Fastly module which will be served when:
6 | * When origin returns a response status greater than 500
7 | * When origin is down (i.e unhealthy, timeout, etc)
8 |
9 | To set custom Error page, go to:
10 |
11 | ```
12 | Magento admin > Stores > Configuration > Advanced > System > Full Page Cache > Fastly Configuration
13 | ```
14 |
15 | Under the Fastly Configuration, click on the **Error/Maintenance page:**
16 |
17 | 
18 |
19 | The modal window will pop up. Paste your custom HTML code into the HTML textarea and press the Upload button to save changes.
20 |
21 | 
22 |
23 | Now when Fastly returns 503 error, instead of default error page which looks something like this:
24 |
25 | 
26 |
27 | You will serve your custom error page:
28 |
29 | 
30 |
--------------------------------------------------------------------------------
/Documentation/Guides/Edge-Modules/EDGE-MODULE-BLACKFIRE-INTEGRATION.md:
--------------------------------------------------------------------------------
1 | # Fastly Edge Modules - Blackfire integration
2 |
3 | This module will enable Blackfire integration. It's available in module version 1.2.103+. It's based on instructions
4 | from [Blackfire reference guide on bypassing reverse proxy cache and CDNs](https://blackfire.io/docs/reference-guide/configuration#bypassing-reverse-proxy-cache-and-content-delivery-networks-cdn).
5 |
6 | Before you can use Fastly Edge Modules you need to [make sure they are enabled](https://github.com/fastly/fastly-magento2/blob/master/Documentation/Guides/Edge-Modules/EDGE-MODULES.md) and that you have selected the Blackfire integration module.
7 |
8 | When you click on the configuration you will be prompted with a screen like this
9 |
10 | 
11 |
12 | ## Configurable options
13 |
14 | ### ACL
15 |
16 | Pick ACL (Access Control List) that contains a list of admin IPs that are allowed to initiate profiling. If there are no ACLs listed or you want to specify a new
17 | one [you can create it using the ACL interface](https://github.com/fastly/fastly-magento2/blob/master/Documentation/Guides/ACL.md).
18 |
19 | ## Enabling
20 |
21 | After any change to the settings you need to click Upload as that will upload require VCL code to Fastly.
22 |
23 | ## Technical details
24 |
25 | Following VCL will be uploaded
26 |
27 | Snippet Type: vcl_recv
28 |
29 | ```vcl
30 | if (req.http.X-Blackfire-Query && req.http.Fastly-Client-IP ~ maint_allowlist) {
31 | if (req.esi_level > 0) {
32 | # ESI request should not be included in the profile.
33 | # Instead you should profile them separately, each one
34 | # in their dedicated profile.
35 | # Removing the Blackfire header avoids to trigger the profiling.
36 | # Not returning let it go through your usual workflow as a regular
37 | # ESI request without distinction.
38 | unset req.http.X-Blackfire-Query;
39 | } else {
40 | set req.http.X-Pass = "1";
41 | }
42 | }
43 | ```
44 |
--------------------------------------------------------------------------------
/Documentation/Guides/Edge-Modules/EDGE-MODULE-DATADOME-INTEGRATION.md:
--------------------------------------------------------------------------------
1 | # Fastly Edge Modules - DataDome integration
2 |
3 | DataDome is a real-time bot protection. To enable the module, start your 30 days free trial at https://datadome.co/free-signup/.
4 |
5 | This module enables [DataDome integration](https://docs.datadome.co/docs/magento-with-fastly-cdn "DataDome Documetation"), it provides integration between Fastly Edge module and DataDome. It is available from module version 1.2.127+.
6 |
7 | Before you can use Fastly Edge Modules you need to [make sure they are enabled](https://github.com/fastly/fastly-magento2/blob/master/Documentation/Guides/Edge-Modules/EDGE-MODULES.md) and that you have selected the Datadome integration module.
8 |
9 | Once the module is enabled, the following settings screen should be configured:
10 |
11 | 
12 |
13 | ## Configurable options
14 |
15 | | Setting | Description |
16 | |---------|-------------|
17 | | API Key | Your DataDome License key |
18 | | Exclusion Regex | The regex that will be applied to req.url.ext |
19 | | Connection Timeout | How long to wait for a timeout in milliseconds. |
20 | | First byte timeout | How long to wait for the first byte in milliseconds. |
21 | | Between bytes tiemout | How long to wait between bytes in milliseconds. |
22 |
23 | ## Enabling
24 |
25 | After any change to the settings you need to click *Upload* as that will upload require VCL code to Fastly.
26 |
27 | ## Full documentation
28 |
29 | You can access the full documentation on [DataDome's website](https://docs.datadome.co/docs/magento-with-fastly-cdn "Documentation")
--------------------------------------------------------------------------------
/Documentation/Guides/Edge-Modules/EDGE-MODULE-HARD-RELOAD-CACHE-BYPASS.md:
--------------------------------------------------------------------------------
1 | # Fastly Edge Modules - Hard Reload Cache Bypass for admins
2 |
3 | This guide will show how to configure hard reload cache bypass for admin IPs. This feature allows
4 | administrators to force a cache miss in their browser by pressing CMD/CTRL + SHIFT + R or SHIFT + F5.
5 | Administrators are defined as those users on the selected Access Control List (ACL).
6 | [More details can be found here](https://github.com/fastly/fastly-magento2/issues/147)
7 |
8 | Before you can use Fastly Edge Modules you need to [make sure they are enabled](https://github.com/fastly/fastly-magento2/blob/master/Documentation/Guides/Edge-Modules/EDGE-MODULES.md)
9 |
10 | When you click on the configuration you will be prompted with a screen like this
11 |
12 | 
13 |
14 | ## Configurable options
15 |
16 | ### ACL
17 |
18 | Pick ACL (Access Control List) that contains a list of admin IPs. If there are no ACLs listed or you want to specify a new
19 | one [you can create it using the ACL interface](https://github.com/fastly/fastly-magento2/blob/master/Documentation/Guides/ACL.md).
20 |
21 |
22 | ## Enabling
23 |
24 | After any change to the settings you need to click Upload as that will activate the functionality you configured.
25 |
26 | ## Technical details
27 |
28 | Following VCL snippets are being uploaded
29 |
30 | Snippet Type: vcl_recv
31 |
32 | ```vcl
33 | if ( req.http.Fastly-Client-IP ~ maint_allowlist && req.http.pragma ~ "no-cache" ) {
34 | set req.hash_always_miss = true;
35 | }
36 | ```
37 |
38 | Snippet Type: vcl_hash
39 |
40 | ```vcl
41 | if ( req.http.Fastly-Client-IP ~ maint_allowlist && req.http.pragma ~ "no-cache" ) {
42 | set req.hash += "NOCACHE";
43 | }
44 | ```
45 |
--------------------------------------------------------------------------------
/Documentation/Guides/Edge-Modules/EDGE-MODULE-NETACEA-INTEGRATION.md:
--------------------------------------------------------------------------------
1 | # Fastly Edge Modules - Netacea integration
2 |
3 | This module will enable Netacea integration. Netacea is a security provider providing services such
4 | as bot detection, etc. You have to have an account with Netacea before proceeding. This module only provides
5 | integration with Netacea service. It's available in module version 1.2.131+.
6 |
7 | Before you can use Fastly Edge Modules you need to [make sure they are enabled](https://github.com/fastly/fastly-magento2/blob/master/Documentation/Guides/Edge-Modules/EDGE-MODULES.md) and that you have selected the Netacea integration module.
8 |
9 | After you have enabled the module it's time to configure. You will be prompted with a screen like this
10 |
11 | 
12 |
13 | ## Configurable options
14 |
15 | In order to configure Netacea module please see the following documentation.
23 |
24 | At a minimum you will need to provide the webhook URL e.g.
25 |
26 | https://hooks.slack.com/services/XXX/XXXX/XXXXX
27 |
28 | By default Fastly module will send following notifications
29 |
30 | * Publish Key and URL Purge Events
31 | * Publish Purge All/Clean All Items Events
32 | * Publish Config change events
33 |
34 | Optionally you can
35 |
36 | * Turn on showing stack trace of purge all events - this is useful if you are experiencing issues due to frequent purges and don't know
37 | what may be triggering them
38 | * Message prefix - useful if you are sending messages from multiple Magento instances
39 |
40 | Once you have configured the webhook notifications you should see messages like this in your Slack channel
41 |
42 | 
43 |
--------------------------------------------------------------------------------
/Documentation/OPENING-ISSUES.md:
--------------------------------------------------------------------------------
1 | # How to open issues for Fastly_Cdn Module
2 |
3 | Issues are for tracking broken functionality and are intended for managing
4 | development work to address these.
5 |
6 | If you have an issue with usage or need general assistance using this module,
7 | or Fastly in general please use the [support infomation](../README.md#support).
8 |
9 | This describes what content should be added to a issue to help with an
10 | expedient resolution.
11 |
12 | ## What to post
13 |
14 | A good bug report contains the data necessary to reproduce, identify, locate
15 | and address a problem in code. Where possible it should also indicate what
16 | steps have already been taken to address the issue and their result too.
17 |
18 | A report should be reproducible on a base install of Magento to an up to date
19 | system with no additional modules.
20 |
21 | At a bare minimum include:
22 |
23 | 1. OS name and version.
24 | 1. PHP version
25 | 1. Database server name and version.
26 | 1. Magento version.
27 | 1. Composer version.
28 | 1. Description of the problem. What is happening that shouldn't?
29 | 1. Description of the expected behaviour.
30 | 1. Exact steps to reproduce the error.
31 |
32 | Additional data which can help:
33 |
34 | 1. Logs showing errors or behaviour.
35 | 1. Steps which have been taken to try address the issue.
36 | 1. Other data which indicates what may be causing the issue.
37 | 1. Stack trace if any error is seen.
--------------------------------------------------------------------------------
/Documentation/README.md:
--------------------------------------------------------------------------------
1 | # Documentation
2 |
3 | This folder contains the collected documentation for the Fastly_Cdn module.
4 |
5 | ## Contents
6 |
7 | * [Installation instructions](INSTALLATION.md)
8 | * [TLS Deployment instructions](TLS.md)
9 | * [Configuration instructions](CONFIGURATION.md)
10 | * [Purging and Other Functions](OTHER-FUNCTIONS.md)
11 | * [CLI Functions](CLI.md)
12 | * [Troubleshooting instructions](TROUBLESHOOTING.md)
13 | * [How to report bugs](OPENING-ISSUES.md)
14 |
15 | Please report any errors or problems with these documents as GitHub issues.
--------------------------------------------------------------------------------
/Documentation/TROUBLESHOOTING.md:
--------------------------------------------------------------------------------
1 | # Troubleshooting the Fastly_Cdn Module
2 |
3 | Here are a few notes on troubleshooting the Fastly_Cdn module.
4 |
5 | 1. Try disabling other non-essential modules.
6 | 1. Try disabling the Fastly_Cdn module.
7 | 1. Put the server into developer mode and see if errors are generated.
8 | 1. Check the logs in `401 Unauthorized
13 | 14 | "}; 15 | return (deliver); 16 | } 17 | 18 | -------------------------------------------------------------------------------- /etc/vcl_snippets_basic_auth/recv.vcl: -------------------------------------------------------------------------------- 1 | # Check Basic auth against a table. /admin URLs are not basic auth protected to avoid the possibility of people 2 | # locking themselves out. /oauth and /rest have their own auth so we can skip Basic Auth on them as well 3 | if ( req.method != "FASTLYPURGE" && 4 | table.lookup(magentomodule_basic_auth, regsub(req.http.Authorization, "^Basic ", ""), "NOTFOUND") == "NOTFOUND" && 5 | !req.url ~ "^/(index\.php/)?####ADMIN_PATH####/" && 6 | !req.url ~ "^/(index\.php/)?(rest|oauth|graphql)($|[\/?])" && 7 | !req.url ~ "^/pub/static/" ) { 8 | error 771; 9 | } 10 | -------------------------------------------------------------------------------- /etc/vcl_snippets_blocking/recv.vcl: -------------------------------------------------------------------------------- 1 | # Make sure we lookup end user geo not shielding. More at https://docs.fastly.com/vcl/geolocation/#using-geographic-variables-with-shielding 2 | set client.geo.ip_override = req.http.Fastly-Client-IP; 3 | if (req.method != "FASTLYPURGE" && ( ####BLOCKED_ITEMS#### )) { 4 | error 405 "Not allowed"; 5 | } -------------------------------------------------------------------------------- /etc/vcl_snippets_error_page/deliver.vcl: -------------------------------------------------------------------------------- 1 | # If we are about to serve a 5xx we need to restart then in vcl_recv error out to 2 | # get the holding page 3 | if ( resp.status >= 500 && resp.status < 600 && !req.http.ResponseObject ) { 4 | set req.http.ResponseObject = "970"; 5 | restart; 6 | } 7 | -------------------------------------------------------------------------------- /etc/vcl_snippets_force_tls/deliver.vcl: -------------------------------------------------------------------------------- 1 | set resp.http.strict-transport-security = "max-age=31536000"; 2 | -------------------------------------------------------------------------------- /etc/vcl_snippets_force_tls/recv.vcl: -------------------------------------------------------------------------------- 1 | # Force SSL immediately to avoid magento module VCL stripping off 2 | # google campaign ids like gclid 3 | if (!req.http.Fastly-SSL) { 4 | error 801 "Force SSL"; 5 | } 6 | -------------------------------------------------------------------------------- /etc/vcl_snippets_image_optimizations/recv.vcl: -------------------------------------------------------------------------------- 1 | if ( req.url.ext ~ "(?i)^(gif|png|jpg|jpeg|webp)$" ) { 2 | 3 | set req.http.X-Fastly-Imageopto-Api = "fastly"; 4 | 5 | #set req.url = querystring.set(req.url, "optimize", "(low|medium|high)"); 6 | 7 | } 8 | -------------------------------------------------------------------------------- /etc/vcl_snippets_rate_limiting/deliver.vcl: -------------------------------------------------------------------------------- 1 | # Tarpit Rate limited requests 2 | if ( resp.status == 429 && (req.http.Rate-Limit || resp.http.Fastly-Vary) ) { 3 | resp.tarpit(std.atoi(table.lookup(magentomodule_config, "tarpit_interval", "5")), 100000); 4 | set resp.http.Vary = "Cookie"; 5 | } 6 | 7 | if ( fastly.ff.visits_this_service == 0 ) { 8 | remove resp.http.Fastly-Vary; 9 | } 10 | -------------------------------------------------------------------------------- /etc/vcl_snippets_rate_limiting/fetch.vcl: -------------------------------------------------------------------------------- 1 | # VCL support for Rate limiting. Rate limiting needs to be turned on through the UI 2 | if ( req.http.Rate-Limit ) { 3 | if ( beresp.status == 429 ) { 4 | set beresp.cacheable = true; 5 | remove beresp.http.Vary; 6 | return(deliver); 7 | } else { 8 | set beresp.cacheable = false; 9 | return(pass); 10 | } 11 | } 12 | 13 | # If we get Fastly-Vary it means it was set by the Crawler Module. Unfortunately magento overwrites 14 | # Vary headers so we had to set our own Fastly-Vary header we set here. 15 | if ( beresp.status == 429 && beresp.http.Fastly-Vary ) { 16 | set beresp.http.Vary = beresp.http.Fastly-Vary; 17 | } 18 | -------------------------------------------------------------------------------- /etc/vcl_snippets_rate_limiting/hash.vcl: -------------------------------------------------------------------------------- 1 | if (req.http.Rate-Limit) { 2 | set req.hash += client.ip; 3 | return(hash); 4 | } -------------------------------------------------------------------------------- /etc/vcl_snippets_rate_limiting/miss.vcl: -------------------------------------------------------------------------------- 1 | if (req.http.Rate-Limit) { 2 | set bereq.method = req.http.X-Orig-Method; 3 | } 4 | -------------------------------------------------------------------------------- /etc/vcl_snippets_rate_limiting/recv.vcl: -------------------------------------------------------------------------------- 1 | if (####RATE_LIMITED_PATHS####) { 2 | if (req.http.Fastly-Client-Ip !~ maint_allowlist) { 3 | set req.http.Rate-Limit = "1"; 4 | set req.http.X-Orig-Method = req.method; 5 | set req.hash_ignore_busy = true; 6 | if (req.method !~ "^(GET|POST)$") { 7 | set req.method = "POST"; 8 | } 9 | } 10 | } 11 | -------------------------------------------------------------------------------- /etc/vcl_snippets_waf/recv.vcl: -------------------------------------------------------------------------------- 1 | # Specify one or multiple ACLs that are allowed to bypass WAF blocking ie. no WAF rules are going to trigger for those IPs. 2 | if(####WAF_ALLOWLIST####) { 3 | set req.http.bypasswaf = "1"; 4 | } 5 | -------------------------------------------------------------------------------- /etc/webapi_rest/di.xml: -------------------------------------------------------------------------------- 1 | 2 | 23 |
24 |
25 |
30 |
31 |
34 |  ?>)
9 |