{"canonical_url":"https://engineer.company/glossary/configuration/","content_markdown":"# Configuration\n\n## What it is\n\nConfiguration is everything a program reads from outside its own source code to\ndecide how to run in one particular place: the port it listens on, the database\nit connects to, the accounts it lets in, the features it switches on. In\nconversation it is nearly always shortened to config, and the files that carry\nit are config files. NIST, in SP 800-128, its guide to security-focused\nconfiguration management, defines it as “the possible conditions, parameters,\nand specifications with which an information system or system component can be\ndescribed or arranged”. The word to hold on to is described: a configuration is\na description, and the system may or may not agree with it.\n\nA program seldom takes its configuration from one place. Defaults are compiled\ninto the binary, a main file sits on disk with a directory of drop-in fragments\nbeside it, and environment variables and command-line flags arrive at start. The\nprogram merges these into one set of values, with a rule for what happens when\ntwo sources set the same key, and that rule belongs to each program. The OpenSSH\nserver keeps the first value it reads for most keywords, while other tools let a\nlater file override an earlier one. The same files read in a different order\nproduce a different system.\n\nThe formats vary: INI-style lines, TOML, YAML, JSON and formats private to one\nprogram. TOML 1.0.0 aims to be “a minimal configuration file format”, while YAML\n1.2.2 is a general data language that config files borrow, and each has its own\nrules for turning text into values.\n\n## Why it matters\n\nConfiguration is how one build serves many places. The same program runs on a\nlaptop, a staging host and production, and what differs between them is its\nconfiguration. The [Twelve-Factor App](https://12factor.net/), a methodology for\ndeployable services, draws the line there: config is “everything that is likely\nto vary between deploys”, such as handles to backing services, credentials for\noutside services and the hostname of each deploy. It requires strict separation\nof config from code, and it offers a test worth applying anywhere: whether “the\ncodebase could be made open source at any moment, without compromising any\ncredentials”.\n\nThe same text marks the opposite edge. Internal wiring that stays the same on\nevery deploy, such as a web framework’s table of routes, falls outside its\ndefinition and is “best done in the code”. A value that is the same on every\ndeploy is code dressed as a setting, and a file only gives it another place to\nbe wrong.\n\nConfiguration is also where a system states its security: who may log in, which\nports answer, what a firewall lets through. A host is exactly as hardened as the\nvalues it is actually using, and between a file and those values sit the parser,\nthe precedence rules, the compiled defaults, the program version and the\nenvironment. Any of them can change the outcome while the file stays the same,\nso the dependable habit is to ask the program what it is using and treat that\nanswer as the configuration.\n\n## What it looks like in practice\n\nThis site is configured in one TOML file, hugo.toml, which sets its languages,\ntaxonomies and mounts, among much else. One table in hugo.toml shows how much a\nfew lines can decide:\n\n```toml\n[frontmatter]\n  date = [\"date\", \":git\", \":fileModTime\"]\n  lastmod = [\"lastmod\", \":git\", \":fileModTime\"]\n```\n\nEach list is a lookup order: a date written in the page itself, then the date of\nthe last commit that touched the file, then the file’s modification time. A flag\nnear the top of the file, `enableGitInfo = true`, lets Hugo read the git history\nat all. The comment above the table explains the first entry: the literal\nfront-matter field has to be named, or a `lastmod` written in a page is silently\nignored while the site builds as usual.\n\nThat table is the fix described in\n[repairing a sitemap in which most pages shared one timestamp](/portfolio/fixed-a-sitemap-with-one-shared-timestamp/).\nThe sitemap had told search engines that 172 of the site’s 176 pages last\nchanged at the same instant: with the file’s modification time as the source of\nthe date, each run of the content export, which writes out every file again,\nrestamped all of them at once. The fallback chain\nmoved the source to the version history. At that recorded implementation stage,\na re-sync after a month of content edits touched eight files of 186.\n\nOn a server, the same lesson runs through\n[hardening SSH with three stages of validation](/portfolio/hardened-ssh-to-24-validated-directives/).\nAn automation role had written the SSH daemon’s configuration for months when an\naccess report in September 2026 read the daemon’s resolved settings and found\ntwo of them disagreeing with the role’s file. The operating system’s own\ndefaults sat above the drop-in, and for those two settings the first occurrence\nwins, so the fix was a filename prefix that sorts ahead of the vendor’s. Around\nit the role now validates in three stages: the candidate file is syntax-checked\nbefore install, the assembled configuration is checked after, and the resolved\noutput is read back with 24 directives asserted. Two directives were left out on\npurpose, because the daemon no longer implements them.\n\n[Three SSH brute-force protections that never worked](/portfolio/three-locks-on-the-door-none-of-them-locked/)\nshows the failure from the other side. In August 2026 a review set each\nprotection's configuration beside the running host. All three were written down,\nall three printed in every report, and none had done its job since the day the\nhost was built. The jail's configuration still named port 22, a value left\nbehind when the initial hardening moved the daemon to 1986. The rate limit's own\nline was right, and the order of the firewall's rules undid it: a broader rule\nlisted above it caught the same traffic first. The ban action's configuration\ncalled a packet-filter binary that the package system recommends without\nrequiring, and on this host that program never resolved. Two rules came out of\nthe review: every security control is backed by an assertion that tests it,\nnever by a comment that describes it, and a firewall is checked by where each\nrule sits in the order, not by whether it is listed.\n\n## Where it goes wrong\n\nEach failure below is a file that is correct as text and wrong as behaviour, and\neach has a check that reads the behaviour.\n\n1. The wrong source wins. The OpenSSH manual for its server configuration says:\n   “Unless noted otherwise, for each keyword, the first obtained value will be\n   used.” A vendor default read before your drop-in therefore beats it, and a\n   tool where the last value wins turns the same layout around. Read the\n   precedence rule in the program’s own manual, then ask the program: `sshd -t`\n   checks that a configuration is valid, and `sshd -T` prints the effective one.\n2. A TOML key lands in the wrong table. In TOML 1.0.0 the pairs under a\n   `[table]` header belong to it “until the next header or EOF”, and indentation\n   is ignored. A key added at the bottom of a file joins the last table even\n   when it is written flush left. Keep tables at the end and plain keys above\n   them. Defining a key or a table twice is invalid, so a duplicate is an error\n   to fix, never a way to override.\n3. A plain YAML value changes type. Under the core schema, which YAML 1.2.2\n   recommends as the default, an unquoted value that matches one of its patterns\n   becomes a number, a boolean or null: `1.10` is the float 1.1, `0o17` is the\n   integer 15, `0123` comes back as 123, `FALSE` is a boolean and `~` is null.\n   Quote every value that has to stay text, version strings and identifiers with\n   leading zeros first. The spec also counts repeated mapping keys among the\n   ways a load ends incomplete, so a key written twice is a defect.\n4. A setting reads as active and does nothing. A rule shadowed by an earlier\n   one, a directive a newer release has dropped, a port that the service has\n   since left: each stays in the file and looks deliberate. The jail on port 22\n   and the rate limit beneath a broader rule both printed as healthy. A check\n   that reads each file alone passes them, so assert order and presence against\n   the running system.\n5. A secret travels with the file. A password in a configuration file goes\n   wherever the file goes: the repository, the backups, the bug report.\n   Twelve-Factor keeps config in environment variables partly because,\n   unlike config files, “there is little chance of them being checked into the\n   code repo accidentally”.\n\n## Further reading\n\n- [NIST CSRC Glossary: configuration](https://csrc.nist.gov/glossary/term/configuration)\n  — each definition NIST publications give the term, with its source document.\n- [TOML v1.0.0](https://toml.io/en/v1.0.0) — the complete specification, short\n  enough to read in one sitting.\n- [YAML Ain’t Markup Language, version 1.2.2](https://yaml.org/spec/1.2.2/) —\n  the specification; chapter 10 holds the core schema that decides what a plain\n  value becomes.\n- [The Twelve-Factor App: Config](https://12factor.net/config) — the case for\n  keeping deploy-specific values out of the code, with the open-source test.\n- [sshd_config(5)](https://man.openbsd.org/sshd_config) — the OpenSSH server’s\n  configuration manual, with its first-value rule, Include and Match.\n- [sshd(8)](https://man.openbsd.org/sshd) — the daemon’s manual, where `-t`\n  checks a configuration and `-T` prints the effective one.\n\n\u003chttps://engineer.company/glossary/configuration/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"Where a program’s settings come from, which value wins when several sources disagree, and how to prove that what you wrote is what is running.","formats":{"gemtext":"https://engineer.company/glossary/configuration/index.gmi","gopher":"https://engineer.company/glossary/configuration/gophermap","html":"https://engineer.company/glossary/configuration/","json":"https://engineer.company/glossary/configuration/index.json","markdown":"https://engineer.company/glossary/configuration/index.md","pdf":"https://engineer.company/glossary/configuration/index.pdf"},"kind":"page","language":"en","title":"What is configuration?","url":"https://engineer.company/glossary/configuration/","version":1}