Content Cache

The content-cache charm includes a sites configuration option, which is a YAML-formatted string that can be used to configure virtual hosts/sites. This section documents the format and available options.

Examples

Here is the most basic configuration that can be specified. This will configure a vhost named basic_site listening on port 80 and any URL for that site (because we’ve specified “/” as the location) will forward to a single backend listening on port 80 and the IP address of 127.0.0.10.

basic_site:
  locations:
    /:
      backends:
        - 127.0.0.10:80

And here’s a more involved example. This site has some public, some authenticated content, using another site with two IPs for authentication. In this case, 10.1.1.2 and 10.1.1.3 would need to listen on 443 for auth.example1.com and process authentication requests.

example1.com:
  tls-cert-bundle-path: /var/lib/haproxy
  locations:
    '/':
      extra-config:
        - root /srv/example1.com/content/
        - autoindex on
    '/auth':
      modifier: '='
      backends:
        - 10.1.1.2:443
        - 10.1.1.3:443
      backend-check-path: /status
      backend-inter-time: '10s'
      backend-maxconn: 64
      backend-path: /auth-check/
      backend-tls: True
      cache-maxconn: 4096
      cache-validity: '200 401 1h'
      origin-headers:
        - Original-URI: $request_uri
        - Resource-Name: example1
      extra-config:
        - internal
        - proxy_cache_key $http_authorization
      site-name: auth.example1.com
    '/status':
      extra-config:
        - stub_status on
    '/private/content/':
      extra-config:
        - root /srv/example1.com/content/
        - autoindex on
        - auth_request /auth
      nagios-expect: 401 Unauthorized

Reference

Each virtual host is a top level option in the sites yaml, e.g.:

site1.local:
site2.local:

However, you can optionally also specify configs as a top level key, which will not be configured as a virtual host, but allow you to define variables for use later via YAML Anchors. As an example

configs:              
  backends: &BACKENDS ['127.0.1.10:80', '127.0.1.11:80', '127.0.1.12:80']                                                                    
  hmac_key: &HMAC_KEY SrRorTsImr92B6FfSKBFrSIiR5NYGS+gdjd8oGoVH44=   

site1.local:                                                                                                                                 
  port: 80                                                                                                                                   
  locations:                                                                                                                                 
    /:                                                                                                                                       
      backends: *BACKENDS                                                                                                                    
      signed-url-hmac-key: *HMAC_KEY                                                                                                         
      origin-headers:                                                                                                                        
        - X-Origin-Key: Sae6oob2aethuosh                                                                                                     
        - X-Some-Header-1: something one two three                                                                                           
        - X-Some-Header-2: something:one:two:three 

site2.local:                                                                                                                                 
  locations:                                                                                                                                 
    /:                                                                                                                                       
      backends: *BACKENDS                                                                                                                    

See also the “sites secrets configuration” section of this documentation.

Under each top level site name the following options are supported:

• default
  • If set to any non-empty value, this vhost will be used as the default (i.e. clients requesting an IP but not a specific hostname would return this virtual host).
• locations
  • A list containing locations within the vhost (.e.g. “/”, “/other-path/”), each of which is a key containing values to be assigned to that location. See the “locations” subsection below for more detail.
• port
  • The port for this vhost to listen on. Defaults to 80 if tls-cert-bundle-path isn’t defined, or 443 if that is defined.
• redirect-http-to-https
  • If this is defined (i.e. has any non-empty value), traffic will be redirected from HTTP to HTTPS.
• site-name
  • The name of the vhost. If not specified, the top level key will be used (so in the example above, either site-name1 or site-name2).
• tls-cert-bundle-path
  • The location on disk of your TLS certificate bundle.

Under the “locations” key, the following options are supported:

• backends
  • A list of strings in the form of ‘$IP:$PORT’ that backend connections for this virtual host should be sent to.
• backend-check-path
  • The path for content-cache to use to check the health of backends.
• backend-inter-time
  • The interval between checking for health of backends. Defaults to 2 seconds (‘2s’).
• backend-maxconn
  • The maximum number of simultaneous connections to the defined backends. Defaults to 2048.
• backend-options
  • Other options that can be passed to HAProxy for backends. Defaults to ‘http-request set-header X-Forwarded-For %[src]’.
• backend-path
  • The path to prepend before sending to backends.
• backend-tls
  • The path on disk to use for TLS certificates to encrypt traffic to backends with.
• cache-background-update
  • All updates will be done in the background. The stale file is returned for all requests until the updated file is fully downloaded. Set to None to disable for this location if the enable_cache_background_update config option is True (which is the default). Defaults to whatever the enable_cache_background_update config option is set to.
• cache-maxconn
  • The maximum number of simultaneous connections to the nginx cache for this location. Defaults to 2048.
• cache-min-uses
  • Sets the number of times an item must be requested by clients before caching it. This is useful if the cache is constantly filling up, as it ensures that only the most frequently accessed items are added to the cache. Defaults to 1.
• cache-valid
  • A list of space-separated strings with HTTP response code(s) followed by cache duration. For example [‘200 302 1h’, ‘404 1m’], which would mean 200 and 302 responses are cached for 1 hour and 404 responses are cached for 1 minute.
• extra-config
  • A list of additional configuration items to be specified for this location not covered by other options.
• modifier
  • Modifier to be used by Nginx when matching locations within a virtual host. See Configuring NGINX and NGINX Plus as a Web Server | NGINX Plus for more details.
• nagios-expect
  • Comma-delimited list of strings, at least one of them is expected in the first (status) line of the server response for nagios check for this location (default: HTTP/1.) If specified skips all other status line logic (ex: 3xx, 4xx, 5xx processing). Requires a relation to the nrpe charm.
• origin-headers
  • Allows redefining or appending fields to the request header passed to the proxied server. The value can contain text, variables, and their combinations.
• signed-url-hmac-key
  • The key to use to create secure URLs.
• site-name
  • The site name the backends will expect requests to use. If you have multiple “locations” for a single virtual host they may need to be configured with different site names. Defaults to the site name defined for the virtual host.