From f486f50c80a466f89efba9e4c9142944c7f76b5a Mon Sep 17 00:00:00 2001 From: LiudmylaNad Date: Mon, 28 Sep 2026 13:04:10 +0200 Subject: docs: Update Host name page to VyOS 1.5 standards (#2254) --- docs/configuration/system/host-name.md | 120 ++++++++++++++++++++++----------- 1 file changed, 80 insertions(+), 40 deletions(-) diff --git a/docs/configuration/system/host-name.md b/docs/configuration/system/host-name.md index 81840d1f..b8aa5d92 100644 --- a/docs/configuration/system/host-name.md +++ b/docs/configuration/system/host-name.md @@ -1,70 +1,110 @@ +--- +myst: + html_meta: + description: | + Host information sets the router's system name and controls how it + resolves host names to IP addresses. It covers the host name, the + domain name, and static host mappings kept in the local hosts file. + keywords: host information, host name, domain name, static host mapping +--- + (host-information)= -# Host Information +# Host information -This section describes the system's host information and how to configure them, -it covers the following topics: +Host information sets the router's system name and controls how it +resolves host names to IP addresses. -- Host name -- Domain -- IP address -- Aliases +## Configuration -## Hostname +### Host name -A hostname is the label (name) assigned to a network device (a host) on a -network and is used to distinguish one device from another on specific networks -or over the internet. On the other hand this will be the name which appears on -the command line prompt. +A host name is the label that distinguishes the router from other +devices on the network. It appears in the router's command-line prompt +and log messages. ```{cfgcmd} set system host-name \ - The hostname can be up to 63 characters. A hostname - must start and end with a letter or digit, and have as interior characters - only letters, digits, or a hyphen. +**Configure the router's host name.** + +The host name must start and end with a letter or digit, may contain +letters, digits, hyphens, and periods in between, and must not exceed 63 +characters. Otherwise, the commit fails. - The default hostname used is `vyos`. +By default, the router uses `vyos`. ``` -## Domain Name +Example: +```none +set system host-name router-east +``` -A domain name is the label (name) assigned to a computer network and is thus -unique. VyOS appends the domain name as a suffix to any unqualified name. For -example, if you set the domain name `example.com`, and you would ping the -unqualified name of `crux`, then VyOS qualifies the name to `crux.example.com`. +### Domain name + +A domain name identifies the network the router belongs to. Setting it +allows hosts in that network to be reached by a short name. When the +router looks up a name with no domain, such as `crux`, it appends the +domain name and looks up `crux.example.com`. ```{cfgcmd} set system domain-name \ -Configure system domain name. A domain name must start and end with a letter -or digit, and have as interior characters only letters, digits, or a hyphen. +**Configure the router's domain name.** + +The domain name must begin with a letter or digit and may contain +letters, digits, hyphens, and periods. Otherwise, the commit fails. ``` -## Static Hostname Mapping +Example: +```none +set system domain-name example.com +``` -How an IP address is assigned to an interface in {ref}`ethernet-interface`. -This section shows how to statically map an IP address to a hostname for local -(meaning on this VyOS instance) name resolution. This is the VyOS equivalent to -`/etc/hosts` file entries. +### Static host mapping +A static host mapping ties a host name to one or more IP addresses. The +router keeps it in the `/etc/hosts` file and resolves that name from +there. -:::{note} -Do *not* manually edit `/etc/hosts`. This file will automatically be -regenerated on boot based on the settings in this section, which means you'll -lose all your manual edits. Instead, configure static host mappings as follows. -::: +```{note} +Do not manually edit `/etc/hosts`. The router regenerates this file +whenever the configuration is applied (at boot and on every commit that +changes these settings), so any manual edits are lost. Instead, +configure static host mappings as follows. +``` ```{cfgcmd} set system static-host-mapping host-name \ inet \ -Create a static hostname mapping which will always resolve the name -`` to IP address `
`. +**Map a host name to an IP address for local name resolution.** + +The address can be IPv4 or IPv6, and the same host name can map to more +than one address. + +Each `host-name` mapping requires at least one `inet` address. +Otherwise, the commit fails. ``` + +Example: + +```none +set system static-host-mapping host-name server1 inet 192.0.2.10 +``` + ```{cfgcmd} set system static-host-mapping host-name \ alias \ -Create named `` for the configured static mapping for ``. -Thus the address configured as {cfgcmd}`set system static-host-mapping -host-name inet
` can be reached via multiple names. +**Configure an alias for a static host mapping.** + +The alias points to the same address as its host name, and a mapping +can have more than one alias. -Multiple aliases can be specified per host-name. -``` \ No newline at end of file +Each alias must start and end with a letter or digit, may contain +letters, digits, hyphens, and periods in between, and must not exceed 63 +characters. Otherwise, the commit fails. +``` + +Example: + +```none +set system static-host-mapping host-name server1 alias mail +``` -- cgit v1.2.3