BIND’s named.conf is complaining about an "unknown option" because a directive you’ve used isn’t recognized by the version of BIND you’re running, or it’s syntactically incorrect. This isn’t about a missing feature, but about BIND’s parser encountering something it simply doesn’t understand in its configuration.
Here are the common culprits and how to fix them:
1. Typo in an Option Name
This is the most frequent reason. A simple misspelling can lead to BIND throwing its hands up.
Diagnosis: Carefully read through your named.conf and any included files. Look for options that seem slightly "off."
Fix: Correct the spelling. For example, if you intended recursion yes; but typed recusion yes;, change it to recursion yes;.
Why it works: BIND has a defined set of keywords for its configuration directives. A typo means the keyword doesn’t match any of the known ones, hence "unknown option."
2. Using an Option Not Supported by Your BIND Version
Newer BIND versions introduce new options. If you’ve copied configuration from a newer version or are using an option that was added recently, and your BIND is older, it won’t recognize it.
Diagnosis:
- Check your BIND version:
named -v - Consult the BIND documentation for your specific version (or a newer one) to see if the option in question is supported. You can usually find this on the ISC BIND website.
Fix:
- Upgrade BIND: If possible, upgrade to a newer version of BIND that supports the option.
- Remove/Replace the Option: If upgrading isn’t feasible, remove the unsupported option or find an equivalent configuration that works with your current version. For example, if you’re trying to use a new logging channel format that’s not supported, you might have to revert to older logging syntax.
Why it works: Each BIND version has a specific grammar it understands. Unsupported options are outside that grammar.
3. Incorrect Syntax for an Option
Some options require specific arguments or a particular structure. Deviating from this can cause BIND to misinterpret the directive.
Diagnosis: Check the documentation for the specific option that’s causing the error. Pay close attention to the required syntax, data types, and any surrounding punctuation.
Fix: Ensure the option is configured according to its documentation. For instance, if an option expects a list of IP addresses, it might need to be enclosed in square brackets: allow-query { 192.168.1.0/24; 10.0.0.0/8; };. If you wrote allow-query 192.168.1.0/24; 10.0.0.0/8;, BIND might not parse it correctly.
Why it works: BIND’s parser is strict about how it expects options to be presented. Correct syntax ensures it can properly parse and apply the configuration.
4. Using an Option in the Wrong Context
Certain options are only valid within specific configuration blocks (e.g., options, zone, view). Placing them in the wrong block will cause an "unknown option" error.
Diagnosis: Identify the scope of the option causing the error. Refer to BIND documentation to confirm where it’s supposed to be used.
Fix: Move the option to its correct configuration block. For example, allow-recursion is typically an option within the options block, not a zone block.
Why it works: BIND processes configuration based on hierarchical scopes. An option meant for global settings shouldn’t appear within a zone-specific definition.
5. Misplaced Braces or Semicolons
Syntax errors like missing or extra braces ({}), or semicolons (;) can confuse the BIND parser, leading it to misinterpret valid keywords as unknown options.
Diagnosis: Use a text editor that highlights matching braces and parentheses. Carefully scan your named.conf for any obvious structural issues.
Fix: Ensure all configuration blocks are properly closed with } and that each statement ends with a semicolon ;. For example, a missing semicolon after file "db.example.com"; could cause the next line to be misinterpreted.
Why it works: BIND parses configuration as a structured text file. Mismatched delimiters or missing terminators break this structure, making subsequent lines appear as invalid.
6. Using Deprecated or Removed Options
As BIND evolves, some options are deprecated and eventually removed. If you’re using an option that was present in older versions but has been deleted in your current version, BIND will report it as unknown.
Diagnosis: Check the release notes or migration guides for your BIND version to see if the option has been removed or replaced.
Fix: Replace the deprecated option with its modern equivalent or remove it if it’s no longer needed. For instance, older logging mechanisms have been replaced by logging statements with channels and categories; using the old category directive directly might cause an error.
Why it works: The parser is updated to reflect the current, supported feature set of the BIND software.
After fixing the "unknown option," the next error you’re likely to encounter, especially if you’ve been making significant configuration changes, is a syntax error related to zone file loading or incorrect ACL definitions.