Proposal for changes to the BIND ARM (meta)

Following is a list of ideas about how we could make the BIND ARM more user-friendly, written by Ron Aitchinson. It is copied from an email thread, apologies in advance for anything that doesn't make sense. I am putting this into an issue for transparency, and to allow for feedback and input - presumably actual changes would have separate issues associated with them.

• fix the red-colored text styling for commands (anti-accessibility). NB this is part of the ReadTheDocs theme. We could deviate from the theme, but it is surprising to me nobody else is upset about this, because there are accessibility people poking at Sphinx. There is also a specific 'accessibility' theme.....)

• (I) below, means 'do these first'

Chapter 1 - About the DNS, or Terminology or Background....

1. Addition of some diagrams in section 1.4. (We need to discuss how to make diagrams that will be editable/maintainable.)
2. (I) Section 1.4 could usefully discuss the query process (brings in the whole DNS hierarchy thing).
3. (I) Specifically the functional difference between name serving and resolving (maybe with a diagram) should be brought out - a lot of understanding flows from this and a lot of poor configuration is due to user failure to understand the key differences.
4. Too many people get confused over the primary and secondary since the terms imply an order of access - this needs to be noted and explained. I cannot count the number of emails on this topic I have answered over the years.
5. (I) Addition of section 1.5 titled DNS Security and Threat Considerations or something similar (with diagram). Section to overview the various threats to an operational system and the methods used to mitigate them. No detail just links to appropriate sections. Includes Open Resolvers, DDoS, MiM, cache pollution etc, etc, 1 (classic) page max.

Chapter 2 - Installation or Getting Started

1. Remove section 2.7 to Chapter 10 (or make an appendix) this a vital section specifically for those with non-standard requirements. Residual text should refer to packages RPMs, ports etc and link to build chapter. The reason for the move - if a newbie hits this early on it may scare the beejesus out of them which can suppress learning speed drastically.

Chapter 3 (DNS Configurations and Zone Files?)

1. (I) named.conf as far as I can tell automagically appears in the ARM - it is never explained (I still recall my problems with this trivial point when the world was very young.) Either the intro here or 1.4 should be modified (trivially) to cover the basic files used by BIND.
2. (I) Separation of authoritative server examples into primary and secondary. There is some useful text in 1.4 that will help. Copy here.
3. (I) Move NOTIFY (5.1) to this chapter - unchanged (maybe).
4. (I) Add a forwarding example
5. Stealth servers? (move 5.4 unchanged)
6. Essential zone files (local loopback, RFC1918 IPs rtc.) for both authoritative and resolver to reduce mal-configuration? Hints file? or do we drop the pretense that it is even necessary these days.
7. Move all the material on zone files (4.3) in here unchanged? Current chapter 4 is already huge and since we are not covering RRs entirely it is not, technically, a reference (picky, picky).

Chapter 4 (new) DNS Operations.

1. (I) Move and renumber 3.3 and 3.4 here unchanged.
2. I note that the tools man pages are also maintained in sphinx (and presumably in the copy provided for release as well as online). I think either we just list all the utilities with a link or better still copy the description section of the man page for each tool with a link (how often does the description change though better if we could automate the process).
3. Think Dig and RNDC should be in here as well as the man pages (maybe nslookup) as frequently used tools.

Chapter 5 (Renumbered) Advanced DNS

1. (I) add reference to chapter 10 to current 5.11 (or move whole section to 10).
2. add DNS over TLS or to chapter 6?
3. DDDS Emun example?
4. RPZ (two pages here on this topic that may be helpful are https://www.zytrax.com/books/dns/ch7/rpz.html and https://www.zytrax.com/books/dns/ch9/rpz.html)

• which RA is happy to contribute as a starting point - Evan can do the extensive editing required!!
• rate-limiting

Chapter 6 New - Securing DNS Operations (or something)

1. Hardening DNS configurations (some stuff along NIST lines/RA book)
2. (I) move 5.5, 5.6 and 5.7 here

Chapter 7 New - DNSSEC

1. (I) 5.9 and 5.10 here or move DNSSEC appendix here or both! Your call entirely. Tactically I would like to see all DNSSEC material here since appendices are typically regarded as afterthoughts or of lesser importance. Impressions matter.

Chapter 8 Configuration Reference

1. (I) Intro to named.conf. Grammer layout rules etc. with and without views etc.

2. (I) In named.conf there are only three things (highly technical term) i. directive - really only one 'include' which causes BIND to perform an action during its parameter file building phase. ii. entities or statements or commands or items (check a dictionary - don't care which term is used as long as there is only one term used for everything (currently defined as clause, a statement, an option, a substatement and a phrase) - definition is as entity modifies bind behavior, may contain parameters that affect its operation and which cannot contain other entities (or statements or...). iii. clause (see no alternative to this, possibly container but that has specific OO connotations) - definition is that clauses do not affect bind behavior, may have an associated name, have no parameters and can be either empty or contain statements (or entities or...)

3. (I) Clauses - simple list with brief explanation of use and link to detailed explanation. Largely as present.

4. (I) Layout of statements (or whatever the damned name is) (see my original Bind9 book page 302 onward for an implementation

My categories were (2/3 char code possibly for space)

• Queries - statements relating to query operations
• Transfers- statements relating to zone transfer operations
• Logging - statements relating to logging operations
• Server - bit flakey, typically statements that can only appear in a server clause which tend to be pretty unique
• Zone - statements used to define zone properties or characteristics
• Security - statements that affect or control BIND security
• Views - statements that control the use of view clauses (only three)
• Resolver - statements that relate to the resolver library (may now be redundant view, ndots and search)
• Controls - only one (inet) in this category but the purest in me would not let me categorize it under operations and security which may be more sensible.
• Operations - (a.k.a. the bucket) statements that affect BIND operational characteristics or control its use of resources.

So, there are 5 bits of data that should be associated with each statement in the initial index table

1. the statement name (alphabetic order)
2. the category,
3. what clause(s) it can be used in ( 1 o2 2 char clause codes can be used)
4. a brief explanation and the default value (due to the constraints of my publisher I had to use two tables, one just for clauses - real maintenance pain).

Here is a single example to illustrate (life is too short to do two) it would appear as a single line in a table with clickable links on name, category, each of the clauses (lotta links):

allow-transfer | Transfers | O, V, Z | Defines an address_match_list (linked) that is allowed to transfer the zone information from this server. The default behavior is to allow zone transfer to any host.

Clicking the name link will take you directly to the statement description (statements are defined in alphabetic order under category so the user can browse). Clicking the category link will take you to either the first entry in the alphabetic order under category - least effort or to a simple list of statement names which can be clicked to go to the statement (too much work?). Clicking on the clause code(s) will go to the clause definition.

This structure works for raw text and hyperlinked documents - clearly navigation is trivial with hyperlinks. Statement description should progressively have examples added. See specimen of my web descriptions here: top level reference:https://www.zytrax.com/books/dns/ch7/ Queries list: https://www.zytrax.com/books/dns/ch7/queries.html

Descriptions include the formal syntax, may include one or more specific example(s) and additional text which can vary from a couple of lines to very lengthy text (see sortlist) depending on complexity or the statement nuances.

I did not use the tabular index of my book for my web pages (it's a brutal job) primarily because of the difficulty in keeping it up to date. You have significant advantages here since the developers know when they change something and can automatically update or add material to the source document. I was simply a passive recipient of BIND data which had, in my experience, variable quality of 'changes from previous release' material - the only way for me to be safe method for me to maintain the index would have been to look at every statement every release - meh. My take here is that I could contribute my web material for the initial release and that each release adds some more where necessary (many are perfectly OK now).

Chapter 9 Renumbered TroubleShooting

1. (I) Reference to Dig/nslookup and documenting all config files (?)
2. some log examples
3. logging statement reference (with link)

Chapter 10 Building Bind 9

1. (I) ex 2.7 unchanged

Appendices - unchanged except for a decision about DNSSEC

I am conflicted about whether to separate out Dynamic DNS (currently 5.2) into a separate chapter since more people are using the capability. It may well grow and DNSSEC plus DDNS is a bit of a game changer - certainly people may look for it at the top level (chapter) names. (Chapter names are important since its the first level search (and read the docs does a first rate job here).) Certainly a really good index would overcome many problem but we do not currently have one and it would be brutal work if there is no good tool. I tried typing in dynamic update to the search feature in readthedocs and got ..... squat.