After assisting another user recently, I had cause to read the handbook and consider this section:- ------------------------------------------------------------------ Code Listing 2.2: Setting the domainname # nano -w /etc/conf.d/net (Set the dns_domain variable to your domain name) dns_domain_lo="homenetwork" Note: If you choose not to set a domainname, you can get rid of the "This is hostname.(none)" messages at your login screen by editing /etc/issue. Just delete the string .\O from that file. ------------------------------------------------------------------- This is quite misleading. It implies that the value of dns_domain plays a role in determining the effective domain name/part of the fully qualified hostname of the host being configured. However, it is /etc/hosts *alone* that governs this. To whit: * dns_domain populates resolv.conf so as to change the glibc resolver behaviour when resolving a short name * gethostname(2) and getdomainname(2) refer exclusively to the currently effective hostname in memory *plus* /etc/hosts in order to retrieve their results In short, resolv.conf is for configuring the behaviour of the resolver; this has nothing to to with the gethostname/sethostname functions in glibc, nor the hostname/dnsdomainname commands. Don't believe me? Try stracing the behaviour of these. You can also carry out some simple test cases: # echo "127.0.0.1 foo" > /etc/hosts # hostname foo # mimics the behaviour of the init.d/hostname script # hostname foo # hostname --long foo # dnsdomainname -v gethostname()=`foo' Resolving `foo' ... Result: h_name=`foo' Result: h_addr_list=`127.0.0.1' # echo "127.0.0.1 foo.bar.baz foo" > /etc/hosts # hostname foo # hostname --long foo.bar.baz # dnsdomainname -v gethostname()=`foo' Resolving `foo' ... Result: h_name=`foo.bar.baz' Result: h_aliases=`foo' Result: h_addr_list=`127.0.0.1' bar.baz Note that order is important (to the credit of the handbook, it does take that into account in its /etc/hosts sample): # echo "127.0.0.1 foo foo.bar.baz" > /etc/hosts # hostname --long foo # dnsdomainname # this doesn't return anything now! Finally, the hostname is stored in memory, whereas the effective DNS domain name is always inferred from hosts: # echo "127.0.0.1 foo.bar.baz foo" > /etc/hosts # hostname foo # hostname --long foo.bar.baz # echo "127.0.0.1 quux.bar.baz quux" > /etc/hosts # hostname bar # hostname --long # what's this ... hostname: Unknown host # hostname quux # hostname quux # hostname --long # ah, this is better ... quux.bar.baz I see exchanges such as these in #gentoo all too frequently: <user_a> issue and/or hostname --long is showing "unknown_domain". why? <user_b> oh, you need to edit /etc/conf.d/net This is incorrect. In fact, I just intervened in such a discussion and, after some toing and froing, the problem was, as per usual, solved by modifying /etc/hosts (whether he did or didn't set dns_domain, let alone how, doesn't come into it). I don't think it's too presumptious to say that this is not common knowledge and it causes a huge amount of confusion. The problem is that it's rather too easy for user_b to suggest a solution for problem Y to user_a when the handbook alludes to it, yet the problem is actually X. So, the statement about /etc/issue is contextualised incorrectly and, by mere virtue of its presence, is misleading. Really though, as these mechanisms are obviously not well understood, I think the two sections in the handbook regarding dns_domain and /etc/hosts could be modified so as to render the distinction entirely clear, and to clarify the actual usage of dns_domain. There are some situations where it is a good idea to set the latter, and some where it is not but this is not explained. I think this could be accomplished in a way that preserves the overall brevity of the handbook section in question. If the docs team would be willing to accept a contribution, I would be happy to think this over and provide some sample text.
Regarding the second bullet point, I should retract the word "exclusively" as other name resolution methods can be used to obtain the correct information. However, this only of use where an external DNS server exists that contains the correct entries in the appropriate zone and, is thus beyond the scope of the documentation and this bug. By default, nsswitch.conf favours "files" over "dns" and the purpose of configuring /etc/hosts is to make sure that the host itself can resolve its own hostname and dnsdomainname without relying upon an external authority (which is unfeasible for 'ordinary' users).
Sorry to comment again but, just to clarify the role of DNS and the name service switch, here's an example from one of my systems (the second line is a temporary entry for the purposes of demonstration): # head -n2 /etc/hosts 172.16.0.1 plato.uk.parlicentre.lan plato 172.16.0.2 temphostname.uk.parlicentre.lan temphostname # hostname --long plato.uk.parlicentre.lan # hostname temphostname # hostname --long temphostname.uk.parlicentre.lan Now, I remove the first line in /etc/hosts (plato) and also edit nsswitch.conf to read "hosts: dns", thus removing "files" as a possible source of information. Let's see what happens: # hostname --long # its trying for temphostname still hostname: Unknown host No surprise there. Let's change it back to plato: # hostname plato # hostname --long plato.uk.parlicentre.lan Woah, how did it know? Well, the host is part of a corporate environment and I have a BIND server that contains the appropriate A and PTR records for 172.16.0.1. Now let's change nsswitch.conf so that it only reads "hosts: files" only, then: # hostname plato # hostname --long hostname: Unknown host The name service switch is not allowed to contact the DNS server anymore. But let's add the correct entry back to /etc/hosts (as covered by "files"): # echo "172.16.0.1 plato.uk.parlicentre.lan plato" >> /etc/hosts # hostname --long plato.uk.parlicentre.lan There we go. The moral of the story is not to conflate name service switch (nsswitch.conf) with the behaviour of the resolver (resolv.conf).
If you can provide a GuideXML patch with all your wordy changes, but condensed to make it more user-friendly, then we can consider it. As it is, though, the examples given won't hurt an installed system. Even in the existing order, users will still have working host/domainnames following the handbook's instructions, whether or not they set dnsdomainname and whatnot. I just checked my box, and the "alias" line is already in my output since I followed the handbook instructions on editing /etc/hosts, as well as every other step listed in the process: # /etc/hosts 127.0.0.1 myw0rkstation localhost Given that this particular section of the handbook is all about working with the displayed hostname, to me it makes sense to talk about related hostname editing in /etc/issue.
The point is that the vast majority of people will read that and think that defining dns_domain is akin to asserting a domain as part of the hostname (in the same way that defining "hostname" elsewhere asserts the hostname). Unfortunately, That's a reasonable assumption given that the only explanation of the setting is "Setting the domainname" but it's the wrong one [1]. That's exacerbated by claiming that, when issue displays no domain, it's related to dns_domain. It isn't. I can pretty much gurantee that people who understand this are few and far between. Look, even developers completely get the wrong end of the stick ... bug 255957. I've hung out in #gentoo for years and do not actually recall seeing anyone else offer a resolution to the 'unknown domain' matter based on an adequate level of understanding. With may people getting it wrong, and with the handbook being held up as the canonical example of all things right and good, I think it should be taken seriously. Regarding the note specifically, its locality really concerns the process of editing /etc/hosts in a following section, not configuring dns_domain. Regarding the /etc/hosts example, it is sound but there is no explanation as to _why_ it is sound. I think that the /etc/hosts section should have a note briefly describing the crucial role that it has in defining the FQDN, how order matters - fully qualified should be first, localhost last - and how it asserts the effective domain name as a result (notwithstanding other methods of resolution in more complex environments). Incidentally, if the system hostname is fully qualified then the DNS resolver will actually infer the search domain from the hostname so there is no need to set dns_domain at all! Not unless there is a specific requirement to do so. From man resolv.conf: "If no domain entry is present, the domain is determined from the local host‐ name returned by gethostname(2);" The process of defining dns_domain is given undue weight and should not, in my view, precede that of modifying /etc/hosts which could be fleshed out with a note or such. Which begets the question: can you tell me where I can find the GuideXML sources? [1] "Setting the DNS search domain" would be more accurate. In fact, I really wish the option hadn't been named as it is.
(In reply to comment #4) > can you tell me where I can find the GuideXML sources? All doc sources can be reached by appending ?passthru=1. However, the handbook that you read on gentoo.org is not a single file, but a page dynamically generated from several files, so you would need to look inside one of those for your suggested changes. Check our CVS repo: http://sources.gentoo.org/gentoo/xml/htdocs/doc/en/handbook/
For the record, this matter has recently been addressed by the following two changes. https://wiki.gentoo.org/index.php?title=Handbook%3AParts%2FInstallation%2FSystem&type=revision&diff=1179983&oldid=1170071 https://github.com/gentoo/baselayout/pull/3
