I never want to see exciting tech in production. As the guy who gets
woken up at 4am when it breaks, I’d much rather have boring.
For years, I’ve been optimizing for boring. I try not to invent new
standards, usually there’s already something good enough out there. Why
write a new library, style guide, protocol or data schema? Worst case,
I’d rather copy as much of the spirit of an old standby into a new realm
than start from scratch.
In that spirit, I’ve long been putting up snippets up as Github gists
with titles like, “The Most Boring nginx.conf”. The spirit of the
projects has always been the same: I want the simplest template of
reasonable defaults for a thing, and I may as well make it public.
Now at first glance it might sound like I’d put up the most minimal
config possible, because what’s more boring than nothing? Sadly, this is
rarely the case. Instead, I actually include all the default value for
important parameters in as defaults. “Why!?” I’ve been asked by friends
and coworkers who’ve suffered through my needlessly long configs. Two
reasons: explicitness & reference. First, I often see folks putting
default values in as if they needed to be specified. This leads to cargo
cult configs (I truly hope you’ve never experienced old sendmail
configs, which consist entirely of remembrances of use cases lost),
which will eventually cascade into a Revolution in which Everything Must
Second is as reference to default values. Sometimes defaults change.
Sometimes, expectations are made of these default values. And while they
may be the default, ultimately you are responsible for software being
configured this way. You are specifying this behaviour, and so I
encourage being explicit.
Of course, if you look at my configs, you’ll occasionally note that I
have more than a single “default” left in comments. Usually these are
Debian or Red Hat packager settings that vary from the vendor defaults.
I list them because many people accidentally mistake them for official
defaults. And why wouldn’t you? If you install with a system package,
it’s settings truly are a default.
So I’ve discussed the two values I always consider in my configs: vendor
and packager defaults. But often that is not enough.
Consider a common usage of Nginx: that of a front-end proxy for web
applications. For that we want TLS settings, vhost settings, and
potentially many features that aren’t on by default. For this we need to
have an understanding of the browser landscape, HTTP semantics
(especially about caching), and expectations about the app to be
Worst of all, we have the atrocious default values for TLS that ship
with almost anything built on OpenSSL. You see, OpenSSL rarely updates
their recommended ciphers, and even if they did they likely wouldn’t
match browser best practices. For that sort of thing, it’s important to
refer to expert third parties.
Finally, some things just aren’t clear. Sometimes performance tuning is
off by default, even when it is appropriate in most cases. Sometimes
there are bugs outstanding that require workarounds. For this sort of
thing, we can only confidently refer to the source.
Which is to say, in making the most boring configs, I comb through the
vendor docs, common packager settings, expert guidance, and the source
to figure out what exactly the best general value should be.
Then I actually combine it into a config. Of course, the file should
start with a description and some links to the official doc for the
settings in question. I always stick a comment saying that the file is
config managed and shouldn’t be changed by hand. Because I do so hope we
aren’t savages here.
Then I go through all the settings, set into logical group (often
alphabetical inside those groups) and every single value has a comment
with a justification. It might be “vendor default” or “debian default”,
or it might be enabling a straightforward feature. But anything which
might be mistaken for an interesting value should include a link to an
explanatory reference or ticket.
You might wonder why I’m not doing this in chef, or puppet, or ansible
or any of the many tools I use every day. Would templates make this
clearer? The problem is that to do so would make some folks feel
isolated. These are reference texts, and exist as a place outside config
management modules where we can share our common ends, even if we don’t
share means. And ultimately, all this stuff should just be in the
vendor’s defaults, right?
I’ve described the why and the how, so if you’re still interested in
what these actually are, you can find them at: