nixpkgs/nixos/doc/manual
Michael Weiss 234d95a6fc
nixos/networking: Add the FQDN and hostname to /etc/hosts
This fixes the output of "hostname --fqdn" (previously the domain name
was not appended). Additionally it's now possible to use the FQDN.

This works by unconditionally adding two entries to /etc/hosts:
127.0.0.1 localhost
::1 localhost

These are the first two entries and therefore gethostbyaddr() will
always resolve "127.0.0.1" and "::1" back to "localhost" [0].
This works because nscd (or rather the nss-files module) returns the
first matching row from /etc/hosts (and ignores the rest).

The FQDN and hostname entries are appended later to /etc/hosts, e.g.:
127.0.0.2 nixos-unstable.test.tld nixos-unstable
::1 nixos-unstable.test.tld nixos-unstable
Note: We use 127.0.0.2 here to follow nss-myhostname (systemd) as close
as possible. This has the advantage that 127.0.0.2 can be resolved back
to the FQDN but also the drawback that applications that only listen to
127.0.0.1 (and not additionally ::1) cannot be reached via the FQDN.
If you would like this to work you can use the following configuration:
```nix
networking.hosts."127.0.0.1" = [
  "${config.networking.hostName}.${config.networking.domain}"
  config.networking.hostName
];
```

Therefore gethostbyname() resolves "nixos-unstable" to the FQDN
(canonical name): "nixos-unstable.test.tld".

Advantages over the previous behaviour:
- The FQDN will now also be resolved correctly (the entry was missing).
- E.g. the command "hostname --fqdn" will now work as expected.
Drawbacks:
- Overrides entries form the DNS (an issue if e.g. $FQDN should resolve
  to the public IP address instead of 127.0.0.1)
  - Note: This was already partly an issue as there's an entry for
    $HOSTNAME (without the domain part) that resolves to
    127.0.1.1 (!= 127.0.0.1).
- Unknown (could potentially cause other unexpected issues, but special
  care was taken).

[0]: Some applications do apparently depend on this behaviour (see
c578924) and this is typically the expected behaviour.

Co-authored-by: Florian Klink <flokli@flokli.de>
2020-05-25 14:06:25 +02:00
..
administration Revert "nixos/doc: re-format" 2019-09-19 19:17:30 +02:00
configuration nixos/manual: document use of systemd to mount filesystems (#87684) 2020-05-14 18:00:01 +02:00
development treewide: use https for nixos.org and hydra.nixos.org 2020-05-03 22:14:21 -07:00
installation treewide: use https for nixos.org and hydra.nixos.org 2020-05-03 22:14:21 -07:00
release-notes nixos/networking: Add the FQDN and hostname to /etc/hosts 2020-05-25 14:06:25 +02:00
.gitignore nixos docs: ignore generated files 2018-05-01 19:50:02 -04:00
default.nix nixos manual: have a toc for each part and chapter 2019-10-30 10:25:09 +01:00
Makefile nixos/doc/manual: Fix Makefile 2019-09-06 12:40:06 +02:00
man-configuration.xml nixos/doc: fix manpage format 2019-10-05 15:55:49 +00:00
man-nixos-build-vms.xml nixos/doc: fix manpage format 2019-10-05 15:55:49 +00:00
man-nixos-enter.xml nixos/doc: fix manpage format 2019-10-05 15:55:49 +00:00
man-nixos-generate-config.xml nixos/doc: fix manpage format 2019-10-05 15:55:49 +00:00
man-nixos-install.xml nixos-install: 'nix build' -> nix-build 2020-05-07 13:12:29 +02:00
man-nixos-option.xml Merge pull request #75439 from Ma27/submodule-fixes-for-nixos-option 2020-02-01 10:00:59 +01:00
man-nixos-rebuild.xml nixos-{rebuild,container}: Use flakeref#attrpath syntax 2020-02-05 23:15:18 +01:00
man-nixos-version.xml nixos-version: Add --json flag and show system.configurationRevision 2020-02-05 23:15:18 +01:00
man-pages.xml nixos/doc+manual: update copyright year range end 2019->2020 2020-01-14 07:01:39 -06:00
manual.xml nixos manual: move preface into own file 2019-10-30 10:25:09 +01:00
preface.xml nixos manual: refer to nix and nixpkgs manuals 2019-10-30 10:25:09 +01:00
README
shell.nix doc: Adds xml fixing script. (see previous and next commits) 2018-05-31 21:02:15 -04:00

To build the manual, you need Nix installed on your system (no need
for NixOS). To install Nix, follow the instructions at

    https://nixos.org/nix/download.html

When you have Nix on your system, in the root directory of the project
(i.e., `nixpkgs`), run:

    nix-build nixos/release.nix -A manual.x86_64-linux

When this command successfully finishes, it will tell you where the
manual got generated.