Tuning your site & platform

Most of what makes your site fast and reliable is handled for you — caching, Nginx, PHP, Redis, all of it comes tuned out of the box. But BOA also leaves a set of dials in your hands, and you turn them from your own shell, without ever touching the server. This topic is about those dials.

Everything here works the same way: you create a small text file in a folder you already own, and BOA reads it for you. There are three kinds of dial, and each has its own page in this topic:

  • Behaviour settings — how caching, sessions, Redis, access protections and a few integrations behave, set in a pair of boa_*_control.ini files (one for a single site, one for a whole platform).
  • PHP version — which PHP your sites and command-line tools run, chosen with a one-line file in your ~/static/control/ folder.
  • Modules BOA manages — a short list of modules BOA keeps on or off for you on Drupal 6/7 sites, and what to do when its choice and yours disagree.

The rest of this page is about the first kind — the .ini control files — because that's where most tuning happens. The PHP-version and module pages cover the other two.

These are all your files, in folders you already own over SFTP. None of them is the server's .barracuda.cnf — that one belongs to your host and you can't reach it. Everything in this topic lives inside your own account.

The two control files

You tune a site or a platform's behaviour with two small text files you create yourself:

  • boa_site_control.ini — settings for one site.
  • boa_platform_control.ini — settings for every site on one platform.

Neither file exists until you make it. There's a documented template for each one already on the server, full of comments explaining every setting; you copy the template, uncomment the one or two lines you actually want to change, and save it in the right place. That's the whole workflow.

Where each file goes

The location is what makes a control file take effect — put it in the wrong folder and BOA simply won't read it. There are exactly two homes:

  • Per-site: sites/<your-domain>/modules/boa_site_control.ini (for example, sites/foo.com/modules/boa_site_control.ini). This affects only that one site.
  • Per-platform: sites/all/modules/boa_platform_control.ini, inside the platform's codebase. This affects every site running on that platform.

If a site has both files, the site file wins for that site — think of the platform file as the default for all its sites, and the site file as an override for one of them.

How to switch a setting on

The steps are the same for both files. From your own shell (or over SFTP):

  1. Find the template. BOA ships a fully commented template for each file. Look for default.boa_site_control.ini and default.boa_platform_control.ini in the BOA configuration folder on the server, or ask your host to point you at them — every setting is listed with its default value and a paragraph explaining what it does.
  2. Copy it into place under the correct name (boa_site_control.ini or boa_platform_control.ini), in the folder shown above. Keep the default. prefix off your copy — that prefix marks the read-only template.
  3. Uncomment only the lines you want to change. Every setting in the template starts with a leading ; (that's an INI comment). Remove the ; from a line to make that one setting active, and set the value you want. Leave everything else commented — the defaults already listed are just there for reference.
  4. Save the file. There's no button to press and no task to run in the control panel — BOA reads the file on its own.

Give it about a minute. Changes don't appear instantly. Because BOA keeps your PHP code cached for speed, it can take roughly 60 seconds for a change to a control file to take effect. If nothing seems different right away, wait a moment and try again before assuming it didn't work.

A tiny example — this is the whole file if all you want is to shorten how long a logged-out visitor sees a cached page:

; ## INI (site level) located in sites/foo.com/modules/

speed_booster_anon_cache_ttl = 30

Everything else keeps its default. You never have to fill the file in — one active line is a perfectly valid control file.

What you can tune

The templates cover a lot of ground, and you'll never need most of it. Here's the shape of what's available, so you know where to look:

  • Front-end caching — how long anonymous visitors see a cached page (speed_booster_anon_cache_ttl), and whether Drupal's own page cache stays on (it does by default, and you almost always want it that way).
  • Sessions — how long login sessions and cookies last (session_cookie_ttl, session_gc_eol).
  • Redis cache behaviour — a set of switches for how the Redis/Valkey object cache behaves, plus timeouts and debug headers for when you're chasing a caching question.
  • Access & registration protection — options such as ignore_user_register_protection and the anonymous-node and admin-DoS protections, for the rare site that needs the defaults relaxed.
  • Search (Solr) — pointing a site at a Solr integration module (solr_integration_module) so BOA builds a Solr core for you, and controlling whether it uses your own generated config.
  • Integrations & extras — New Relic, Composer's vendor directory, private-file downloads, the cookie domain, and per-module toggles (Domain Access, AdvAgg, Entity Cache, and a few others).
  • Platform-only options — a handful of settings that only make sense for a whole platform, such as fix_files_permissions_daily for platforms you keep in Git as a single codebase.

Every one of these is documented, line by line, right inside the template file — that's the authoritative place to read exactly what a setting does before you change it. This topic points you at the ones you're most likely to reach for.

In this topic

  • Which file do I edit? — start here. Pick the thing you want to change from a table, and it tells you the one file to put it in and points you at the page with the full instructions.
  • Platform and site INI settings — the full guide to boa_site_control.ini and boa_platform_control.ini: where each lives, how a site setting overrides a platform setting, the copy-and-uncomment routine, and every setting you can reach for (caching TTL, sessions, Redis, access protections, Solr, integrations, and the platform-only options).
  • Choosing your site's PHP version — pick which PHP version serves your sites (fpm.info) and which one runs drush and composer (cli.info), or set a different version per site (multi-fpm.info), all from one-line files in ~/static/control/.
  • Modules BOA manages — the short list of modules BOA keeps switched on or off for you each night on Drupal 6/7 sites, why it does it, and your options when its choice and yours don't match.

When it's not yours to tune

The control files cover what's safe for you to change from your own account. Some performance and server settings sit outside them on purpose — PHP memory limits, Nginx worker settings, the amount of RAM a site's pool may use, adding a Solr or Redis service that isn't already running. Those live on the server, which you don't manage.

If you think one of those needs adjusting for your site, don't go hunting for a config file to edit — it's something your host or operator does. Open a support request, describe what your site needs, and let them make the change on the server side.

Where to go next