diff options
| author | Lubomir Rintel <lkundrak@v3.sk> | 2016-10-19 15:42:05 +0200 |
|---|---|---|
| committer | Lubomir Rintel <lkundrak@v3.sk> | 2016-10-19 16:41:55 +0200 |
| commit | 1b44d328ded4bc5ca478919fb2816355636d9660 (patch) | |
| tree | 1913163c74b8dcb34c5c03e1bf0fc4f4b2d44ccf | |
| parent | 956f0be2f99e1a92bcd5c7ac395839455a01bf92 (diff) | |
| parent | 6fa4f9c399b6935cd5a938f3315f7537e41f4bcd (diff) | |
Merge branch 'master' of https://git.fedorahosted.org/cgit/docs/networking-guide
24 files changed, 10471 insertions, 1 deletions
diff --git a/configure.ac b/configure.ac index a245d7293..d0772a171 100644 --- a/configure.ac +++ b/configure.ac @@ -1199,6 +1199,7 @@ data/Makefile docs/Makefile docs/api/Makefile docs/api/version.xml +docs/guide/Makefile docs/libnm-glib/Makefile docs/libnm-glib/version.xml docs/libnm-util/Makefile diff --git a/docs/Makefile.am b/docs/Makefile.am index 52cbe5286..8d03d7064 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -1,4 +1,4 @@ -SUBDIRS = libnm api +SUBDIRS = libnm api guide if WITH_LEGACY_LIBRARIES SUBDIRS += \ diff --git a/docs/guide/Author_Group.xml b/docs/guide/Author_Group.xml new file mode 100644 index 000000000..c63175bd1 --- /dev/null +++ b/docs/guide/Author_Group.xml @@ -0,0 +1,16 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> +<authorgroup> + + <author> + <firstname>Stephen</firstname> + <surname>Wadeley</surname> + <affiliation> + <orgname>Red Hat</orgname> + <orgdiv>Customer Content Services</orgdiv> + </affiliation> + <email>swadeley@redhat.com</email> + </author> + +</authorgroup> diff --git a/docs/guide/BIND.xml b/docs/guide/BIND.xml new file mode 100644 index 000000000..7914ab0a7 --- /dev/null +++ b/docs/guide/BIND.xml @@ -0,0 +1,2130 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<section id="sec-BIND"> + <title>BIND</title> + <indexterm> + <primary>Berkeley Internet Name Domain</primary> + <see>BIND</see> + </indexterm> + <para> + This section covers <systemitem class="service">BIND</systemitem> (Berkeley Internet Name Domain), the <systemitem class="protocol">DNS</systemitem> server included in &MAJOROS;. It focuses on the structure of its configuration files, and describes how to administer it both locally and remotely. + </para> + <section id="sec-bind-empty-zones"> + <title>Empty Zones</title> + <para> + <systemitem class="service">BIND</systemitem> configures a number of <quote>empty zones</quote> to prevent recursive servers from sending unnecessary queries to Internet servers that cannot handle them (thus creating delays and SERVFAIL responses to clients who query for them). These empty zones ensure that immediate and authoritative NXDOMAIN responses are returned instead. The configuration option <command>empty-zones-enable</command> controls whether or not empty zones are created, whilst the option <command>disable-empty-zone</command> can be used in addition to disable one or more empty zones from the list of default prefixes that would be used. + </para> + <para> + The number of empty zones created for <ulink url="http://www.rfc-editor.org/info/rfc1918"><citetitle pubwork="webpage">RFC 1918</citetitle></ulink> prefixes has been increased, and users of <systemitem class="service">BIND 9.9</systemitem> and above will see the <ulink url="http://www.rfc-editor.org/info/rfc1918"><citetitle pubwork="webpage">RFC 1918</citetitle></ulink> empty zones both when <command>empty-zones-enable</command> is unspecified (defaults to <literal>yes</literal>), and when it is explicitly set to <literal>yes</literal>. + </para> + + </section> + <section id="sec-bind-namedconf"> + <title>Configuring the named Service</title> + <indexterm significance="preferred"> + <primary>BIND</primary> + <secondary>utilities</secondary> + <tertiary><systemitem class="service">named</systemitem></tertiary> + </indexterm> + <para> + When the <systemitem class="service">named</systemitem> service is started, it reads the configuration from the files as described in <xref linkend="table-bind-namedconf-files" />. + </para> + <indexterm> + <primary><filename>/etc/named.conf</filename></primary> + <see>BIND</see> + </indexterm> + <indexterm> + <primary>BIND</primary> + <secondary>files</secondary> + <tertiary><filename>/etc/named.conf</filename></tertiary> + </indexterm> + <indexterm> + <primary>BIND</primary> + <secondary>directories</secondary> + <tertiary><filename class="directory">/etc/named/</filename></tertiary> + </indexterm> + <table id="table-bind-namedconf-files"> + <title>The named Service Configuration Files</title> + <tgroup cols="2"> + <colspec colname="path" colnum="1" colwidth="30*" /> + <colspec colname="description" colnum="2" colwidth="50*" /> + <thead> + <row> + <entry> + Path + </entry> + <entry> + Description + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <filename>/etc/named.conf</filename> + </entry> + <entry> + The main configuration file. + </entry> + </row> + <row> + <entry> + <filename class="directory">/etc/named/</filename> + </entry> + <entry> + An auxiliary directory for configuration files that are included in the main configuration file. + </entry> + </row> + </tbody> + </tgroup> + </table> + <para> + The configuration file consists of a collection of statements with nested options surrounded by opening and closing curly brackets (<literal>{</literal> and <literal>}</literal>). Note that when editing the file, you have to be careful not to make any syntax error, otherwise the <systemitem class="service">named</systemitem> service will not start. A typical <filename>/etc/named.conf</filename> file is organized as follows: + </para> + <programlisting><replaceable>statement-1</replaceable> ["<replaceable>statement-1-name</replaceable>"] [<replaceable>statement-1-class</replaceable>] { + <replaceable>option-1</replaceable>; + <replaceable>option-2</replaceable>; + <replaceable>option-N</replaceable>; +}; +<replaceable>statement-2</replaceable> ["<replaceable>statement-2-name</replaceable>"] [<replaceable>statement-2-class</replaceable>] { + <replaceable>option-1</replaceable>; + <replaceable>option-2</replaceable>; + <replaceable>option-N</replaceable>; +}; +<replaceable>statement-N</replaceable> ["<replaceable>statement-N-name</replaceable>"] [<replaceable>statement-N-class</replaceable>] { + <replaceable>option-1</replaceable>; + <replaceable>option-2</replaceable>; + <replaceable>option-N</replaceable>; +};</programlisting> + <note> + <title>Running BIND in a chroot environment</title> + <para> + If you have installed the <package>bind-chroot</package> package, the BIND service will run in the <command>chroot</command> environment. In that case, the initialization script will mount the above configuration files using the <command>mount --bind</command> command, so that you can manage the configuration outside this environment. There is no need to copy anything into the <filename class="directory">/var/named/chroot/</filename> directory because it is mounted automatically. This simplifies maintenance since you do not need to take any special care of <systemitem class="service">BIND</systemitem> configuration files if it is run in a <command>chroot</command> environment. You can organize everything as you would with <systemitem class="service">BIND</systemitem> not running in a <command>chroot</command> environment.</para> + <para>The following directories are automatically mounted into the <filename class="directory">/var/named/chroot/</filename> directory if the corresponding mount point directories underneath <filename class="directory">/var/named/chroot/</filename> are empty: + <itemizedlist> + <listitem> + <para> + <filename>/etc/named</filename> + </para> + </listitem> + <listitem> + <para> + <filename>/etc/pki/dnssec-keys</filename> + </para> + </listitem> + <listitem> + <para> + <filename>/run/named</filename> + </para> + </listitem> + <listitem> + <para> + <filename>/var/named</filename> + </para> + </listitem> + <listitem> + <para> + <filename>/usr/lib64/bind</filename> or <filename>/usr/lib/bind</filename> (architecture dependent). + </para> + </listitem> + </itemizedlist> + </para> + + <para> + The following files are also mounted if the target file does not exist in <filename class="directory">/var/named/chroot/</filename>: +<itemizedlist> + <listitem> + <para> + <filename>/etc/named.conf</filename> + </para> + </listitem> + <listitem> + <para> + <filename>/etc/rndc.conf</filename> + </para> + </listitem> + <listitem> + <para> + <filename>/etc/rndc.key</filename> + </para> + </listitem> + <listitem> + <para> + <filename>/etc/named.rfc1912.zones</filename> + </para> + </listitem> + <listitem> + <para> + <filename>/etc/named.dnssec.keys</filename> + </para> + </listitem> + <listitem> + <para> + <filename>/etc/named.iscdlv.key</filename> + </para> + </listitem> + <listitem> + <para> + <filename>/etc/named.root.key</filename> + </para> + </listitem> + +</itemizedlist> +</para> + </note> +<important> + <para> + Editing files which have been mounted in a <command>chroot</command> environment requires creating a backup copy and then editing the original file. Alternatively, use an editor with <quote>edit-a-copy</quote> mode disabled. For example, to edit the BIND's configuration file, <filename>/etc/named.conf</filename>, with Vim while it is running in a <command>chroot</command> environment, issue the following command as <systemitem class="username">root</systemitem>: + <screen>~]# <command>vim -c "set backupcopy=yes" /etc/named.conf</command></screen> + </para> +</important> + + <section id="sec-Installing_Bind_In_A_Chroot_Environment"> +<title>Installing BIND in a chroot Environment</title> +<para> +To install <application>BIND</application> to run in a <command>chroot</command> environment, issue the following command as <systemitem class="username">root</systemitem>: + <screen>~]# <command>dnf install bind-chroot</command></screen> + </para> + <para> + To enable the <systemitem class="daemon">named-chroot</systemitem> service, first check if the <systemitem class="daemon">named</systemitem> service is running by issuing the following command: + <screen>~]$ <command>systemctl status named</command></screen> + If it is running, it must be disabled.</para> + <para> + To disable <systemitem class="daemon">named</systemitem>, issue the following commands as <systemitem class="username">root</systemitem>: + <screen>~]# <command>systemctl stop named</command></screen> +<screen>~]# <command>systemctl disable named</command></screen> +Then, to enable the <systemitem class="daemon">named-chroot</systemitem> service, issue the following commands as <systemitem class="username">root</systemitem>: +<screen>~]# <command>systemctl enable named-chroot</command></screen> +<screen>~]# <command>systemctl start named-chroot</command></screen> + </para> + <para> + To check the status of the <systemitem class="daemon">named-chroot</systemitem> service, issue the following command as <systemitem class="username">root</systemitem>: + <screen>~]# <command>systemctl status named-chroot</command></screen> + </para> + </section> + <section id="sec-bind-namedconf-state"> + <title>Common Statement Types</title> + <para> + The following types of statements are commonly used in <filename>/etc/named.conf</filename>: + </para> + <variablelist> + <varlistentry> + <term> + <indexterm> + <primary>BIND</primary> + <secondary>configuration</secondary> + <tertiary><option>acl</option> statement</tertiary> + </indexterm> + <option>acl</option> + </term> + <listitem> + <para> + The <option>acl</option> (Access Control List) statement allows you to define groups of hosts, so that they can be permitted or denied access to the nameserver. It takes the following form: + </para> + <programlisting>acl <replaceable>acl-name</replaceable> { + <replaceable>match-element</replaceable>; + ... +};</programlisting> + <para> + The <replaceable>acl-name</replaceable> statement name is the name of the access control list, and the <replaceable>match-element</replaceable> option is usually an individual <systemitem class="protocol">IP</systemitem> address (such as <literal>10.0.1.1</literal>) or a <firstterm>Classless Inter-Domain Routing</firstterm> (<acronym>CIDR</acronym>) network notation (for example, <literal>10.0.1.0/24</literal>). For a list of already defined keywords, see <xref linkend="table-bind-namedconf-common-acl" />. + </para> + <table id="table-bind-namedconf-common-acl"> + <title>Predefined Access Control Lists</title> + <tgroup cols="2"> + <colspec colname="keyword" colnum="1" colwidth="20*" /> + <colspec colname="description" colnum="2" colwidth="60*" /> + <thead> + <row> + <entry> + Keyword + </entry> + <entry> + Description + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <option>any</option> + </entry> + <entry> + Matches every <systemitem class="protocol">IP</systemitem> address. + </entry> + </row> + <row> + <entry> + <option>localhost</option> + </entry> + <entry> + Matches any <systemitem class="protocol">IP</systemitem> address that is in use by the local system. + </entry> + </row> + <row> + <entry> + <option>localnets</option> + </entry> + <entry> + Matches any <systemitem class="protocol">IP</systemitem> address on any network to which the local system is connected. + </entry> + </row> + <row> + <entry> + <option>none</option> + </entry> + <entry> + Does not match any <systemitem class="protocol">IP</systemitem> address. + </entry> + </row> + </tbody> + </tgroup> + </table> + <para> + The <option>acl</option> statement can be especially useful in conjunction with other statements such as <option>options</option>. <xref linkend="example-bind-namedconf-common-acl"/> defines two access control lists, <literal>black-hats</literal> and <literal>red-hats</literal>, and adds <literal>black-hats</literal> on the blacklist while granting <literal>red-hats</literal> normal access. + </para> + <example id="example-bind-namedconf-common-acl"> + <title>Using acl in Conjunction with Options</title> + <programlisting>acl black-hats { + 10.0.2.0/24; + 192.168.0.0/24; + 1234:5678::9abc/24; +}; +acl red-hats { + 10.0.1.0/24; +}; +options { + blackhole { black-hats; }; + allow-query { red-hats; }; + allow-query-cache { red-hats; }; +};</programlisting> + </example> + </listitem> + </varlistentry> + <varlistentry> + <term> + <indexterm> + <primary>BIND</primary> + <secondary>configuration</secondary> + <tertiary><option>include</option> statement</tertiary> + </indexterm> + <option>include</option> + </term> + <listitem> + <para> + The <option>include</option> statement allows you to include files in the <filename>/etc/named.conf</filename>, so that potentially sensitive data can be placed in a separate file with restricted permissions. It takes the following form: + </para> + <programlisting>include "<replaceable>file-name</replaceable>"</programlisting> + <para> + The <replaceable>file-name</replaceable> statement name is an absolute path to a file. + </para> + <example id="example-bind-namedconf-common-include"> + <title>Including a File to /etc/named.conf</title> + <programlisting>include "/etc/named.rfc1912.zones";</programlisting> + </example> + </listitem> + </varlistentry> + <varlistentry> + <term> + <indexterm> + <primary>BIND</primary> + <secondary>configuration</secondary> + <tertiary><option>options</option> statement</tertiary> + </indexterm> + <option>options</option> + </term> + <listitem> + <para> + The <option>options</option> statement allows you to define global server configuration options as well as to set defaults for other statements. It can be used to specify the location of the <systemitem class="service">named</systemitem> working directory, the types of queries allowed, and much more. It takes the following form: + </para> + <programlisting>options { + <replaceable>option</replaceable>; + ... +};</programlisting> + <para> + For a list of frequently used <replaceable>option</replaceable> directives, see <xref linkend="table-bind-namedconf-common-options" /> below. + </para> + <table id="table-bind-namedconf-common-options"> + <title>Commonly Used Configuration Options</title> + <tgroup cols="2"> + <colspec colname="option" colnum="1" colwidth="20*" /> + <colspec colname="description" colnum="2" colwidth="60*" /> + <thead> + <row> + <entry> + Option + </entry> + <entry> + Description + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <option>allow-query</option> + </entry> + <entry> + Specifies which hosts are allowed to query the nameserver for authoritative resource records. It accepts an access control list, a collection of <systemitem class="protocol">IP</systemitem> addresses, or networks in the CIDR notation. All hosts are allowed by default. + </entry> + </row> + <row> + <entry> + <option>allow-query-cache</option> + </entry> + <entry> + Specifies which hosts are allowed to query the nameserver for non-authoritative data such as recursive queries. Only <literal>localhost</literal> and <literal>localnets</literal> are allowed by default. + </entry> + </row> + <row> + <entry> + <option>blackhole</option> + </entry> + <entry> + Specifies which hosts are <emphasis>not</emphasis> allowed to query the nameserver. This option should be used when a particular host or network floods the server with requests. The default option is <literal>none</literal>. + </entry> + </row> + <row> + <entry> + <option>directory</option> + </entry> + <entry> + Specifies a working directory for the <systemitem class="service">named</systemitem> service. The default option is <literal>/var/named/</literal>. + </entry> + </row> + <row> + <entry> + <option>disable-empty-zone</option> + </entry> + <entry> + Used to disable one or more empty zones from the list of default prefixes that would be used. Can be specified in the options statement and also in view statements. It can be used multiple times. + </entry> + </row> + <row> + <entry> + <option>dnssec-enable</option> + </entry> + <entry> + Specifies whether to return DNSSEC related resource records. The default option is <literal>yes</literal>. + </entry> + </row> + <row> + <entry> + <option>dnssec-validation</option> + </entry> + <entry> + Specifies whether to prove that resource records are authentic via DNSSEC. The default option is <literal>yes</literal>. + </entry> + </row> + <row> + <entry> + <option>empty-zones-enable</option> + </entry> + <entry> + Controls whether or not empty zones are created. Can be specified only in the options statement. + </entry> + </row> + <row> + <entry> + <option>forwarders</option> + </entry> + <entry> + Specifies a list of valid <systemitem class="protocol">IP</systemitem> addresses for nameservers to which the requests should be forwarded for resolution. + </entry> + </row> + <row> + <entry> + <option>forward</option> + </entry> + <entry> + <para> + Specifies the behavior of the <option>forwarders</option> directive. It accepts the following options: + </para> + <itemizedlist> + <listitem> + <para><literal>first</literal> — The server will query the nameservers listed in the <option>forwarders</option> directive before attempting to resolve the name on its own. + </para> + </listitem> + <listitem> + <para><literal>only</literal> — When unable to query the nameservers listed in the <option>forwarders</option> directive, the server will not attempt to resolve the name on its own. + </para> + </listitem> + </itemizedlist> + </entry> + </row> + <row> + <entry> + <option>listen-on</option> + </entry> + <entry> + Specifies the <systemitem class="protocol">IPv4</systemitem> network interface on which to listen for queries. On a <systemitem class="protocol">DNS</systemitem> server that also acts as a gateway, you can use this option to answer queries originating from a single network only. All <systemitem class="protocol">IPv4</systemitem> interfaces are used by default. + </entry> + </row> + <row> + <entry> + <option>listen-on-v6</option> + </entry> + <entry> + Specifies the <systemitem class="protocol">IPv6</systemitem> network interface on which to listen for queries. On a <systemitem class="protocol">DNS</systemitem> server that also acts as a gateway, you can use this option to answer queries originating from a single network only. All <systemitem class="protocol">IPv6</systemitem> interfaces are used by default. + </entry> + </row> + <row> + <entry> + <option>max-cache-size</option> + </entry> + <entry> + Specifies the maximum amount of memory to be used for server caches. When the limit is reached, the server causes records to expire prematurely so that the limit is not exceeded. In a server with multiple views, the limit applies separately to the cache of each view. The default option is <literal>32M</literal>. + </entry> + </row> + <row> + <entry> + <option>notify</option> + </entry> + <entry> + <para> + Specifies whether to notify the secondary nameservers when a zone is updated. It accepts the following options: + </para> + <itemizedlist> + <listitem> + <para><literal>yes</literal> — The server will notify all secondary nameservers. + </para> + </listitem> + <listitem> + <para><literal>no</literal> — The server will <emphasis>not</emphasis> notify any secondary nameserver. + </para> + </listitem> + <listitem> + <para><literal>master-only</literal> — The server will notify primary server for the zone only. + </para> + </listitem> + <listitem> + <para><literal>explicit</literal> — The server will notify only the secondary servers that are specified in the <option>also-notify</option> list within a zone statement. + </para> + </listitem> + </itemizedlist> + </entry> + </row> + <row> + <entry> + <option>pid-file</option> + </entry> + <entry> + Specifies the location of the process ID file created by the <systemitem class="service">named</systemitem> service. + </entry> + </row> + <row> + <entry> + <option>recursion</option> + </entry> + <entry> + Specifies whether to act as a recursive server. The default option is <literal>yes</literal>. + </entry> + </row> + <row> + <entry> + <option>statistics-file</option> + </entry> + <entry> + Specifies an alternate location for statistics files. The <filename>/var/named/named.stats</filename> file is used by default. + </entry> + </row> + </tbody> + </tgroup> + </table> + + <note> + <para> + The directory used by <systemitem class="daemon">named</systemitem> for runtime data has been moved from the BIND default location, <filename class="directory">/var/run/named/</filename>, to a new location <filename class="directory">/run/named/</filename>. As a result, the PID file has been moved from the default location <filename>/var/run/named/named.pid</filename> to the new location <filename>/run/named/named.pid</filename>. In addition, the session-key file has been moved to <filename>/run/named/session.key</filename>. These locations need to be specified by statements in the options section. See <xref linkend="example-bind-namedconf-common-options" />. + </para> + </note> + <important> + <title>Restrict recursive servers to selected clients only</title> + <para> + To prevent distributed denial of service (DDoS) attacks, it is recommended that you use the <option>allow-query-cache</option> option to restrict recursive <systemitem class="protocol">DNS</systemitem> services for a particular subset of clients only. + </para> + </important> + <para> + Refer to the <citetitle>BIND 9 Administrator Reference Manual</citetitle> referenced in <xref linkend="sec-bind-installed-docs" />, and the <filename>named.conf</filename> manual page for a complete list of available options. + </para> + <example id="example-bind-namedconf-common-options"> + <title>Using the options Statement</title> + <programlisting>options { + allow-query { localhost; }; + listen-on port 53 { 127.0.0.1; }; + listen-on-v6 port 53 { ::1; }; + max-cache-size 256M; + directory "/var/named"; + statistics-file "/var/named/data/named_stats.txt"; + + recursion yes; + dnssec-enable yes; + dnssec-validation yes; + + pid-file "/run/named/named.pid"; + session-keyfile "/run/named/session.key"; +};</programlisting> + </example> + </listitem> + </varlistentry> + <varlistentry> + <term> + <indexterm> + <primary>BIND</primary> + <secondary>configuration</secondary> + <tertiary><option>zone</option> statement</tertiary> + </indexterm> + <option>zone</option> + </term> + <listitem> + <para> + The <option>zone</option> statement allows you to define the characteristics of a zone, such as the location of its configuration file and zone-specific options, and can be used to override the global <option>options</option> statements. It takes the following form: + </para> + <programlisting>zone <replaceable>zone-name</replaceable> [<replaceable>zone-class</replaceable>] { + <replaceable>option</replaceable>; + ... +};</programlisting> + <para> + The <replaceable>zone-name</replaceable> attribute is the name of the zone, <replaceable>zone-class</replaceable> is the optional class of the zone, and <replaceable>option</replaceable> is a <option>zone</option> statement option as described in <xref linkend="table-bind-namedconf-common-zone" />. + </para> + <para> + The <replaceable>zone-name</replaceable> attribute is particularly important, as it is the default value assigned for the <option>$ORIGIN</option> directive used within the corresponding zone file located in the <filename>/var/named/</filename> directory. The <systemitem class="service">named</systemitem> daemon appends the name of the zone to any non-fully qualified domain name listed in the zone file. For example, if a <option>zone</option> statement defines the namespace for <literal>example.com</literal>, use <literal>example.com</literal> as the <replaceable>zone-name</replaceable> so that it is placed at the end of host names within the <literal>example.com</literal> zone file. + </para> + <para> + For more information about zone files, refer to <xref linkend="sec-bind-zone" />. + </para> + <table id="table-bind-namedconf-common-zone"> + <title>Commonly Used Options in Zone Statements</title> + <tgroup cols="2"> + <colspec colname="option" colnum="1" colwidth="20*" /> + <colspec colname="description" colnum="2" colwidth="60*" /> + <thead> + <row> + <entry> + Option + </entry> + <entry> + Description + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <option>allow-query</option> + </entry> + <entry> + Specifies which clients are allowed to request information about this zone. This option overrides global <option>allow-query</option> option. All query requests are allowed by default. + </entry> + </row> + <row> + <entry> + <option>allow-transfer</option> + </entry> + <entry> + Specifies which secondary servers are allowed to request a transfer of the zone's information. All transfer requests are allowed by default. + </entry> + </row> + <row> + <entry> + <option>allow-update</option> + </entry> + <entry> + <para> + Specifies which hosts are allowed to dynamically update information in their zone. The default option is to deny all dynamic update requests. + </para> + <para> + Note that you should be careful when allowing hosts to update information about their zone. Do not set <systemitem class="protocol">IP</systemitem> addresses in this option unless the server is in the trusted network. Instead, use TSIG key as described in <xref linkend="sec-bind-features-tsig" />. + </para> + </entry> + </row> + <row> + <entry> + <option>file</option> + </entry> + <entry> + Specifies the name of the file in the <systemitem class="service">named</systemitem> working directory that contains the zone's configuration data. + </entry> + </row> + <row> + <entry> + <option>masters</option> + </entry> + <entry> + Specifies from which <systemitem class="protocol">IP</systemitem> addresses to request authoritative zone information. This option is used only if the zone is defined as <option>type</option> <option>slave</option>. + </entry> + </row> + <row> + <entry> + <option>notify</option> + </entry> + <entry> + <para> + Specifies whether to notify the secondary nameservers when a zone is updated. It accepts the following options: + </para> + <itemizedlist> + <listitem> + <para><option>yes</option> — The server will notify all secondary nameservers. + </para> + </listitem> + <listitem> + <para><option>no</option> — The server will <emphasis>not</emphasis> notify any secondary nameserver. + </para> + </listitem> + <listitem> + <para><option>master-only</option> — The server will notify primary server for the zone only. + </para> + </listitem> + <listitem> + <para><option>explicit</option> — The server will notify only the secondary servers that are specified in the <option>also-notify</option> list within a zone statement. + </para> + </listitem> + </itemizedlist> + </entry> + </row> + <row> + <entry> + <option>type</option> + </entry> + <entry> + <para> + Specifies the zone type. It accepts the following options: + </para> + <itemizedlist> + <listitem> + <para><option>delegation-only</option> — Enforces the delegation status of infrastructure zones such as COM, NET, or ORG. Any answer that is received without an explicit or implicit delegation is treated as <literal>NXDOMAIN</literal>. This option is only applicable in TLDs (Top-Level Domain) or root zone files used in recursive or caching implementations. + </para> + </listitem> + <listitem> + <para><option>forward</option> — Forwards all requests for information about this zone to other nameservers. + </para> + </listitem> + <listitem> + <para><option>hint</option> — A special type of zone used to point to the root nameservers which resolve queries when a zone is not otherwise known. No configuration beyond the default is necessary with a <option>hint</option> zone. + </para> + </listitem> + <listitem> + <para><option>master</option> — Designates the nameserver as authoritative for this zone. A zone should be set as the <option>master</option> if the zone's configuration files reside on the system. + </para> + </listitem> + <listitem> + <para><option>slave</option> — Designates the nameserver as a slave server for this zone. Master server is specified in <option>masters</option> directive. + </para> + </listitem> + </itemizedlist> + </entry> + </row> + </tbody> + </tgroup> + </table> + <para> + Most changes to the <filename>/etc/named.conf</filename> file of a primary or secondary nameserver involve adding, modifying, or deleting <option>zone</option> statements, and only a small subset of <option>zone</option> statement options is usually needed for a nameserver to work efficiently. + </para> + <para> + In <xref linkend="example-bind-namedconf-common-zone-primary" />, the zone is identified as <literal>example.com</literal>, the type is set to <literal>master</literal>, and the <systemitem class="service">named</systemitem> service is instructed to read the <filename>/var/named/example.com.zone</filename> file. It also allows only a secondary nameserver (<literal>192.168.0.2</literal>) to transfer the zone. + </para> + <example id="example-bind-namedconf-common-zone-primary"> + <title>A Zone Statement for a Primary nameserver</title> + <programlisting>zone "example.com" IN { + type master; + file "example.com.zone"; + allow-transfer { 192.168.0.2; }; +};</programlisting> + </example> + <para> + A secondary server's <option>zone</option> statement is slightly different. The type is set to <literal>slave</literal>, and the <literal>masters</literal> directive is telling <systemitem class="service">named</systemitem> the <systemitem class="protocol">IP</systemitem> address of the master server. + </para> + <para> + In <xref linkend="example-bind-namedconf-common-zone-secondary" />, the <systemitem class="service">named</systemitem> service is configured to query the primary server at the <literal>192.168.0.1</literal> <systemitem class="protocol">IP</systemitem> address for information about the <literal>example.com</literal> zone. The received information is then saved to the <filename>/var/named/slaves/example.com.zone</filename> file. Note that you have to put all slave zones in the <filename class="directory">/var/named/slaves/</filename> directory, otherwise the service will fail to transfer the zone. + </para> + <example id="example-bind-namedconf-common-zone-secondary"> + <title>A Zone Statement for a Secondary nameserver</title> + <programlisting>zone "example.com" { + type slave; + file "slaves/example.com.zone"; + masters { 192.168.0.1; }; +};</programlisting> + </example> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="sec-bind-namedconf-state-other"> + <title>Other Statement Types</title> + <para> + The following types of statements are less commonly used in <filename>/etc/named.conf</filename>: + </para> + <variablelist> + <varlistentry> + <term> + <indexterm> + <primary>BIND</primary> + <secondary>configuration</secondary> + <tertiary><option>controls</option> statement</tertiary> + </indexterm> + <option>controls</option> + </term> + <listitem> + <para> + The <option>controls</option> statement allows you to configure various security requirements necessary to use the <command>rndc</command> command to administer the <systemitem class="service">named</systemitem> service. + </para> + <para> + Refer to <xref linkend="sec-bind-rndc" /> for more information on the <command>rndc</command> utility and its usage. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <indexterm> + <primary>BIND</primary> + <secondary>configuration</secondary> + <tertiary><option>key</option> statement</tertiary> + </indexterm> + <option>key</option> + </term> + <listitem> + <para> + The <option>key</option> statement allows you to define a particular key by name. Keys are used to authenticate various actions, such as secure updates or the use of the <command>rndc</command> command. Two options are used with <option>key</option>: + </para> + <itemizedlist> + <listitem> + <para><option>algorithm <replaceable>algorithm-name</replaceable></option> — The type of algorithm to be used (for example, <literal>hmac-md5</literal>). + </para> + </listitem> + <listitem> + <para><option>secret "<replaceable>key-value</replaceable>"</option> — The encrypted key. + </para> + </listitem> + </itemizedlist> + <para> + Refer to <xref linkend="sec-bind-rndc" /> for more information on the <command>rndc</command> utility and its usage. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <indexterm> + <primary>BIND</primary> + <secondary>configuration</secondary> + <tertiary><option>logging</option> statement</tertiary> + </indexterm> + <option>logging</option> + </term> + <listitem> + <para> + The <option>logging</option> statement allows you to use multiple types of logs, so called <firstterm>channels</firstterm>. By using the <option>channel</option> option within the statement, you can construct a customized type of log with its own file name (<option>file</option>), size limit (<option>size</option>), version number (<option>version</option>), and level of importance (<option>severity</option>). Once a customized channel is defined, a <option>category</option> option is used to categorize the channel and begin logging when the <systemitem class="service">named</systemitem> service is restarted. + </para> + <para> + By default, <systemitem class="service">named</systemitem> sends standard messages to the <systemitem class="service">rsyslog</systemitem> daemon, which places them in <filename>/var/log/messages</filename>. Several standard channels are built into BIND with various severity levels, such as <literal>default_syslog</literal> (which handles informational logging messages) and <literal>default_debug</literal> (which specifically handles debugging messages). A default category, called <literal>default</literal>, uses the built-in channels to do normal logging without any special configuration. + </para> + <para> + Customizing the logging process can be a very detailed process and is beyond the scope of this chapter. For information on creating custom BIND logs, refer to the <citetitle>BIND 9 Administrator Reference Manual</citetitle> referenced in <xref linkend="sec-bind-installed-docs"/>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <indexterm> + <primary>BIND</primary> + <secondary>configuration</secondary> + <tertiary><option>server</option> statement</tertiary> + </indexterm> + <option>server</option> + </term> + <listitem> + <para> + The <option>server</option> statement allows you to specify options that affect how the <systemitem class="service">named</systemitem> service should respond to remote nameservers, especially with regard to notifications and zone transfers. + </para> + <para> + The <option>transfer-format</option> option controls the number of resource records that are sent with each message. It can be either <literal>one-answer</literal> (only one resource record), or <literal>many-answers</literal> (multiple resource records). Note that while the <literal>many-answers</literal> option is more efficient, it is not supported by older versions of BIND. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <indexterm> + <primary>BIND</primary> + <secondary>configuration</secondary> + <tertiary><option>trusted-keys</option> statement</tertiary> + </indexterm> + <option>trusted-keys</option> + </term> + <listitem> + <para> + The <option>trusted-keys</option> statement allows you to specify assorted public keys used for secure <systemitem class="protocol">DNS</systemitem> (DNSSEC). Refer to <xref linkend="sec-bind-features-dnssec" /> for more information on this topic. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <indexterm> + <primary>BIND</primary> + <secondary>configuration</secondary> + <tertiary><option>view</option> statement</tertiary> + </indexterm> + <option>view</option> + </term> + <listitem> + <para> + The <option>view</option> statement allows you to create special views depending upon which network the host querying the nameserver is on. This allows some hosts to receive one answer regarding a zone while other hosts receive totally different information. Alternatively, certain zones may only be made available to particular trusted hosts while non-trusted hosts can only make queries for other zones. + </para> + <para> + Multiple views can be used as long as their names are unique. The <option>match-clients</option> option allows you to specify the <systemitem class="protocol">IP</systemitem> addresses that apply to a particular view. If the <option>options</option> statement is used within a view, it overrides the already configured global options. Finally, most <option>view</option> statements contain multiple <option>zone</option> statements that apply to the <option>match-clients</option> list. + </para> + <para> + Note that the order in which the <option>view</option> statements are listed is important, as the first statement that matches a particular client's <systemitem class="protocol">IP</systemitem> address is used. For more information on this topic, refer to <xref linkend="sec-bind-features-views"/>. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="sec-bind-namedconf-comm"> + <title>Comment Tags</title> + <indexterm> + <primary>BIND</primary> + <secondary>configuration</secondary> + <tertiary>comment tags</tertiary> + </indexterm> + <para> + Additionally to statements, the <filename>/etc/named.conf</filename> file can also contain comments. Comments are ignored by the <systemitem class="service">named</systemitem> service, but can prove useful when providing additional information to a user. The following are valid comment tags: + </para> + <variablelist> + <varlistentry> + <term> + <literal>//</literal> + </term> + <listitem> + <para> + Any text after the <literal>//</literal> characters to the end of the line is considered a comment. For example: + </para> + <programlisting>notify yes; // notify all secondary nameservers</programlisting> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>#</literal> + </term> + <listitem> + <para> + Any text after the <literal>#</literal> character to the end of the line is considered a comment. For example: + </para> + <programlisting>notify yes; # notify all secondary nameservers</programlisting> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>/*</literal> and <literal>*/</literal></term> + <listitem> + <para> + Any block of text enclosed in <literal>/*</literal> and <literal>*/</literal> is considered a comment. For example: + </para> + <programlisting>notify yes; /* notify all secondary nameservers */</programlisting> + </listitem> + </varlistentry> + </variablelist> + </section> + </section> + <section id="sec-bind-zone"> + <title>Editing Zone Files</title> + <indexterm> + <primary>BIND</primary> + <secondary>directories</secondary> + <tertiary><filename class="directory">/var/named/</filename></tertiary> + </indexterm> + <indexterm> + <primary>BIND</primary> + <secondary>directories</secondary> + <tertiary><filename class="directory">/var/named/slaves/</filename></tertiary> + </indexterm> + <indexterm> + <primary>BIND</primary> + <secondary>directories</secondary> + <tertiary><filename class="directory">/var/named/dynamic/</filename></tertiary> + </indexterm> + <indexterm> + <primary>BIND</primary> + <secondary>directories</secondary> + <tertiary><filename class="directory">/var/named/data/</filename></tertiary> + </indexterm> + <para> + As outlined in <xref linkend="sec-dns-introduction-zones" />, zone files contain information about a namespace. They are stored in the <systemitem class="service">named</systemitem> working directory located in <filename class="directory">/var/named/</filename> by default. Each zone file is named according to the <option>file</option> option in the <option>zone</option> statement, usually in a way that relates to the domain in and identifies the file as containing zone data, such as <filename>example.com.zone</filename>. + </para> + <table id="table-bind-zone-files"> + <title>The named Service Zone Files</title> + <tgroup cols="2"> + <thead> + <row> + <entry> + Path + </entry> + <entry> + Description + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <filename class="directory">/var/named/</filename> + </entry> + <entry> + The working directory for the <systemitem class="service">named</systemitem> service. The nameserver is <emphasis>not</emphasis> allowed to write to this directory. + </entry> + </row> + <row> + <entry> + <filename class="directory">/var/named/slaves/</filename> + </entry> + <entry> + The directory for secondary zones. This directory is writable by the <systemitem class="service">named</systemitem> service. + </entry> + </row> + <row> + <entry> + <filename class="directory">/var/named/dynamic/</filename> + </entry> + <entry> + The directory for other files, such as dynamic <systemitem class="protocol">DNS</systemitem> (DDNS) zones or managed DNSSEC keys. This directory is writable by the <systemitem class="service">named</systemitem> service. + + </entry> + </row> + <row> + <entry> + <filename class="directory">/var/named/data/</filename> + </entry> + <entry> + The directory for various statistics and debugging files. This directory is writable by the <systemitem class="service">named</systemitem> service. + </entry> + </row> + </tbody> + </tgroup> + </table> + <para> + A zone file consists of directives and resource records. Directives tell the nameserver to perform tasks or apply special settings to the zone, resource records define the parameters of the zone and assign identities to individual hosts. While the directives are optional, the resource records are required in order to provide name service to a zone. + </para> + <para> + All directives and resource records should be entered on individual lines. + </para> + <section id="sec-bind-zone-directives"> + <title>Common Directives</title> + <para> + Directives begin with the dollar sign character (<literal>$</literal>) followed by the name of the directive, and usually appear at the top of the file. The following directives are commonly used in zone files: + </para> + <variablelist> + <varlistentry> + <term> + <indexterm> + <primary>BIND</primary> + <secondary>zones</secondary> + <tertiary><command>$INCLUDE</command> directive</tertiary> + </indexterm> + <command>$INCLUDE</command> + </term> + <listitem> + <para> + The <command>$INCLUDE</command> directive allows you to include another file at the place where it appears, so that other zone settings can be stored in a separate zone file. + </para> + <example id="example-bind-zone-directive-include"> + <title>Using the $INCLUDE Directive</title> + <programlisting>$INCLUDE /var/named/penguin.example.com</programlisting> + </example> + </listitem> + </varlistentry> + <varlistentry> + <term> + <indexterm> + <primary>BIND</primary> + <secondary>zones</secondary> + <tertiary><command>$ORIGIN</command> directive</tertiary> + </indexterm> + <command>$ORIGIN</command> + </term> + <listitem> + <para> + The <command>$ORIGIN</command> directive allows you to append the domain name to unqualified records, such as those with the host name only. Note that the use of this directive is not necessary if the zone is specified in <filename>/etc/named.conf</filename>, since the zone name is used by default. + </para> + <para> + In <xref linkend="example-bind-zone-directive-origin" />, any names used in resource records that do not end in a trailing period (the <literal>.</literal> character) are appended with <literal>example.com</literal>. + </para> + <example id="example-bind-zone-directive-origin"> + <title>Using the $ORIGIN Directive</title> + <programlisting>$ORIGIN example.com.</programlisting> + </example> + </listitem> + </varlistentry> + <varlistentry> + <term> + <indexterm> + <primary>BIND</primary> + <secondary>zones</secondary> + <tertiary><command>$TTL</command> directive</tertiary> + </indexterm> + <command>$TTL</command> + </term> + <listitem> + <para> + The <command>$TTL</command> directive allows you to set the default <firstterm>Time to Live</firstterm> (TTL) value for the zone, that is, how long is a zone record valid. Each resource record can contain its own TTL value, which overrides this directive. + </para> + <para> + Increasing this value allows remote nameservers to cache the zone information for a longer period of time, reducing the number of queries for the zone and lengthening the amount of time required to propagate resource record changes. + </para> + <example id="example-bind-zone-directive-ttl"> + <title>Using the $TTL Directive</title> + <programlisting>$TTL 1D</programlisting> + </example> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="sec-bind-zone-rr"> + <title>Common Resource Records</title> + <para> + The following resource records are commonly used in zone files: + </para> + <variablelist> + <varlistentry> + <term> + <indexterm> + <primary>BIND</primary> + <secondary>zones</secondary> + <tertiary><command>A</command> (Address) resource record</tertiary> + </indexterm> + <command>A</command> + </term> + <listitem> + <para> + The <firstterm>Address</firstterm> record specifies an <systemitem class="protocol">IP</systemitem> address to be assigned to a name. It takes the following form: + </para> + <programlisting><replaceable>hostname</replaceable> IN A <replaceable>IP-address</replaceable></programlisting> + <para> + If the <replaceable>hostname</replaceable> value is omitted, the record will point to the last specified <replaceable>hostname</replaceable>. + </para> + <para> + In <xref linkend="example-bind-zone-rr-a" />, the requests for <systemitem class="domainname">server1.example.com</systemitem> are pointed to <literal>10.0.1.3</literal> or <literal>10.0.1.5</literal>. + </para> + <example id="example-bind-zone-rr-a"> + <title>Using the A Resource Record</title> + <programlisting>server1 IN A 10.0.1.3 + IN A 10.0.1.5</programlisting> + </example> + </listitem> + </varlistentry> + <varlistentry> + <term> + <indexterm> + <primary>BIND</primary> + <secondary>zones</secondary> + <tertiary><command>CNAME</command> (Canonical Name) resource record</tertiary> + </indexterm> + <command>CNAME</command> + </term> + <listitem> + <para> + The <firstterm>Canonical Name</firstterm> record maps one name to another. Because of this, this type of record is sometimes referred to as an <firstterm>alias record</firstterm>. It takes the following form: + </para> + <programlisting><replaceable>alias-name</replaceable> IN CNAME <replaceable>real-name</replaceable></programlisting> + <para> + <command>CNAME</command> records are most commonly used to point to services that use a common naming scheme, such as <literal>www</literal> for Web servers. However, there are multiple restrictions for their usage: + </para> + <itemizedlist> + <listitem> + <para> + CNAME records should not point to other CNAME records. This is mainly to avoid possible infinite loops. + </para> + </listitem> + <listitem> + <para> + CNAME records should not contain other resource record types (such as A, NS, MX, etc.). The only exception are DNSSEC related records (RRSIG, NSEC, etc.) when the zone is signed. + </para> + </listitem> + <listitem> + <para> + Other resource records that point to the fully qualified domain name (FQDN) of a host (NS, MX, PTR) should not point to a CNAME record. + </para> + </listitem> + </itemizedlist> + <para> + In <xref linkend="example-bind-zone-rr-cname" />, the <command>A</command> record binds a host name to an <systemitem class="protocol">IP</systemitem> address, while the <command>CNAME</command> record points the commonly used <literal>www</literal> host name to it. + </para> + <example id="example-bind-zone-rr-cname"> + <title>Using the CNAME Resource Record</title> + <programlisting>server1 IN A 10.0.1.5 +www IN CNAME server1</programlisting> + </example> + </listitem> + </varlistentry> + <varlistentry> + <term> + <indexterm> + <primary>BIND</primary> + <secondary>zones</secondary> + <tertiary><command>MX</command> (Mail Exchange) resource record</tertiary> + </indexterm> + <command>MX</command> + </term> + <listitem> + <para> + The <firstterm>Mail Exchange</firstterm> record specifies where the mail sent to a particular namespace controlled by this zone should go. It takes the following form: + </para> + <programlisting>IN MX <replaceable>preference-value</replaceable> <replaceable>email-server-name</replaceable></programlisting> + <para> + The <replaceable>email-server-name</replaceable> is a fully qualified domain name (FQDN). The <replaceable>preference-value</replaceable> allows numerical ranking of the email servers for a namespace, giving preference to some email systems over others. The <command>MX</command> resource record with the lowest <replaceable>preference-value</replaceable> is preferred over the others. However, multiple email servers can possess the same value to distribute email traffic evenly among them. + </para> + <para> + In <xref linkend="example-bind-zone-rr-mx" />, the first <systemitem class="domainname">mail.example.com</systemitem> email server is preferred to the <systemitem class="domainname">mail2.example.com</systemitem> email server when receiving email destined for the <systemitem class="domainname">example.com</systemitem> domain. + + </para> + <example id="example-bind-zone-rr-mx"> + <title>Using the MX Resource Record</title> + <programlisting>example.com. IN MX 10 mail.example.com. + IN MX 20 mail2.example.com.</programlisting> + </example> + </listitem> + </varlistentry> + <varlistentry> + <term> + <indexterm> + <primary>BIND</primary> + <secondary>zones</secondary> + <tertiary><command>NS</command> (Nameserver) resource record</tertiary> + </indexterm> + <command>NS</command> + </term> + <listitem> + <para> + The <firstterm>Nameserver</firstterm> record announces authoritative nameservers for a particular zone. It takes the following form: + </para> + <programlisting>IN NS <replaceable>nameserver-name</replaceable></programlisting> + <para> + The <replaceable>nameserver-name</replaceable> should be a fully qualified domain name (FQDN). Note that when two nameservers are listed as authoritative for the domain, it is not important whether these nameservers are secondary nameservers, or if one of them is a primary server. They are both still considered authoritative. + </para> + <example id="example-bind-zone-rr-ns"> + <title>Using the NS Resource Record</title> + <programlisting>IN NS dns1.example.com. +IN NS dns2.example.com.</programlisting> + </example> + </listitem> + </varlistentry> + <varlistentry> + <term> + <indexterm> + <primary>BIND</primary> + <secondary>zones</secondary> + <tertiary><command>PTR</command> (Pointer) resource record</tertiary> + </indexterm> + <command>PTR</command> + </term> + <listitem> + <para> + The <firstterm>Pointer</firstterm> record points to another part of the namespace. It takes the following form: + </para> + <programlisting><replaceable>last-IP-digit</replaceable> IN PTR <replaceable>FQDN-of-system</replaceable></programlisting> + <para> + The <replaceable>last-IP-digit</replaceable> directive is the last number in an <systemitem class="protocol">IP</systemitem> address, and the <replaceable>FQDN-of-system</replaceable> is a fully qualified domain name (FQDN). + </para> + <para> + <command>PTR</command> records are primarily used for reverse name resolution, as they point <systemitem class="protocol">IP</systemitem> addresses back to a particular name. Refer to <xref linkend="sec-bind-configuration-zone-reverse" /> for examples of <command>PTR</command> records in use. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <indexterm> + <primary>BIND</primary> + <secondary>zones</secondary> + <tertiary><command>SOA</command> (Start of Authority) resource record</tertiary> + </indexterm> + <command>SOA</command> + </term> + <listitem> + <para> + The <firstterm>Start of Authority</firstterm> record announces important authoritative information about a namespace to the nameserver. Located after the directives, it is the first resource record in a zone file. It takes the following form: + </para> + <programlisting>@ IN SOA <replaceable>primary-name-server</replaceable> <replaceable>hostmaster-email</replaceable> ( + <replaceable>serial-number</replaceable> + <replaceable>time-to-refresh</replaceable> + <replaceable>time-to-retry</replaceable> + <replaceable>time-to-expire</replaceable> + <replaceable>minimum-TTL</replaceable> )</programlisting> + <para> + The directives are as follows: + </para> + <itemizedlist> + <listitem> + <para> + The <literal>@</literal> symbol places the <command>$ORIGIN</command> directive (or the zone's name if the <command>$ORIGIN</command> directive is not set) as the namespace being defined by this <command>SOA</command> resource record. + </para> + </listitem> + <listitem> + <para> + The <replaceable>primary-name-server</replaceable> directive is the host name of the primary nameserver that is authoritative for this domain. + </para> + </listitem> + <listitem> + <para> + The <replaceable>hostmaster-email</replaceable> directive is the email of the person to contact about the namespace. + </para> + </listitem> + <listitem> + <para> + The <replaceable>serial-number</replaceable> directive is a numerical value incremented every time the zone file is altered to indicate it is time for the <systemitem class="service">named</systemitem> service to reload the zone. + </para> + </listitem> + <listitem> + <para> + The <replaceable>time-to-refresh</replaceable> directive is the numerical value secondary nameservers use to determine how long to wait before asking the primary nameserver if any changes have been made to the zone. + </para> + </listitem> + <listitem> + <para> + The <replaceable>time-to-retry</replaceable> directive is a numerical value used by secondary nameservers to determine the length of time to wait before issuing a refresh request in the event that the primary nameserver is not answering. If the primary server has not replied to a refresh request before the amount of time specified in the <replaceable>time-to-expire</replaceable> directive elapses, the secondary servers stop responding as an authority for requests concerning that namespace. + </para> + </listitem> + <listitem> + <para> + In BIND 4 and 8, the <replaceable>minimum-TTL</replaceable> directive is the amount of time other nameservers cache the zone's information. In BIND 9, it defines how long negative answers are cached for. Caching of negative answers can be set to a maximum of 3 hours (<option>3H</option>). + </para> + </listitem> + </itemizedlist> + <para> + When configuring BIND, all times are specified in seconds. However, it is possible to use abbreviations when specifying units of time other than seconds, such as minutes (<literal>M</literal>), hours (<literal>H</literal>), days (<literal>D</literal>), and weeks (<literal>W</literal>). <xref linkend="tb-bind-seconds" /> shows an amount of time in seconds and the equivalent time in another format. + </para> + <table id="tb-bind-seconds"> + <title>Seconds compared to other time units</title> + <tgroup cols="2"> + <colspec colname="seconds" colnum="1" colwidth="50*" /> + <colspec colname="other" colnum="2" colwidth="50*" /> + <thead> + <row> + <entry> + Seconds + </entry> + <entry> + Other Time Units + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + 60 + </entry> + <entry> + <literal>1M</literal> + </entry> + </row> + <row> + <entry> + 1800 + </entry> + <entry> + <literal>30M</literal> + </entry> + </row> + <row> + <entry> + 3600 + </entry> + <entry> + <literal>1H</literal> + </entry> + </row> + <row> + <entry> + 10800 + </entry> + <entry> + <literal>3H</literal> + </entry> + </row> + <row> + <entry> + 21600 + </entry> + <entry> + <literal>6H</literal> + </entry> + </row> + <row> + <entry> + 43200 + </entry> + <entry> + <literal>12H</literal> + </entry> + </row> + <row> + <entry> + 86400 + </entry> + <entry> + <literal>1D</literal> + </entry> + </row> + <row> + <entry> + 259200 + </entry> + <entry> + <literal>3D</literal> + </entry> + </row> + <row> + <entry> + 604800 + </entry> + <entry> + <literal>1W</literal> + </entry> + </row> + <row> + <entry> + 31536000 + </entry> + <entry> + <literal>365D</literal> + </entry> + </row> + </tbody> + </tgroup> + </table> + <example id="example-bind-zone-rr-soa"> + <title>Using the SOA Resource Record</title> + <programlisting>@ IN SOA dns1.example.com. hostmaster.example.com. ( + 2001062501 ; serial + 21600 ; refresh after 6 hours + 3600 ; retry after 1 hour + 604800 ; expire after 1 week + 86400 ) ; minimum TTL of 1 day</programlisting> + </example> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="sec-bind-zone-comm"> + <title>Comment Tags</title> + <indexterm> + <primary>BIND</primary> + <secondary>zones</secondary> + <tertiary>comment tags</tertiary> + </indexterm> + <para> + Additionally to resource records and directives, a zone file can also contain comments. Comments are ignored by the <systemitem class="service">named</systemitem> service, but can prove useful when providing additional information to the user. Any text after the semicolon character (<literal>;</literal>) to the end of the line is considered a comment. For example: + </para> + <programlisting> 604800 ; expire after 1 week</programlisting> + </section> + <section id="sec-bind-zone-examples"> + <title>Example Usage</title> + <para> + The following examples show the basic usage of zone files. + </para> + <section id="sec-bind-zone-examples-basic"> + <title>A Simple Zone File</title> + <indexterm> + <primary>BIND</primary> + <secondary>zones</secondary> + <tertiary>example usage</tertiary> + </indexterm> + <para> + <xref linkend="example-bind-zone-examples-basic" /> demonstrates the use of standard directives and <command>SOA</command> values. + </para> + <example id="example-bind-zone-examples-basic"> + <title>A simple zone file</title> + <programlisting>$ORIGIN example.com. +$TTL 86400 +@ IN SOA dns1.example.com. hostmaster.example.com. ( + 2001062501 ; serial + 21600 ; refresh after 6 hours + 3600 ; retry after 1 hour + 604800 ; expire after 1 week + 86400 ) ; minimum TTL of 1 day +; +; + IN NS dns1.example.com. + IN NS dns2.example.com. +dns1 IN A 10.0.1.1 + IN AAAA aaaa:bbbb::1 +dns2 IN A 10.0.1.2 + IN AAAA aaaa:bbbb::2 +; +; +@ IN MX 10 mail.example.com. + IN MX 20 mail2.example.com. +mail IN A 10.0.1.5 + IN AAAA aaaa:bbbb::5 +mail2 IN A 10.0.1.6 + IN AAAA aaaa:bbbb::6 +; +; +; This sample zone file illustrates sharing the same IP addresses +; for multiple services: +; +services IN A 10.0.1.10 + IN AAAA aaaa:bbbb::10 + IN A 10.0.1.11 + IN AAAA aaaa:bbbb::11 + +ftp IN CNAME services.example.com. +www IN CNAME services.example.com. +; +;</programlisting> + </example> + <para> + In this example, the authoritative nameservers are set as <systemitem class="domainname">dns1.example.com</systemitem> and <systemitem class="domainname">dns2.example.com</systemitem>, and are tied to the <systemitem class="ipaddress">10.0.1.1</systemitem> and <systemitem class="ipaddress">10.0.1.2</systemitem> <systemitem class="protocol">IP</systemitem> addresses respectively using the <command>A</command> record. + </para> + <para> + The email servers configured with the <command>MX</command> records point to <systemitem class="domainname">mail</systemitem> and <systemitem class="domainname">mail2</systemitem> via <command>A</command> records. Since these names do not end in a trailing period (<literal>.</literal> character), the <command>$ORIGIN</command> domain is placed after them, expanding them to <systemitem class="domainname">mail.example.com</systemitem> and <systemitem class="domainname">mail2.example.com</systemitem>. + </para> + <para> + Services available at the standard names, such as <systemitem class="domainname">www.example.com</systemitem> (<acronym>WWW</acronym>), are pointed at the appropriate servers using the <command>CNAME</command> record. + </para> + <para> + This zone file would be called into service with a <command>zone</command> statement in the <filename>/etc/named.conf</filename> similar to the following: + </para> + <programlisting>zone "example.com" IN { + type master; + file "example.com.zone"; + allow-update { none; }; +};</programlisting> + </section> + <section id="sec-bind-configuration-zone-reverse"> + <title>A Reverse Name Resolution Zone File</title> + <indexterm> + <primary>BIND</primary> + <secondary>zones</secondary> + <tertiary>example usage</tertiary> + </indexterm> + <para> + A reverse name resolution zone file is used to translate an <systemitem class="protocol">IP</systemitem> address in a particular namespace into a fully qualified domain name (FQDN). It looks very similar to a standard zone file, except that the <command>PTR</command> resource records are used to link the <systemitem class="protocol">IP</systemitem> addresses to a fully qualified domain name as shown in <xref linkend="example-bind-zone-examples-reverse" />. + </para> + <example id="example-bind-zone-examples-reverse"> + <title>A reverse name resolution zone file</title> + <programlisting>$ORIGIN 1.0.10.in-addr.arpa. +$TTL 86400 +@ IN SOA dns1.example.com. hostmaster.example.com. ( + 2001062501 ; serial + 21600 ; refresh after 6 hours + 3600 ; retry after 1 hour + 604800 ; expire after 1 week + 86400 ) ; minimum TTL of 1 day +; +@ IN NS dns1.example.com. +; +1 IN PTR dns1.example.com. +2 IN PTR dns2.example.com. +; +5 IN PTR server1.example.com. +6 IN PTR server2.example.com. +; +3 IN PTR ftp.example.com. +4 IN PTR ftp.example.com.</programlisting> + </example> + <para> + In this example, <systemitem class="protocol">IP</systemitem> addresses <systemitem class="ipaddress">10.0.1.1</systemitem> through <systemitem class="ipaddress">10.0.1.6</systemitem> are pointed to the corresponding fully qualified domain name. + </para> + <para> + This zone file would be called into service with a <option>zone</option> statement in the <filename>/etc/named.conf</filename> file similar to the following: + </para> + <programlisting>zone "1.0.10.in-addr.arpa" IN { + type master; + file "example.com.rr.zone"; + allow-update { none; }; +};</programlisting> + <para> + There is very little difference between this example and a standard <command>zone</command> statement, except for the zone name. Note that a reverse name resolution zone requires the first three blocks of the <systemitem class="protocol">IP</systemitem> address reversed followed by <command>.in-addr.arpa</command>. This allows the single block of <systemitem class="protocol">IP</systemitem> numbers used in the reverse name resolution zone file to be associated with the zone. + </para> + </section> + </section> + </section> + <section id="sec-bind-rndc"> + <title>Using the rndc Utility</title> + <indexterm significance="preferred"> + <primary>BIND</primary> + <secondary>utilities</secondary> + <tertiary><command>rndc</command></tertiary> + </indexterm> + <para> + The <command>rndc</command> utility is a command-line tool that allows you to administer the <systemitem class="service">named</systemitem> service, both locally and from a remote machine. Its usage is as follows: + </para> + <screen><command>rndc</command> [<replaceable>option</replaceable>...] <replaceable>command</replaceable> [<replaceable>command-option</replaceable>]</screen> + <section id="sec-bind-rndc-configuration"> + <title>Configuring the Utility</title> + <para> + To prevent unauthorized access to the service, <systemitem class="service">named</systemitem> must be configured to listen on the selected port (<literal>953</literal> by default), and an identical key must be used by both the service and the <command>rndc</command> utility. + </para> + <table id="table-bind-rndc-configuration-files "> + <title>Relevant files</title> + <tgroup cols="2"> + <colspec colname="path" colnum="1" colwidth="30*" /> + <colspec colname="description" colnum="2" colwidth="50*" /> + <thead> + <row> + <entry> + Path + </entry> + <entry> + Description + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <indexterm> + <primary>BIND</primary> + <secondary>files</secondary> + <tertiary><filename>/etc/named.conf</filename></tertiary> + </indexterm> + <filename>/etc/named.conf</filename> + </entry> + <entry> + The default configuration file for the <systemitem class="service">named</systemitem> service. + </entry> + </row> + <row> + <entry> + <indexterm> + <primary>BIND</primary> + <secondary>files</secondary> + <tertiary><filename>/etc/rndc.conf</filename></tertiary> + </indexterm> + <filename>/etc/rndc.conf</filename> + </entry> + <entry> + The default configuration file for the <command>rndc</command> utility. + </entry> + </row> + <row> + <entry> + <indexterm> + <primary>BIND</primary> + <secondary>files</secondary> + <tertiary><filename>/etc/rndc.key</filename></tertiary> + </indexterm> + <filename>/etc/rndc.key</filename> + </entry> + <entry> + The default key location. + </entry> + </row> + </tbody> + </tgroup> + </table> + <para> + The <command>rndc</command> configuration is located in <filename>/etc/rndc.conf</filename>. If the file does not exist, the utility will use the key located in <filename>/etc/rndc.key</filename>, which was generated automatically during the installation process using the <command>rndc-confgen -a</command> command. + </para> + <para> + The <systemitem class="service">named</systemitem> service is configured using the <option>controls</option> statement in the <filename>/etc/named.conf</filename> configuration file as described in <xref linkend="sec-bind-namedconf-state-other" />. Unless this statement is present, only the connections from the loopback address (<systemitem class="ipaddress">127.0.0.1</systemitem>) will be allowed, and the key located in <filename>/etc/rndc.key</filename> will be used. + </para> + <para> + For more information on this topic, refer to manual pages and the <citetitle>BIND 9 Administrator Reference Manual</citetitle> listed in <xref linkend="sec-bind-additional-resources"/>. + </para> + <important> + <title>Set the correct permissions</title> + <para> + To prevent unprivileged users from sending control commands to the service, make sure only <systemitem class="username">root</systemitem> is allowed to read the <filename>/etc/rndc.key</filename> file: + </para> + <screen>~]# <command>chmod o-rwx /etc/rndc.key</command></screen> + </important> + </section> + <section id="sec-bind-rndc-status"> + <title>Checking the Service Status</title> + <para> + To check the current status of the <systemitem class="service">named</systemitem> service, use the following command: + </para> + <screen>~]# <command>rndc status</command> +version: 9.7.0-P2-RedHat-9.7.0-5.P2.el6 +CPUs found: 1 +worker threads: 1 +number of zones: 16 +debug level: 0 +xfers running: 0 +xfers deferred: 0 +soa queries in progress: 0 +query logging is OFF +recursive clients: 0/0/1000 +tcp clients: 0/100 +server is up and running</screen> + </section> + <section id="sec-bind-rndc-reload"> + <title>Reloading the Configuration and Zones</title> + <para> + To reload both the configuration file and zones, type the following at a shell prompt: + </para> + <screen>~]# <command>rndc reload</command> +server reload successful</screen> + <para> + This will reload the zones while keeping all previously cached responses, so that you can make changes to the zone files without losing all stored name resolutions. + </para> + <para> + To reload a single zone, specify its name after the <command>reload</command> command, for example: + </para> + <screen>~]# <command>rndc reload localhost</command> +zone reload up-to-date</screen> + <para> + Finally, to reload the configuration file and newly added zones only, type: + </para> + <screen>~]# <command>rndc reconfig</command></screen> + <note> + <title>Modifying zones with dynamic DNS</title> + <para> + If you intend to manually modify a zone that uses Dynamic <systemitem class="protocol">DNS</systemitem> (DDNS), make sure you run the <command>freeze</command> command first: + </para> + <screen>~]# <command>rndc freeze localhost</command></screen> + <para> + Once you are finished, run the <command>thaw</command> command to allow the <systemitem class="protocol">DDNS</systemitem> again and reload the zone: + </para> + <screen>~]# <command>rndc thaw localhost</command> +The zone reload and thaw was successful.</screen> + </note> + </section> + <section id="sec-bind-rndc-sign"> + <title>Updating Zone Keys</title> + <para> + To update the DNSSEC keys and sign the zone, use the <command>sign</command> command. For example: + </para> + <screen>~]# <command>rndc sign localhost</command></screen> + <para> + Note that to sign a zone with the above command, the <option>auto-dnssec</option> option has to be set to <literal>maintain</literal> in the zone statement. For example: + </para> + <programlisting>zone "localhost" IN { + type master; + file "named.localhost"; + allow-update { none; }; + auto-dnssec maintain; +};</programlisting> + </section> + <section id="sec-bind-rndc-validation"> + <title>Enabling the DNSSEC Validation</title> + <para> + To enable the DNSSEC validation, issue the following command as <systemitem class="username">root</systemitem>: + </para> + <screen>~]# <command>rndc validation on</command></screen> + <para> + Similarly, to disable this option, type: + </para> + <screen>~]# <command>rndc validation off</command></screen> + <para> + Refer to the <option>options</option> statement described in <xref linkend="sec-bind-namedconf-state" /> for information on how to configure this option in <filename>/etc/named.conf</filename>. + </para> + </section> + <section id="sec-bind-rndc-querylog"> + <title>Enabling the Query Logging</title> + <para> + To enable (or disable in case it is currently enabled) the query logging, issue the following command as <systemitem class="username">root</systemitem>: + </para> + <screen>~]# <command>rndc querylog</command></screen> + <para> + To check the current setting, use the <command>status</command> command as described in <xref linkend="sec-bind-rndc-status" />. + </para> + </section> + </section> + <section id="sec-bind-dig"> + <title>Using the dig Utility</title> + <indexterm significance="preferred"> + <primary>BIND</primary> + <secondary>utilities</secondary> + <tertiary><command>dig</command></tertiary> + </indexterm> + <para> + The <command>dig</command> utility is a command-line tool that allows you to perform <systemitem class="protocol">DNS</systemitem> lookups and debug a nameserver configuration. Its typical usage is as follows: + </para> + <screen><command>dig</command> [@<replaceable>server</replaceable>] [<replaceable>option</replaceable>...] <replaceable>name</replaceable> <replaceable>type</replaceable></screen> + <para> + Refer to <xref linkend="sec-bind-zone-rr" /> for a list of common values to use for <replaceable>type</replaceable>. + </para> + <section id="sec-bind-dig-ns"> + <title>Looking Up a Nameserver</title> + <para> + To look up a nameserver for a particular domain, use the command in the following form: + </para> + <screen><command>dig</command> <replaceable>name</replaceable> NS</screen> + <para> + In <xref linkend="example-bind-dig-ns" />, the <command>dig</command> utility is used to display nameservers for <systemitem class="domainname">example.com</systemitem>. + </para> + <example id="example-bind-dig-ns"> + <title>A sample nameserver lookup</title> + <screen>~]$ <command>dig example.com NS</command> + +; <<>> DiG 9.7.1-P2-RedHat-9.7.1-2.P2.fc13 <<>> example.com NS +;; global options: +cmd +;; Got answer: +;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 57883 +;; flags: qr rd ra; QUERY: 1, ANSWER: 2, AUTHORITY: 0, ADDITIONAL: 0 + +;; QUESTION SECTION: +;example.com. IN NS + +;; ANSWER SECTION: +example.com. 99374 IN NS a.iana-servers.net. +example.com. 99374 IN NS b.iana-servers.net. + +;; Query time: 1 msec +;; SERVER: 10.34.255.7#53(10.34.255.7) +;; WHEN: Wed Aug 18 18:04:06 2010 +;; MSG SIZE rcvd: 77</screen> + </example> + </section> + <section id="sec-bind-dig-a"> + <title>Looking Up an IP Address</title> + <para> + To look up an <systemitem class="protocol">IP</systemitem> address assigned to a particular domain, use the command in the following form: + </para> + <screen><command>dig</command> <replaceable>name</replaceable> A</screen> + <para> + In <xref linkend="example-bind-dig-a" />, the <command>dig</command> utility is used to display the <systemitem class="protocol">IP</systemitem> address of <systemitem class="domainname">example.com</systemitem>. + </para> + <example id="example-bind-dig-a"> + <title>A sample IP address lookup</title> + <screen>~]$ <command>dig example.com A</command> + +; <<>> DiG 9.7.1-P2-RedHat-9.7.1-2.P2.fc13 <<>> example.com A +;; global options: +cmd +;; Got answer: +;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 4849 +;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 2, ADDITIONAL: 0 + +;; QUESTION SECTION: +;example.com. IN A + +;; ANSWER SECTION: +example.com. 155606 IN A 192.0.32.10 + +;; AUTHORITY SECTION: +example.com. 99175 IN NS a.iana-servers.net. +example.com. 99175 IN NS b.iana-servers.net. + +;; Query time: 1 msec +;; SERVER: 10.34.255.7#53(10.34.255.7) +;; WHEN: Wed Aug 18 18:07:25 2010 +;; MSG SIZE rcvd: 93</screen> + </example> + </section> + <section id="sec-bind-dig-x"> + <title>Looking Up a Host Name</title> + <para> + To look up a host name for a particular <systemitem class="protocol">IP</systemitem> address, use the command in the following form: + </para> + <screen><command>dig</command> <option>-x</option> <replaceable>address</replaceable></screen> + <para> + In <xref linkend="example-bind-dig-x" />, the <command>dig</command> utility is used to display the host name assigned to <systemitem class="ipaddress">192.0.32.10</systemitem>. + </para> + <example id="example-bind-dig-x"> + <title>A Sample Host Name Lookup</title> + <screen>~]$ <command>dig -x 192.0.32.10</command> + +; <<>> DiG 9.7.1-P2-RedHat-9.7.1-2.P2.fc13 <<>> -x 192.0.32.10 +;; global options: +cmd +;; Got answer: +;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 29683 +;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 5, ADDITIONAL: 6 + +;; QUESTION SECTION: +;10.32.0.192.in-addr.arpa. IN PTR + +;; ANSWER SECTION: +10.32.0.192.in-addr.arpa. 21600 IN PTR www.example.com. + +;; AUTHORITY SECTION: +32.0.192.in-addr.arpa. 21600 IN NS b.iana-servers.org. +32.0.192.in-addr.arpa. 21600 IN NS c.iana-servers.net. +32.0.192.in-addr.arpa. 21600 IN NS d.iana-servers.net. +32.0.192.in-addr.arpa. 21600 IN NS ns.icann.org. +32.0.192.in-addr.arpa. 21600 IN NS a.iana-servers.net. + +;; ADDITIONAL SECTION: +a.iana-servers.net. 13688 IN A 192.0.34.43 +b.iana-servers.org. 5844 IN A 193.0.0.236 +b.iana-servers.org. 5844 IN AAAA 2001:610:240:2::c100:ec +c.iana-servers.net. 12173 IN A 139.91.1.10 +c.iana-servers.net. 12173 IN AAAA 2001:648:2c30::1:10 +ns.icann.org. 12884 IN A 192.0.34.126 + +;; Query time: 156 msec +;; SERVER: 10.34.255.7#53(10.34.255.7) +;; WHEN: Wed Aug 18 18:25:15 2010 +;; MSG SIZE rcvd: 310</screen> + </example> + </section> + </section> + <section id="sec-bind-features"> + <title>Advanced Features of BIND</title> + <para> + Most BIND implementations only use the <systemitem class="service">named</systemitem> service to provide name resolution services or to act as an authority for a particular domain. However, BIND version 9 has a number of advanced features that allow for a more secure and efficient <systemitem class="protocol">DNS</systemitem> service. + </para> + <important> + <title>Make sure the feature is supported</title> + <para> + Before attempting to use advanced features like DNSSEC, TSIG, or IXFR (Incremental Zone Transfer), make sure that the particular feature is supported by all nameservers in the network environment, especially when you use older versions of BIND or non-BIND servers. + </para> + </important> + <para> + All of the features mentioned are discussed in greater detail in the <citetitle>BIND 9 Administrator Reference Manual</citetitle> referenced in <xref linkend="sec-bind-installed-docs" />. + </para> + <section id="sec-bind-features-views"> + <title>Multiple Views</title> + <indexterm> + <primary>BIND</primary> + <secondary>features</secondary> + <tertiary>multiple views</tertiary> + </indexterm> + <para> + Optionally, different information can be presented to a client depending on the network a request originates from. This is primarily used to deny sensitive <systemitem class="protocol">DNS</systemitem> entries from clients outside of the local network, while allowing queries from clients inside the local network. + </para> + <para> + To configure multiple views, add the <command>view</command> statement to the <filename>/etc/named.conf</filename> configuration file. Use the <option>match-clients</option> option to match <systemitem class="protocol">IP</systemitem> addresses or entire networks and give them special options and zone data. + </para> + </section> + <section id="sec-bind-features-ixfr"> + <title>Incremental Zone Transfers (IXFR)</title> + <indexterm> + <primary>BIND</primary> + <secondary>features</secondary> + <tertiary>Incremental Zone Transfer (IXFR)</tertiary> + </indexterm> + <para> + <firstterm>Incremental Zone Transfers</firstterm> (<firstterm>IXFR</firstterm>) allow a secondary nameserver to only download the updated portions of a zone modified on a primary nameserver. Compared to the standard transfer process, this makes the notification and update process much more efficient. + </para> + <indexterm> + <primary>BIND</primary> + <secondary>features</secondary> + <tertiary>Automatic Zone Transfer (AXFR)</tertiary> + </indexterm> + <para> + Note that IXFR is only available when using dynamic updating to make changes to master zone records. If manually editing zone files to make changes, <firstterm>Automatic Zone Transfer</firstterm> (<firstterm>AXFR</firstterm>) is used. + </para> + </section> + <section id="sec-bind-features-tsig"> + <title>Transaction SIGnatures (TSIG)</title> + <indexterm> + <primary>BIND</primary> + <secondary>features</secondary> + <tertiary>Transaction SIGnature (TSIG)</tertiary> + </indexterm> + <para> + <firstterm>Transaction SIGnatures</firstterm> (TSIG) ensure that a shared secret key exists on both primary and secondary nameservers before allowing a transfer. This strengthens the standard <systemitem class="protocol">IP</systemitem> address-based method of transfer authorization, since attackers would not only need to have access to the <systemitem class="protocol">IP</systemitem> address to transfer the zone, but they would also need to know the secret key. + </para> + <para> + Since version 9, BIND also supports <firstterm>TKEY</firstterm>, which is another shared secret key method of authorizing zone transfers. + </para> + <important> + <title>Secure the transfer</title> + <para> + When communicating over an insecure network, do not rely on <systemitem class="protocol">IP</systemitem> address-based authentication only. + </para> + </important> + </section> + <section id="sec-bind-features-dnssec"> + <title>DNS Security Extensions (DNSSEC)</title> + <indexterm> + <primary>BIND</primary> + <secondary>features</secondary> + <tertiary>DNS Security Extensions (DNSSEC)</tertiary> + </indexterm> + <para> + <firstterm>Domain Name System Security Extensions</firstterm> (<firstterm>DNSSEC</firstterm>) provide origin authentication of <systemitem class="protocol">DNS</systemitem> data, authenticated denial of existence, and data integrity. When a particular domain is marked as secure, the <literal>SERVFAIL</literal> response is returned for each resource record that fails the validation. + </para> + <indexterm> + <primary>BIND</primary> + <secondary>utilities</secondary> + <tertiary><command>dig</command></tertiary> + </indexterm> + <para> + Note that to debug a DNSSEC-signed domain or a DNSSEC-aware resolver, you can use the <command>dig</command> utility as described in <xref linkend="sec-bind-dig" />. Useful options are <option>+dnssec</option> (requests DNSSEC-related resource records by setting the DNSSEC OK bit), <option>+cd</option> (tells recursive nameserver not to validate the response), and <option>+bufsize=512</option> (changes the packet size to 512B to get through some firewalls). + </para> + </section> + <section id="sec-bind-features-ipv6"> + <title>Internet Protocol version 6 (IPv6)</title> + <indexterm> + <primary>BIND</primary> + <secondary>features</secondary> + <tertiary>Internet Protocol version 6 (IPv6)</tertiary> + </indexterm> + <para> + <firstterm>Internet Protocol version 6</firstterm> (<firstterm>IPv6</firstterm>) is supported through the use of <option>AAAA</option> resource records, and the <option>listen-on-v6</option> directive as described in <xref linkend="table-bind-namedconf-common-options" />. + </para> + </section> + </section> + <section id="sec-bind-mistakes"> + <title>Common Mistakes to Avoid</title> + <indexterm> + <primary>BIND</primary> + <secondary>common mistakes</secondary> + </indexterm> + <para> + The following is a list of recommendations on how to avoid common mistakes users make when configuring a nameserver: + </para> + <variablelist> + <varlistentry> + <term>Use semicolons and curly brackets correctly</term> + <listitem> + <para> + An omitted semicolon or unmatched curly bracket in the <filename>/etc/named.conf</filename> file can prevent the <systemitem class="service">named</systemitem> service from starting. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Use period (the <literal>.</literal> character) correctly</term> + <listitem> + <para> + In zone files, a period at the end of a domain name denotes a fully qualified domain name. If omitted, the <systemitem class="service">named</systemitem> service will append the name of the zone or the value of <option>$ORIGIN</option> to complete it. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Increment the serial number when editing a zone file</term> + <listitem> + <para> + If the serial number is not incremented, the primary nameserver will have the correct, new information, but the secondary nameservers will never be notified of the change, and will not attempt to refresh their data of that zone. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Configure the firewall</term> + <listitem> + <para> + If a firewall is blocking connections from the <systemitem class="service">named</systemitem> service to other nameservers, the recommended practice is to change the firewall settings. + </para> + <warning id="warning-Warning-Avoid_Using_Fixed_UDP_Source_Ports"> + <title>Avoid using fixed UDP source ports</title> + <para> + Using a fixed <systemitem class="protocol">UDP</systemitem> source port for <systemitem class="protocol">DNS</systemitem> queries is a potential security vulnerability that could allow an attacker to conduct cache-poisoning attacks more easily. To prevent this, by default <systemitem class="protocol">DNS</systemitem> sends from a random ephemeral port. Configure your firewall to allow outgoing queries from a random <systemitem class="protocol">UDP</systemitem> source port. The range <literal>1024</literal> to <literal>65535</literal> is used by default.</para> + </warning> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="sec-bind-additional-resources"> + <title>Additional Resources</title> + <para> + The following sources of information provide additional resources regarding BIND. + </para> + <section id="sec-bind-installed-docs"> + <title>Installed Documentation</title> + <indexterm> + <primary>BIND</primary> + <secondary>additional resources</secondary> + <tertiary>installed documentation</tertiary> + </indexterm> + <para> + BIND features a full range of installed documentation covering many different topics, each placed in its own subject directory. For each item below, replace <replaceable>version</replaceable> with the version of the <package>bind</package> package installed on the system: + </para> + <variablelist> + <varlistentry> + <term> + <filename class="directory">/usr/share/doc/bind-<replaceable>version</replaceable>/</filename> + </term> + <listitem> + <para> + The main directory containing the most recent documentation. The directory contains the <citetitle>BIND 9 Administrator Reference Manual</citetitle> in HTML and PDF formats, which details BIND resource requirements, how to configure different types of nameservers, how to perform load balancing, and other advanced topics.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <filename class="directory">/usr/share/doc/bind-<replaceable>version</replaceable>/sample/etc/</filename> + </term> + <listitem> + <para> + The directory containing examples of <systemitem class="daemon">named</systemitem> configuration files. + </para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term> + <filename>rndc(8)</filename> + </term> + <listitem> + <para> + The manual page for the <command>rndc</command> name server control utility, containing documentation on its usage. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <filename>named(8)</filename> + </term> + <listitem> + <para> + The manual page for the Internet domain name server <systemitem class="service">named</systemitem>, containing documentation on assorted arguments that can be used to control the BIND nameserver daemon. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <filename>lwresd(8)</filename> + </term> + <listitem> + <para> + The manual page for the lightweight resolver daemon <systemitem class="service">lwresd</systemitem>, containing documentation on the daemon and its usage. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <filename>named.conf(5)</filename> + </term> + <listitem> + <para> + The manual page with a comprehensive list of options available within the <systemitem class="service">named</systemitem> configuration file. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <command>rndc.conf(5)</command> + </term> + <listitem> + <para> + The manual page with a comprehensive list of options available within the <command>rndc</command> configuration file. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="sec-bind-useful-websites"> + <title>Useful Websites</title> + <indexterm> + <primary>BIND</primary> + <secondary>additional resources</secondary> + <tertiary>useful websites</tertiary> + </indexterm> + <variablelist> + <varlistentry> + <term> + <ulink url="http://www.isc.org/software/bind"/> + </term> + <listitem> + <para> + The home page of the BIND project containing information about current releases as well as a PDF version of the <citetitle>BIND 9 Administrator Reference Manual</citetitle>. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="sec-bind-related-books"> + <title>Related Books</title> + <indexterm> + <primary>BIND</primary> + <secondary>additional resources</secondary> + <tertiary>related books</tertiary> + </indexterm> + <variablelist> + <varlistentry> + <term><citetitle>DNS and BIND</citetitle> by Paul Albitz and Cricket Liu; O'Reilly & Associates</term> + <listitem> + <para> + A popular reference that explains both common and esoteric BIND configuration options, and provides strategies for securing a DNS server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><citetitle>The Concise Guide to DNS and BIND</citetitle> by Nicolai Langfeldt; Que</term> + <listitem> + <para> + Looks at the connection between multiple network services and BIND, with an emphasis on task-oriented, technical topics. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + </section> +</section> diff --git a/docs/guide/Book_Info.xml b/docs/guide/Book_Info.xml new file mode 100644 index 000000000..f52a25b1a --- /dev/null +++ b/docs/guide/Book_Info.xml @@ -0,0 +1,40 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "Networking_Guide.ent"> +%BOOK_ENTITIES; +]> +<bookinfo> + <subjectset> + <subject> + <subjectterm>Users/Networking</subjectterm> + </subject> +</subjectset> +<keywordset> + <keyword>Network Manager</keyword> + <keyword>nmcli</keyword> + <keyword>networking</keyword> + <keyword>routing</keyword> +</keywordset> + + <title>Networking Guide</title> + <subtitle>Configuration and Administration of Networking for &MAJOROSVER;</subtitle> + <productname>Fedora</productname> + <productnumber>24</productnumber> + <edition>1.0</edition> + <pubsnumber>0</pubsnumber> + <abstract> + <para> + The <citetitle pubwork="book">Networking Guide</citetitle> documents relevant information regarding the configuration and administration of network interfaces, networks and network services in &MAJOROSVER;. It is oriented towards system administrators with a basic understanding of Linux and networking. + </para> + <para> This book is based on the <citetitle pubwork="book">Deployment Guide</citetitle> from Red Hat Enterprise Linux 6. The chapters related to networking were taken from the Deployment Guide to form the foundation for this book.</para> + </abstract> + <corpauthor> + <inlinemediaobject> + <imageobject> + <imagedata fileref="Common_Content/title_logo.svg" format="SVG" /> + </imageobject> + </inlinemediaobject> + </corpauthor> + <xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> +</bookinfo> diff --git a/docs/guide/Configure_802_1Q_VLAN_Tagging.xml b/docs/guide/Configure_802_1Q_VLAN_Tagging.xml new file mode 100644 index 000000000..6f0810c7b --- /dev/null +++ b/docs/guide/Configure_802_1Q_VLAN_Tagging.xml @@ -0,0 +1,453 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "Networking_Guide.ent"> +%BOOK_ENTITIES; +]> +<chapter id="ch-Configure_802_1Q_VLAN_Tagging"> + + <!--Topic, Tasks--> + <title>Configure 802.1Q VLAN tagging</title> + <para> + To create a VLAN, an interface is created on another interface referred to as the <firstterm>parent interface</firstterm>. The VLAN interface will tag packets with the VLAN ID as they pass through the interface, and returning packets will be untagged. VLAN interface can be configured similarly to any other interface. The parent interface need not be an Ethernet interface. An 802.1Q VLAN tagging interface can be created on bridge, bond, and team interfaces, however there are some things to note: + </para> + + <itemizedlist> + <listitem> + <para> + In the case of VLANs over bonds, it is important that the bond has slaves and that they are <quote>up</quote> before bringing up the VLAN interface. At the time of writing, adding a VLAN interface to a bond without slaves does not work. + </para> + </listitem> + <listitem> + <para> +A VLAN slave cannot be configured on a bond with the <option>fail_over_mac=follow</option> option, because the VLAN virtual device cannot change its MAC address to match the parent's new MAC address. In such a case, traffic would still be sent with the now incorrect source MAC address.</para> + </listitem> + <listitem> +<para> + Sending VLAN tagged packets through a network switch requires configuration of the switch. Refer to the documentation for the switch. For example, for Cisco switches the port must be assigned to one VLAN or configured to be a trunk port to accept tagged packets for multiple VLANs. Untagged packets can also be processed by a trunk port and processed as belonging to the <firstterm>native VLAN</firstterm>, however this is a security risk and may have been disabled, or by default not enabled, depending on the make of the switch. +</para> +</listitem> + +<listitem> +<para> +Some older network interface cards, loopback interfaces, Wimax cards, and some InfiniBand devices, are said to be <firstterm>VLAN challenged</firstterm>, meaning they cannot support VLANs. This is usually because the devices cannot cope with VLAN headers and the larger MTU size associated with tagged packets. +</para> +</listitem> +</itemizedlist> + +<section id="sec-Selecting_VLAN_Interface_Configuration_Methods"> +<title>Selecting VLAN Interface Configuration Methods</title> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">To configure a network using graphical user interface tools</emphasis>, proceed to <xref linkend="sec-Configure_802_1Q_VLAN_Tagging_Using_a_GUI" /> + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">To configure a VLAN interface using</emphasis> <application>NetworkManager</application>'s command-line tool, <application>nmcli</application>, proceed to <xref linkend="sec-Configure_802_1Q_VLAN_Tagging_Using_the_Command_Line_Tool_nmcli" /> + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">To configure a network interface manually</emphasis>, see <xref linkend="sec-Configure_802_1Q_VLAN_Tagging_Using_the_Command_Line" />. + </para> + </listitem> + </itemizedlist> + </section> + +<section id="sec-Configure_802_1Q_VLAN_Tagging_Using_a_GUI"> + <title>Configure 802.1Q VLAN Tagging Using a GUI</title> + + +<section + id="sec-Establishing_a_VLAN_Connection"> + <title>Establishing a VLAN Connection</title> + <para>You can use the GNOME <application>control-center</application> utility to direct <application>NetworkManager</application> to create a VLAN using an existing interface as the parent interface. At time of writing, you can only make VLANs on Ethernet devices. Note that VLAN devices are only created automatically if the parent interface is set to connect automatically.</para> + + <procedure + id="procedure-Adding_a_New_VLAN_Connection"> + <title>Adding a New VLAN Connection</title> + <para>You can configure a VLAN connection by opening the <guilabel>Network</guilabel> window, clicking the plus symbol, and selecting <guilabel>VLAN</guilabel> from the list.</para> + + <step> + <para>Press the <keycap>Super</keycap> key to enter the Activities Overview, type <command>control network</command> and then press <keycap>Enter</keycap>. The <guilabel>Network</guilabel> settings tool appears.</para> + </step> + + <step> + <para>Click the plus symbol to open the selection list. Select <guilabel>VLAN</guilabel>. The <guilabel>Editing VLAN Connection <replaceable>1</replaceable></guilabel> window appears.</para> + </step> + <step> + <para>On the <guilabel>VLAN</guilabel> tab, select the parent interface from the drop-down list you want to use for the VLAN connection.</para> + </step> + <step> + <para>Enter the VLAN ID</para> + </step> + <step> + <para>Enter a VLAN interface name. This is the name of the VLAN interface that will be created. For example, <literal>eth0.1</literal> or <literal>vlan2</literal>. (Normally this is either the parent interface name plus <quote><literal>.</literal></quote> and the VLAN ID, or <quote><literal>vlan</literal></quote> plus the VLAN ID.) +</para> + </step> + + <step><para>Review and confirm the settings and then click the <guilabel>Save</guilabel> button.</para> + </step> + <step> + <para>To edit the VLAN-specific settings see <xref linkend="sec-Configuring_the_VLAN_Tab"/>.</para> + </step> + </procedure> + + + <procedure + id="procedure-Editing_an_Existing_VLAN_Connection"> + <title>Editing an Existing VLAN Connection</title> + <para>Follow these steps to edit an existing VLAN connection.</para> + <step> + <para>Press the <keycap>Super</keycap> key to enter the Activities Overview, type <command>control network</command> and then press <keycap>Enter</keycap>. The <guilabel>Network</guilabel> settings tool appears.</para> + </step> + + <step> + <para>Select the connection you want to edit and click the <guilabel>Options</guilabel> button.</para> + </step> + <step> + <para>Select the <guilabel>General</guilabel> tab.</para> + </step> + <step> + <para>Configure the connection name, auto-connect behavior, and availability settings.</para> + <para>These settings in the <guilabel>Editing</guilabel> dialog are common to all connection types:</para> + <itemizedlist> + <listitem> + <para> + <guilabel>Connection name</guilabel> — Enter a descriptive name for your network connection. This name will be used to list this connection in the <guilabel>VLAN</guilabel> section of the <guilabel>Network</guilabel> window.</para> + </listitem> + <listitem> + <para> + <guilabel>Automatically connect to this network when it is available</guilabel> — Select this box if you want <application>NetworkManager</application> to auto-connect to this connection when it is available. Refer to <xref + linkend="sec-Connecting_to_a_Network_Automatically"/> for more information.</para> + </listitem> + <listitem> + <para> + <guilabel>Available to all users</guilabel> — Select this box to create a connection available to all users on the system. Changing this setting may require root privileges. Refer to <xref + linkend="sec-System-wide_and_Private_Connection_Profiles"/> for details.</para> + </listitem> + </itemizedlist> + </step> + <step> + <para>To edit the VLAN-specific settings see <xref linkend="sec-Configuring_the_VLAN_Tab"/>.</para> + </step> + </procedure> + <bridgehead + id="bh-Saving_Your_New_or_Modified_Connection_and_Making_Further_Configurations-VLAN">Saving Your New (or Modified) Connection and Making Further Configurations</bridgehead> + + <para>Once you have finished editing your VLAN connection, click the <guibutton>Save</guibutton> button to save your customized configuration. If the profile was in use while being edited, power cycle the connection to make <application>NetworkManager</application> apply the changes. If the profile is OFF, set it to ON. See <xref + linkend="sec-Connecting_to_a_Network_Using_a_GUI"/> for information on using your new or altered connection.</para> + <para>You can further configure an existing connection by selecting it in the <guilabel>Network</guilabel> window and clicking <guilabel>Options</guilabel> to return to the <guilabel>Editing</guilabel> dialog.</para> + <para>Then, to configure:</para> + <itemizedlist> + + <listitem> + <para>IPv4 settings for the connection, click the <guilabel>IPv4 Settings</guilabel> tab and proceed to <xref + linkend="sec-Configuring_IPv4_Settings"/>. + </para> + </listitem> + + </itemizedlist> + + <section id="sec-Configuring_the_VLAN_Tab"> + <title>Configuring the VLAN Tab</title> + <para>If you have already added a new VLAN connection (refer to <xref + linkend="procedure-Adding_a_New_VLAN_Connection"/> for instructions), you can edit the <guilabel>VLAN</guilabel> tab to set the parent interface and the VLAN ID.</para> + <variablelist> + <varlistentry> + <term> + <guilabel>Parent Interface</guilabel> + </term> + <listitem> + + <para>A previously configured interface can be selected in the drop-down list. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>VLAN ID</guilabel> + </term> + <listitem> + <para>The identification number to be used to tag the VLAN network traffic.</para> + </listitem> + </varlistentry> + + + <varlistentry> + <term> + <guilabel>VLAN interface name</guilabel> + </term> + <listitem> + <para>The name of the VLAN interface that will be created. For example, <literal>eth0.1</literal> or <literal>vlan2</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <guilabel>Cloned MAC address</guilabel> + </term> + <listitem> + <para>Optionally sets an alternate MAC address to use for identifying the VLAN interface. This can be used to change the source MAC address for packets sent on this VLAN.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <guilabel>MTU</guilabel> + </term> + <listitem> + <para>Optionally sets a Maximum Transmission Unit (MTU) size to be used for packets to be sent over the VLAN connection.</para> + </listitem> + </varlistentry> + + </variablelist> + </section> + + </section> +</section> + +<section id="sec-Configure_802_1Q_VLAN_Tagging_Using_the_Command_Line"> + <title>Configure 802.1Q VLAN Tagging Using the Command Line</title> +<para> + In Fedora, the <systemitem class="resource">8021q</systemitem> module is loaded by default. If necessary, you can make sure that the module is loaded by issuing the following command as <systemitem class="username">root</systemitem>: + <screen>~]# <command>modprobe --first-time 8021q</command> +modprobe: ERROR: could not insert '8021q': Module already in kernel</screen> +To display information about the module, issue the following command: +<screen>~]$ <command>modinfo 8021q</command></screen> +See the <filename>modprobe(8)</filename> man page for more command options. + </para> + + +<section id="sec-Setting_Up_802.1Q_VLAN_Tagging_Using_ifcfg_Files"> + <title>Setting Up 802.1Q VLAN Tagging Using ifcfg Files</title> + <procedure> + <step><para>Configure the parent interface in <filename>/etc/sysconfig/network-scripts/ifcfg-eth<replaceable>X</replaceable></filename>, where <replaceable>X</replaceable> is a unique number corresponding to a specific interface, as follows:</para> + <screen>DEVICE=ethX +TYPE=Ethernet +BOOTPROTO=none +ONBOOT=yes</screen> + </step> + <step> + <para> + Configure the VLAN interface configuration in the <filename class="directory">/etc/sysconfig/network-scripts/</filename> directory. The configuration file name should be the parent interface plus a <literal>.</literal> character plus the VLAN ID number. For example, if the VLAN ID is 192, and the parent interface is <replaceable>eth0</replaceable>, then the configuration file name should be <filename>ifcfg-eth0.192</filename>:</para> + <screen>DEVICE=ethX.192 +BOOTPROTO=none +ONBOOT=yes +IPADDR=192.168.1.1 +PREFIX=24 +NETWORK=192.168.1.0 +VLAN=yes</screen> + <para> + If there is a need to configure a second VLAN, with for example, VLAN ID 193, on the same interface, <replaceable>eth0</replaceable>, add a new file with the name <filename>eth0.193</filename> with the VLAN configuration details.</para> + </step> + <step> + <para> + Restart the networking service in order for the changes to take effect. As <systemitem class="username">root</systemitem> issue the following command:</para> + <screen>~]# <command>systemctl restart network</command></screen> + </step> + </procedure> + </section> + + <section id="sec-Configure_802_1Q_VLAN_Tagging_ip_Commands"> +<title>Configure 802.1Q VLAN Tagging Using ip Commands</title> +<para> +To create an 802.1Q VLAN interface on Ethernet interface <replaceable>eth0</replaceable>, with name <replaceable>VLAN8</replaceable> and ID <literal>8</literal>, issue a command as <systemitem class="username">root</systemitem> as follows: + <screen>~]# <command>ip link add link <replaceable>eth0</replaceable> name <replaceable>eth0.8</replaceable> type vlan id 8</command></screen> + To view the VLAN, issue the following command: + <screen>~]$ <command>ip -d link show <replaceable>eth0.8</replaceable></command> +4: eth0.8@eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP mode DEFAULT + link/ether 52:54:00:ce:5f:6c brd ff:ff:ff:ff:ff:ff promiscuity 0 + vlan protocol 802.1Q id 8 <REORDER_HDR></screen> +</para> +<para> + Note that the <application>ip</application> utility interprets the VLAN ID as a hexadecimal value if it is preceded by <literal>0x</literal> and as an octal value if it has a leading <literal>0</literal>. This means that in order to assign a VLAN ID with a decimal value of <literal>22</literal>, you must not add any leading zeros. +</para> +<para> + To remove the VLAN, issue a command as <systemitem class="username">root</systemitem> as follows: + <screen>~]# <command>ip link delete <replaceable>eth0.8</replaceable></command></screen> +</para> +<note> +<para> + VLAN interfaces created using <application>ip</application> commands at the command prompt will be lost if the system is shutdown or restarted. To configure VLAN interfaces to be persistent after a system restart, use <filename>ifcfg</filename> files. See <xref linkend="sec-Setting_Up_802.1Q_VLAN_Tagging_Using_ifcfg_Files" /> +</para> +</note> +</section> +</section> + +<section id="sec-Configure_802_1Q_VLAN_Tagging_Using_the_Command_Line_Tool_nmcli"> + <title>Configure 802.1Q VLAN Tagging Using the Command Line Tool, nmcli</title> + <para> + To view the available interfaces on the system, issue a command as follows: + <screen>~]$ <command>nmcli con show</command> +NAME UUID TYPE DEVICE +System eth1 9c92fad9-6ecb-3e6c-eb4d-8a47c6f50c04 802-3-ethernet eth1 +System eth0 5fb06bd0-0bb0-7ffb-45f1-d6edd65f3e03 802-3-ethernet eth0</screen> +Note that the NAME field in the output always denotes the connection ID. It is not the interface name even though it might look the same. +The ID can be used in <command>nmcli connection</command> commands to identify a connection. Use the DEVICE name with other applications such as <systemitem class="daemon">firewalld</systemitem>. + </para> + <para> + To create an 802.1Q VLAN interface on Ethernet interface <replaceable>eth0</replaceable>, with VLAN interface <replaceable>VLAN10</replaceable> and ID <literal>10</literal>, issue a command as follows: + <screen>~]$ <command>nmcli con add type vlan ifname <replaceable>VLAN10</replaceable> dev <replaceable>eth0</replaceable> id 10</command> +Connection 'vlan-VLAN10' (37750b4a-8ef5-40e6-be9b-4fb21a4b6d17) successfully added.</screen> +Note that as no <option>con-name</option> was given for the VLAN interface, the name was derived from the interface name by prepending the type. Alternatively, specify a name with the <option>con-name</option> option as follows: +<screen>~]$ <command>nmcli con add type vlan con-name <replaceable>VLAN12</replaceable> dev <replaceable>eth0</replaceable> id 12</command> +Connection 'VLAN12' (b796c16a-9f5f-441c-835c-f594d40e6533) successfully added.</screen> +</para> + +<bridgehead id="bh-Assigning_Addresses_to_VLAN_Interfaces">Assigning Addresses to VLAN Interfaces</bridgehead> +<para> + You can use the same <application>nmcli</application> commands to assign static and dynamic interface addresses as with any other interface.</para> + <para> + For example, a command to create a VLAN interface with a static <systemitem class="protocol">IPv4</systemitem> address and gateway is as follows: + <screen>~]$ <command>nmcli con add type vlan con-name <replaceable>VLAN20</replaceable> ifname <replaceable>VLAN20</replaceable> id 20 \</command> +<command>dev <replaceable>eth0</replaceable> ip4 10.10.10.10/24 gw4 10.10.10.254</command></screen></para> +<para> +To create a VLAN interface with dynamically assigned addressing, issue a command as follows: + <screen>~]$ <command>nmcli con add type vlan con-name <replaceable>VLAN30</replaceable> ifname <replaceable>VLAN30</replaceable> id 30 dev <replaceable>eth0</replaceable></command></screen> + </para> + <para> + See <xref linkend="sec-Connecting_to_a_Network_Using_nmcli" /> for examples of using <application>nmcli</application> commands to configure interfaces. + </para> + +<para> + To review the VLAN interfaces created, issue a command as follows: + <screen>~]$ <command>nmcli con show</command> +NAME UUID TYPE DEVICE +VLAN12 4129a37d-4feb-4be5-ac17-14a193821755 vlan eth0.12 +System eth1 9c92fad9-6ecb-3e6c-eb4d-8a47c6f50c04 802-3-ethernet eth1 +System eth0 5fb06bd0-0bb0-7ffb-45f1-d6edd65f3e03 802-3-ethernet eth0 +vlan-VLAN10 1be91581-11c2-461a-b40d-893d42fed4f4 vlan VLAN10</screen> + +</para> +<para> + To view detailed information about the newly configured connection, issue a command as follows: + <screen>~]$ <command>nmcli -p con show <replaceable>VLAN12</replaceable></command> +=============================================================================== + Connection profile details (VLAN12) +=============================================================================== +connection.id: VLAN12 +connection.uuid: 4129a37d-4feb-4be5-ac17-14a193821755 +connection.interface-name: -- +connection.type: vlan +connection.autoconnect: yes +<lineannotation>…</lineannotation> +------------------------------------------------------------------------------- +802-3-ethernet.port: -- +802-3-ethernet.speed: 0 +802-3-ethernet.duplex: -- +802-3-ethernet.auto-negotiate: yes +802-3-ethernet.mac-address: -- +802-3-ethernet.cloned-mac-address: -- +802-3-ethernet.mac-address-blacklist: +802-3-ethernet.mtu: auto +<lineannotation>…</lineannotation> +vlan.interface-name: -- +vlan.parent: eth0 +vlan.id: 12 +vlan.flags: 0 (NONE) +vlan.ingress-priority-map: +vlan.egress-priority-map: +------------------------------------------------------------------------------- +=============================================================================== + Activate connection details (4129a37d-4feb-4be5-ac17-14a193821755) +=============================================================================== +GENERAL.NAME: VLAN12 +GENERAL.UUID: 4129a37d-4feb-4be5-ac17-14a193821755 +GENERAL.DEVICES: eth0.12 +GENERAL.STATE: activating +<lineannotation>[output truncated]</lineannotation></screen> +</para> +<para> +Further options for the VLAN command are listed in the VLAN section of the <filename>nmcli(1)</filename> man page. In the man pages the device on which the VLAN is created is referred to as the parent device. In the example above the device was specified by its interface name, <literal>eth0</literal>, it can also be specified by the connection UUID or MAC address. + </para> + <para> + To create an 802.1Q VLAN connection profile with ingress priority mapping on Ethernet interface <replaceable>eth1</replaceable>, with name <interface>VLAN13</interface> and ID <literal>13</literal>, issue a command as follows: + <screen>~]$ <command>nmcli con add type vlan con-name <replaceable>VLAN13</replaceable> dev <replaceable>eth2</replaceable> id 13 ingress "2:3,3:5"</command></screen> + </para> + <para> + To view all the parameters associated with the VLAN created above, issue a command as follows: + <screen>~]$ <command>nmcli connection show <replaceable>VLAN13</replaceable></command></screen> + </para> + <para> + To change the MTU, issue a command as follows: + <screen>~]$ <command>nmcli connection modify <replaceable>VLAN13</replaceable> 802.mtu 1496</command></screen> + The MTU setting determines the maximum size of the network layer packet. The maximum size of the payload the link-layer frame can carry in turn limits the network layer MTU. For standard Ethernet frames this means an MTU of 1500 bytes. It should not be necessary to change the MTU when setting up a VLAN as the link-layer header is increased in size by 4 bytes to accommodate the 802.1Q tag. + </para> + <para> + At time of writing, <literal>connection.interface-name</literal> and <literal>vlan.interface-name</literal> have to be the same (if they are set). They must therefore be changed simultaneously using <application>nmcli</application>'s interactive mode. To change a VLAN connections name, issue commands as follows: + <screen>~]$ <command>nmcli con edit <replaceable>vlan-VLAN10</replaceable></command> +nmcli> <command>set vlan.interface-name <replaceable>superVLAN</replaceable></command> +nmcli> <command>set connection.interface-name <replaceable>superVLAN</replaceable></command> +nmcli> <command>save</command> +nmcli> <command>quit</command></screen> + </para> + <para> + The <application>nmcli</application> utility can be used to set and clear <literal>ioctl</literal> flags which change the way the 802.1Q code functions. The following VLAN flags are supported by <application>NetworkManager</application>: + <itemizedlist> + <listitem> + <para> +0x01 - reordering of output packet headers + </para> + </listitem> + <listitem> + <para> +0x02 - use GVRP protocol + </para> + </listitem> + <listitem> + <para> +0x04 - loose binding of the interface and its master + </para> + </listitem> + </itemizedlist> +The state of the VLAN is synchronized to the state of the parent or master interface (the interface or device on which the VLAN is created). If the parent interface is set to the <quote>down</quote> administrative state then all associated VLANs are set down and all routes are flushed from the routing table. Flag <literal>0x04</literal> enables a <firstterm>loose binding</firstterm> mode, in which only the operational state is passed from the parent to the associated VLANs, but the VLAN device state is not changed. +</para> +<para> + To set a VLAN flag, issue a command as follows: + <screen>~]$ <command>nmcli connection modify vlan-VLAN10 vlan.flags 1</command></screen> + </para> + <para> + See <xref linkend="sec-Using_the_NetworkManager_Command_Line_Tool_nmcli" /> for an introduction to <application>nmcli</application>. + </para> + + </section> + + <!--Topics, Reference--> + <section id="sec-Configure_802_1Q_VLAN_Tagging-additional_resources"> + +<title>Additional Resources</title> +<para> + The following sources of information provide additional resources regarding Network Teaming. + </para> + <section id="sec-Configure_802_1Q_VLAN_Tagging-docs-inst"> + <title>Installed Documentation</title> + <itemizedlist> + <listitem> + <para> + <filename>ip-link(8)</filename> man page — Describes the <application>ip</application> utility's network device configuration commands. + </para> + </listitem> + <listitem> + <para> + <filename>nmcli(1)</filename> man page — Describes <application>NetworkManager</application>'s command‐line tool. + </para> + </listitem> + <listitem> + <para> + <filename>nmcli-examples(5)</filename> man page — Gives examples of <application>nmcli</application> commands. + </para> + </listitem> + <listitem> + <para> + <filename>nm-settings(5)</filename> man page — Description of settings and parameters of <application>NetworkManager</application> connections. + </para> + </listitem> + +</itemizedlist> +</section> + +</section> + +</chapter> diff --git a/docs/guide/Configure_Host_Names.xml b/docs/guide/Configure_Host_Names.xml new file mode 100644 index 000000000..af50db9ed --- /dev/null +++ b/docs/guide/Configure_Host_Names.xml @@ -0,0 +1,158 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "Networking_Guide.ent"> +%BOOK_ENTITIES; +]> +<chapter id="ch-Configure_Host_Names"> + <title>Configure Host Names</title> + + <!-- Topics, Concepts --> + <section id="sec_Understanding_Host_Names"> + <title>Understanding Host Names</title> + <para> + There are three classes of <systemitem class="systemname">hostname</systemitem>: static, pretty, and transient. + </para> + <para> + The <quote>static</quote> host name is the traditional <systemitem class="systemname">hostname</systemitem>, which can be chosen by the user, and is stored in the <filename>/etc/hostname</filename> file. The <quote>transient</quote> <systemitem class="systemname">hostname</systemitem> is a dynamic host name maintained by the kernel. It is initialized to the static host name by default, whose value defaults to <quote>localhost</quote>. It can be changed by <systemitem class="protocol">DHCP</systemitem> or <systemitem class="protocol">mDNS</systemitem> at runtime. The <quote>pretty</quote> <systemitem class="systemname">hostname</systemitem> is a free-form UTF8 host name for presentation to the user. + <note> + <para> + A host name can be a free-form string up to 64 characters in length. However, Red Hat recommends that both static and transient names match the <firstterm>fully-qualified domain name</firstterm> (<acronym>FQDN</acronym>) used for the machine in <systemitem class="protocol">DNS</systemitem>, such as <systemitem class="domainname">host.example.com</systemitem>. It is also recommended that the static and transient names consists only of 7 bit ASCII lower-case characters, no spaces or dots, and limits itself to the format allowed for <systemitem class="protocol">DNS</systemitem> domain name labels, even though this is not a strict requirement. Older specifications do not permit the underscore, and so their use is not recommended.</para> + <para>The <application>hostnamectl</application> tool will enforce the following: Static and transient host names to consist of <literal>a-z</literal>, <literal>A-Z</literal>, <literal>0-9</literal>, <quote><literal>-</literal></quote>, <quote><literal>_</literal></quote> and <quote><literal>.</literal></quote> only, to not begin or end in a dot, and to not have two dots immediately following each other. The size limit of 64 characters is enforced. +</para> + </note> + </para> + <section id="sec-Recommended_Naming_Practices"> + <title>Recommended Naming Practices</title> + <para> + The Internet Corporation for Assigned Names and Numbers (ICANN) sometimes adds previously unregistered Top-Level Domains (such as <systemitem class="domainname">.yourcompany</systemitem>) to the public register. Therefore, Red Hat strongly recommends that you do not use a domain name that is not delegated to you, even on a private network, as this can result in a domain name that resolves differently depending on network configuration. As a result, network resources can become unavailable. Using domain names that are not delegated to you also makes DNSSEC more difficult to deploy and maintain, as domain name collisions require manual configuration to enable DNSSEC validation. See the <ulink url="http://www.icann.org/en/help/name-collision/faqs">ICANN FAQ on domain name collision</ulink> for more information on this issue. + </para> + </section> + </section> + <!-- Topics, Tasks --> + <section id="sec_Configuring_Host_Names_Using_hostnamectl"> + <title>Configuring Host Names Using hostnamectl</title> + <para> + The <application>hostnamectl</application> tool is provided for administering the three separate classes of host names in use on a given system.</para> + + <section id="sec_View_All_the_Host_Names"> + <title>View All the Host Names</title> + <para> + To view all the current host names, enter the following command: + <screen>~]$ <command>hostnamectl status</command></screen> + The <option>status</option> option is implied by default if no option is given. + </para> + </section> + <section id="sec_Set_All_the_Host_Names"> + <title>Set All the Host Names</title> + <para> + To set all the host names on a system, enter the following command as <systemitem class="username">root</systemitem>: + <screen>~]# <command>hostnamectl set-hostname <replaceable>name</replaceable></command></screen> + This will alter the pretty, static, and transient host names alike. The static and transient host names will be simplified forms of the pretty host name. Spaces will be replaced with <quote><literal>-</literal></quote> and special characters will be removed. + </para> + </section> + <section id="sec_Set_a_Particular_Host_Name"> + <title>Set a Particular Host Name</title> + <para> + To set a particular host name, enter the following command as <systemitem class="username">root</systemitem> with the relevant option: + <screen>~]# <command>hostnamectl set-hostname <replaceable>name</replaceable> <optional><replaceable>option</replaceable>...</optional></command></screen> + Where <replaceable>option</replaceable> is one or more of: <option>--pretty</option>, <option>--static</option>, and <option>--transient</option>. + </para> + <para> + If the <option>--static</option> or <option>--transient</option> options are used together with the <option>--pretty</option> option, the static and transient host names will be simplified forms of the pretty host name. Spaces will be replaced with <quote><literal>-</literal></quote> and special characters will be removed. If the <option>--pretty</option> option is not given, no simplification takes place.</para> + <para> + When setting a pretty host name, remember to use the appropriate quotation marks if the host name contains spaces or a single quotation mark. For example: + <screen>~]# <command>hostnamectl set-hostname "Stephen's notebook" --pretty</command></screen> + </para> + </section> + <section id="sec_Clear_a_Particular_Host_Name"> + <title>Clear a Particular Host Name</title> + <para> + To clear a particular host name and allow it to revert to the default, enter the following command as <systemitem class="username">root</systemitem> with the relevant option: + <screen>~]# <command>hostnamectl set-hostname <replaceable>""</replaceable> <optional><replaceable>option</replaceable>...</optional></command></screen> + Where <replaceable>""</replaceable> is a quoted empty string and where <replaceable>option</replaceable> is one or more of: <option>--pretty</option>, <option>--static</option>, and <option>--transient</option>. + </para> + </section> + <section id="sec_Changing_Host_Names_Remotely"> + <title>Changing Host Names Remotely</title> + <para> + To execute a <command>hostnamectl</command> command on a remote system, use the <option>-H, --host</option> option as follows: + <screen>~]# <command>hostnamectl set-hostname <option>-H</option> <optional><replaceable>username</replaceable></optional>@<replaceable>hostname</replaceable></command></screen> + Where <replaceable>hostname</replaceable> is the remote host you want to configure. The <replaceable>username</replaceable> is optional. The <application>hostnamectl</application> tool will use <systemitem class="protocol">SSH</systemitem> to connect to the remote system. + </para> + </section> + </section> + + <section id="sec-Configuring_Host_Names_Using_nmcli"> + <title>Configuring Host Names Using nmcli</title> + <para> + The <application>NetworkManager</application> tool <application>nmcli</application> can be used to query and set the static host name in the <filename>/etc/hostname</filename> file. Note that at time of writing, changing the host name in this way will not be noticed by <application>hostnamectl</application>.</para> + <para> + To query the static host name, issue the following command: + <screen>~]$ <command>nmcli general hostname</command></screen> + To set the static host name to <replaceable>my-server</replaceable>, issue the following command as <systemitem class="username">root</systemitem>: + <screen>~]# <command>nmcli general hostname <replaceable>my-server</replaceable></command></screen> + To force <application>hostnamectl</application> to notice the change in the static host name, restart <systemitem class="daemon">hostnamed</systemitem> as <systemitem class="username">root</systemitem>: + <screen>~]# <command>systemctl restart systemd-hostnamed</command></screen> + </para> + </section> + + <!--Topics, Reference--> + <section id="sec-additional_resources"> + <title>Additional Resources</title> + <para> + The following sources of information provide additional resources regarding <application>hostnamectl</application>. + </para> + <section id="sec-hostnamectl-docs-inst"> + <title>Installed Documentation</title> + <itemizedlist> + <listitem> + <para> + <filename>hostnamectl(1)</filename> man page — Describes <application>hostnamectl</application> including the commands and command options. + </para> + </listitem> + <listitem> + <para> + <filename>hostname(1)</filename> man page — Contains an explanation of the <command>hostname</command> and <command>domainname</command> commands. + </para> + </listitem> + <listitem> + <para> + <filename>hostname(5)</filename> man page — Contains an explanation of the host name file, its contents, and use. + </para> + </listitem> + <listitem> + <para> + <filename>hostname(7)</filename> man page — Contains an explanation of host name resolution. + </para> + </listitem> + <listitem> + <para> + <filename>machine-info(5)</filename> man page — Describes the local machine information file and the environment variables it contains.</para> + </listitem> + <listitem> + <para> + <filename>machine-id(5)</filename> man page — Describes the local machine ID configuration file.</para> + </listitem> + <listitem> + <para> + <filename>systemd-hostnamed.service(8)</filename> man page — Describes the <systemitem class="daemon">systemd-hostnamed</systemitem> system service used by <application>hostnamectl</application>.</para> + </listitem> + </itemizedlist> + </section> +<section id="sec-hostnamectl-Online_Documentation"> + <title>Online Documentation</title> +<variablelist> + <varlistentry> +<term><ulink url="http://www.freedesktop.org/wiki/Software/systemd/hostnamed"/></term> +<listitem> +<para> +Information on <systemitem class="daemon">systemd-hostnamed</systemitem>. +</para> +</listitem> +</varlistentry> +</variablelist> +</section> +</section> + + +</chapter> diff --git a/docs/guide/Configure_Network_Bonding.xml b/docs/guide/Configure_Network_Bonding.xml new file mode 100644 index 000000000..c807d02d3 --- /dev/null +++ b/docs/guide/Configure_Network_Bonding.xml @@ -0,0 +1,1472 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "Networking_Guide.ent"> +%BOOK_ENTITIES; +]> +<chapter id="ch-Configure_Network_Bonding"> + <title>Configure Network Bonding</title> + +<para> + Fedora allows administrators to bind multiple network interfaces together into a single, bonded, channel. Channel bonding enables two or more network interfaces to act as one, simultaneously increasing the bandwidth and providing redundancy. +</para> + + <warning> + <para> + The use of direct cable connections without network switches is not supported for bonding. The failover mechanisms described here will not work as expected without the presence of network switches. + </para> +</warning> + + <note> + <para> + The active-backup, balance-tlb and balance-alb modes do not require any specific configuration of the switch. Other bonding modes require configuring the switch to aggregate the links. For example, a Cisco switch requires EtherChannel for Modes 0, 2, and 3, but for Mode 4 LACP and EtherChannel are required. See the documentation supplied with your switch and see <ulink url="https://www.kernel.org/doc/Documentation/networking/bonding.txt">https://www.kernel.org/doc/Documentation/networking/bonding.txt</ulink>.<!--the <filename>bonding.txt</filename> file in the <package>kernel-doc</package> package (see <xref linkend="sec-Configure_Network_Bonding-docs-installable"/>)--> + </para> + </note> + + <section id="sec-Bond-Understanding_the_Default_Behavior_of_Master_and_Slave_Interfaces"> +<title>Understanding the Default Behavior of Master and Slave Interfaces</title> +<para> +When controlling bonded slave interfaces using the <systemitem class="daemon">NetworkManager</systemitem> daemon, and especially when fault finding, keep the following in mind: +<orderedlist> + <listitem> + <para> + Starting the master interface does not automatically start the slave interfaces. + </para> + </listitem> + <listitem> + <para> + Starting a slave interface always starts the master interface. + </para> + </listitem> + <listitem> + <para> + Stopping the master interface also stops the slave interfaces. + </para> + </listitem> + <listitem> + <para> + A master without slaves can start static <systemitem class="protocol">IP</systemitem> connections. + </para> + </listitem> + <listitem> + <para> + A master without slaves waits for slaves when starting <systemitem class="protocol">DHCP</systemitem> connections. + </para> + </listitem> + <listitem> + <para> + A master with a <systemitem class="protocol">DHCP</systemitem> connection waiting for slaves completes when a slave with a carrier is added. + </para> + </listitem> + <listitem> + <para> + A master with a <systemitem class="protocol">DHCP</systemitem> connection waiting for slaves continues waiting when a slave without a carrier is added. + </para> + </listitem> +</orderedlist> +</para> +</section> + + <section id="sec-Creating_a_Bond_Connection_Using_a_GUI"> + <title>Creating a Bond Connection Using a GUI</title> + <para>You can use the GNOME <application>control-center</application> utility to direct <application>NetworkManager</application> to create a Bond from two or more Wired or InfiniBand connections. It is not necessary to create the connections to be bonded first. They can be configured as part of the process to configure the bond. You must have the MAC addresses of the interfaces available in order to complete the configuration process.</para> + <section id="sec-Establishing_a_Bond_Connection"> + <title>Establishing a Bond Connection</title> + <procedure + id="procedure-Adding_a_New_Bond_Connection"> + <title>Adding a New Bond Connection</title> + <para>You can configure a Bond connection by opening the <guilabel>Network</guilabel> window, clicking the plus symbol, and selecting <guilabel>Bond</guilabel> from the list.</para> + + <step> + <para>Press the <keycap>Super</keycap> key to enter the Activities Overview, type <command>control network</command> and then press <keycap>Enter</keycap>. The <application>Network</application> settings tool appears.</para> + </step> + + <step> + <para>Click the plus symbol to open the selection list. Select <guilabel>Bond</guilabel>. The <guilabel>Editing Bond connection <replaceable>1</replaceable></guilabel> window appears.</para> + </step> + <step> + <para>On the <guilabel>Bond</guilabel> tab, click <guibutton>Add</guibutton> and select the type of interface you want to use with the bond connection. Click the <guibutton>Create</guibutton> button. Note that the dialog to select the slave type only comes up when you create the first slave; after that, it will automatically use that same type for all further slaves.</para> + </step> + <step> + <para>The <guilabel>Editing bond0 slave 1</guilabel> window appears. Use the <guilabel>Device MAC address</guilabel> drop-down menu to select the MAC address of the interface to be bonded. The first slave's MAC address will be used as the MAC address for the bond interface. If required, enter a clone MAC address to be used as the bond's MAC address. Click the <guibutton>Save</guibutton> button.</para> + </step> + <step> + <para>The name of the bonded slave appears in the <guilabel>Bonded connections</guilabel> window. Click the <guibutton>Add</guibutton> button to add further slave connections.</para> + </step> + <step><para>Review and confirm the settings and then click the <guilabel>Save</guilabel> button.</para> + </step> + <step> + <para>Edit the bond-specific settings by referring to <xref linkend="sec-Configuring_the_Bond_Tab"/> below.</para> + </step> + </procedure> + + <procedure + id="procedure-Editing_an_Existing_Bond_Connection"> + <title>Editing an Existing Bond Connection</title> + <para>Follow these steps to edit an existing bond connection.</para> + <step> + <para>Press the <keycap>Super</keycap> key to enter the Activities Overview, type <command>control network</command> and then press <keycap>Enter</keycap>. The <application>Network</application> settings tool appears.</para> + </step> + + <step> + <para>Select the connection you want to edit and click the <guilabel>Options</guilabel> button.</para> + </step> + <step> + <para>Select the <guilabel>General</guilabel> tab.</para> + </step> + <step> + <para>Configure the connection name, auto-connect behavior, and availability settings.</para> + <para>Five settings in the <guilabel>Editing</guilabel> dialog are common to all connection types, see the <guilabel>General</guilabel> tab: + </para> + <itemizedlist> + <listitem> + <para> + <guilabel>Connection name</guilabel> — Enter a descriptive name for your network connection. This name will be used to list this connection in the menu of the <guilabel>Network</guilabel> window. + </para> + </listitem> + <listitem> + <para> + <guilabel>Automatically connect to this network when it is available</guilabel> — Select this box if you want <application>NetworkManager</application> to auto-connect to this connection when it is available. See <xref linkend="sec-Connecting_to_a_Network_Automatically"/> for more information. + </para> + </listitem> + <listitem> + <para> + <guilabel>All users may connect to this network</guilabel> — Select this box to create a connection available to all users on the system. Changing this setting may require root privileges. See <xref linkend="sec-System-wide_and_Private_Connection_Profiles"/> for details. + </para> + </listitem> + <listitem> + <para> + <guilabel>Automatically connect to VPN when using this connection</guilabel> — Select this box if you want <application>NetworkManager</application> to auto-connect to a VPN connection when it is available. Select the VPN from the drop-down menu. + </para> + </listitem> + <listitem> + <para> + <guilabel>Firewall Zone</guilabel> — Select the firewall zone from the drop-down menu. + </para> + </listitem> + </itemizedlist> + </step> + + <step> + <para>Edit the bond-specific settings by referring to <xref linkend="sec-Configuring_the_Bond_Tab"/> below.</para> + </step> + </procedure> + <bridgehead + id="bh-Saving_Your_New_or_Modified_Connection_and_Making_Further_Configurations-bond">Saving Your New (or Modified) Connection and Making Further Configurations</bridgehead> + + <para>Once you have finished editing your bond connection, click the <guibutton>Save</guibutton> button to save your customized configuration. If the profile was in use while being edited, power cycle the connection to make <application>NetworkManager</application> apply the changes. If the profile is OFF, set it to ON. See <xref + linkend="sec-Connecting_to_a_Network_Using_a_GUI"/> for information on using your new or altered connection.</para> + <para>You can further configure an existing connection by selecting it in the <guilabel>Network</guilabel> window and clicking <guilabel>Options</guilabel> to return to the <guilabel>Editing</guilabel> dialog.</para> + <para>Then, to configure:</para> + <itemizedlist> + + <listitem> + <para><systemitem class="protocol">IPv4</systemitem> settings for the connection, click the <guilabel>IPv4 Settings</guilabel> tab and proceed to <xref + linkend="sec-Configuring_IPv4_Settings"/>; or, + </para> + </listitem> + <listitem> + <para><systemitem class="protocol">IPv6</systemitem> settings for the connection, click the <guilabel>IPv6 Settings</guilabel> tab and proceed to <xref + linkend="sec-Configuring_IPv6_Settings"/>. + </para> + </listitem> + </itemizedlist> + + <section id="sec-Configuring_the_Bond_Tab"> + <title>Configuring the Bond Tab</title> + <para>If you have already added a new bond connection (refer to <xref + linkend="procedure-Adding_a_New_Bond_Connection"/> for instructions), you can edit the <guilabel>Bond</guilabel> tab to set the load sharing mode and the type of link monitoring to use to detect failures of a slave connection.</para> + <variablelist> + <varlistentry> + <term> + <guilabel>Mode</guilabel> + </term> + <listitem> + + <para>The mode that is used to share traffic over the slave connections which make up the bond. The default is <guilabel>Round-robin</guilabel>. Other load sharing modes, such as <systemitem class="protocol">802.3ad</systemitem>, can be selected by means of the drop-down list.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Link Monitoring</guilabel> + </term> + <listitem> + <para>The method of monitoring the slaves ability to carry network traffic.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>The following modes of load sharing are selectable from the <guilabel>Mode</guilabel> drop-down list:</para> + <variablelist> + + <varlistentry> + <term> + <guilabel>Round-robin</guilabel> + </term> + <listitem> + <para>Sets a round-robin policy for fault tolerance and load balancing. Transmissions are received and sent out sequentially on each bonded slave interface beginning with the first one available. This mode might not work behind a bridge with virtual machines without additional switch configuration.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <guilabel>Active backup</guilabel> + </term> + <listitem> + <para>Sets an active-backup policy for fault tolerance. Transmissions are received and sent out via the first available bonded slave interface. Another bonded slave interface is only used if the active bonded slave interface fails. Note that this is the only mode available for bonds of InfiniBand devices.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <guilabel>XOR</guilabel> + </term> + <listitem> + <para>Sets an XOR (exclusive-or) policy. Transmissions are based on the selected hash policy. The default is to derive a hash by XOR of the source and destination MAC addresses multiplied by the modulo of the number of slave interfaces. In this mode traffic destined for specific peers will always be sent over the same interface. As the destination is determined by the MAC addresses this method works best for traffic to peers on the same link or local network. If traffic has to pass through a single router then this mode of traffic balancing will be suboptimal.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <guilabel>Broadcast</guilabel> + </term> + <listitem> + <para>Sets a broadcast policy for fault tolerance. All transmissions are sent on all slave interfaces. This mode might not work behind a bridge with virtual machines without additional switch configuration.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <guilabel>802.3ad</guilabel> + </term> + <listitem> + <para>Sets an IEEE <systemitem class="protocol">802.3ad</systemitem> dynamic link aggregation policy. Creates aggregation groups that share the same speed and duplex settings. Transmits and receives on all slaves in the active aggregator. Requires a network switch that is <systemitem class="protocol">802.3ad</systemitem> compliant.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <guilabel>Adaptive transmit load balancing</guilabel> + </term> + <listitem> + <para>Sets an adaptive Transmit Load Balancing (TLB) policy for fault tolerance and load balancing. The outgoing traffic is distributed according to the current load on each slave interface. Incoming traffic is received by the current slave. If the receiving slave fails, another slave takes over the MAC address of the failed slave. This mode is only suitable for local addresses known to the kernel bonding module and therefore cannot be used behind a bridge with virtual machines.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <guilabel>Adaptive load balancing</guilabel> + </term> + <listitem> + <para>Sets an Adaptive Load Balancing (ALB) policy for fault tolerance and load balancing. Includes transmit and receive load balancing for <systemitem class="protocol">IPv4</systemitem> traffic. Receive load balancing is achieved through <systemitem class="protocol">ARP</systemitem> negotiation. This mode is only suitable for local addresses known to the kernel bonding module and therefore cannot be used behind a bridge with virtual machines.</para> + </listitem> + </varlistentry> + + </variablelist> + <para>The following types of link monitoring can be selected from the <guilabel>Link Monitoring</guilabel> drop-down list. It is a good idea to test which channel bonding module parameters work best for your bonded interfaces.</para> + + <variablelist> + <varlistentry> + <term> + <guilabel>MII (Media Independent Interface)</guilabel> + </term> + <listitem> + <para>The state of the carrier wave of the interface is monitored. This can be done by querying the driver, by querying MII registers directly, or by using <application>ethtool</application> to query the device. Three options are available:</para> + + <variablelist> + <varlistentry> + <term> + <guilabel>Monitoring Frequency</guilabel> + </term> + <listitem> + <para>The time interval, in milliseconds, between querying the driver or MII registers.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Link up delay</guilabel> + </term> + <listitem> + <para>The time in milliseconds to wait before attempting to use a link that has been reported as up. This delay can be used if some gratuitous <systemitem class="protocol">ARP</systemitem> requests are lost in the period immediately following the link being reported as <quote>up</quote>. This can happen during switch initialization for example.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Link down delay</guilabel> + </term> + <listitem> + <para>The time in milliseconds to wait before changing to another link when a previously active link has been reported as <quote>down</quote>. This delay can be used if an attached switch takes a relatively long time to change to backup mode.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + </variablelist> + + <variablelist> + <varlistentry> + <term> + <guilabel>ARP</guilabel> + </term> + <listitem> + <para>The address resolution protocol (<systemitem class="protocol">ARP</systemitem>) is used to probe one or more peers to determine how well the link-layer connections are working. It is dependent on the device driver providing the transmit start time and the last receive time.</para> + <para>Two options are available:</para> + + <variablelist> + <varlistentry> + <term> + <guilabel>Monitoring Frequency</guilabel> + </term> + <listitem> + <para>The time interval, in milliseconds, between sending <systemitem class="protocol">ARP</systemitem> requests.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>ARP targets</guilabel> + </term> + <listitem> + <para>A comma separated list of <systemitem class="protocol">IP</systemitem> addresses to send <systemitem class="protocol">ARP</systemitem> requests to.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + </variablelist> + </section> + + </section> + +</section> + +<section id="sec-Network_Bonding_Using_the_Command_Line_Interface"> + <title>Using the Command Line Interface (CLI)</title> + <para> + A bond is created using the <filename>bonding</filename> kernel module and a special network interface called a <firstterm>channel bonding interface</firstterm>. + </para> + + <section id="sec-Check_if_Bonding_Kernel_Module_is_Installed"> + <title>Check if Bonding Kernel Module is Installed</title> + <para> + In Fedora, the bonding module is not loaded by default. You can load the module by issuing the following command as <systemitem class="username">root</systemitem>: + <screen>~]# <command>modprobe --first-time bonding</command></screen> + This activation will not persist across system restarts. See the <citetitle pubwork="book">&MAJOROSVER; System Administrator's Guide</citetitle> for an explanation of persistent module loading. Note that given a correct configuration file using the <command>BONDING_OPTS</command> directive, the bonding module will be loaded as required and therefore does not need to be loaded separately.</para> + <para> +To display information about the module, issue the following command: +<screen>~]$ <command>modinfo bonding</command></screen> +See the <filename>modprobe(8)</filename> man page for more command options. + </para> + </section> + + <section id="sec-Create_a_Channel_Bonding_Interface"> + <title>Create a Channel Bonding Interface</title> + <para> + To create a channel bonding interface, create a file in the <filename class="directory">/etc/sysconfig/network-scripts/</filename> directory called <filename>ifcfg-bond<replaceable>N</replaceable></filename>, replacing <replaceable>N</replaceable> with the number for the interface, such as <filename>0</filename>. + </para> + <para> + The contents of the file can be based on a configuration file for whatever type of interface is getting bonded, such as an Ethernet interface. The essential differences are that the <option>DEVICE</option> directive is <option>bond<replaceable>N</replaceable></option>, replacing <replaceable>N</replaceable> with the number for the interface, and <command>TYPE=Bond</command>. In addition, set <command>BONDING_MASTER=yes</command>. + </para> + + <example id="ex-Example_ifcfg-bond0_Interface_Configuration_File"> + <title>Example ifcfg-bond0 Interface Configuration File</title> + <para> + An example of a channel bonding interface. + </para> + <programlisting>DEVICE=bond0 +NAME=bond0 +TYPE=Bond +BONDING_MASTER=yes +IPADDR=192.168.1.1 +PREFIX=24 +ONBOOT=yes +BOOTPROTO=none +BONDING_OPTS="<replaceable>bonding parameters separated by spaces</replaceable>"</programlisting> +<para> +The NAME directive is useful for naming the connection profile in <application>NetworkManager</application>. ONBOOT says whether the profile should be started when booting (or more generally, when auto-connecting a device).</para> + </example> + <important> + <title>Put all Bonding Module Parameters in ifcfg-bondN Files</title> + <para> + Parameters for the bonding kernel module must be specified as a space-separated list in the <option>BONDING_OPTS="<replaceable>bonding parameters</replaceable>"</option> directive in the <filename>ifcfg-bond<replaceable>N</replaceable></filename> interface file. Do <emphasis>not</emphasis> specify options for the bonding device in <filename>/etc/modprobe.d/<replaceable>bonding</replaceable>.conf</filename>, or in the deprecated <filename>/etc/modprobe.conf</filename> file.</para> + <para>The <option>max_bonds</option> parameter is not interface specific and should not be set when using <filename>ifcfg-bond<replaceable>N</replaceable></filename> files with the <command>BONDING_OPTS</command> directive as this directive will cause the network scripts to create the bond interfaces as required.</para> + <para> + For further instructions and advice on configuring the bonding module and to view the list of bonding parameters, see <xref linkend="sec-Using_Channel_Bonding"/>. + </para> + </important> + </section> + + <section id="sec-Creating_SLAVE_Interfaces"> + <title>Creating SLAVE Interfaces</title> + <para> + The channel bonding interface is the <quote>master</quote> and the interfaces to be bonded are referred to as the <quote>slaves</quote>. After the channel bonding interface is created, the network interfaces to be bound together must be configured by adding the <option>MASTER</option> and <option>SLAVE</option> directives to the configuration files of the slaves. The configuration files for each of the slave interfaces can be nearly identical. + </para> + <example id="ex-Example_Slave_Interface_Configuration_File"> + <title>Example Slave Interface Configuration File</title> + + <para> + For example, if two Ethernet interfaces are being channel bonded, <literal>eth0</literal> and <literal>eth1</literal>, they can both look like the following example: + </para> + <programlisting>DEVICE=eth<replaceable>N</replaceable> +NAME=bond0-slave +TYPE=Ethernet +BOOTPROTO=none +ONBOOT=yes +MASTER=bond0 +SLAVE=yes</programlisting> + <para> + In this example, replace <replaceable>N</replaceable> with the numerical value for the interface. Note that if more than one profile or configuration file exists with ONBOOT=yes for an interface, they may race with each other and a plain TYPE=Ethernet profile may be activated instead of a bond slave. + </para> + </example> + </section> + + <section id="sec-Activating_a_Channel_Bond"> + <title>Activating a Channel Bond</title> + <para> + To activate a bond, bring up all the slaves. As <systemitem class="username">root</systemitem>, issue the following commands: + + <screen>~]# <command>ifup ifcfg-eth0</command> +Connection successfully activated (D-Bus active path: /org/freedesktop/NetworkManager/ActiveConnection/7)</screen> + <screen>~]# <command>ifup ifcfg-eth1</command> +Connection successfully activated (D-Bus active path: /org/freedesktop/NetworkManager/ActiveConnection/8)</screen> +</para> +<para> +Note that if editing interface files for interfaces which are currently <quote>up</quote>, set them down first as follows: +<synopsis>ifdown eth<replaceable>N</replaceable></synopsis> +Then when complete, bring up all the slaves, which will bring up the bond (provided it was not set <quote>down</quote>). + </para> + <para> + To make <application>NetworkManager</application> aware of the changes, issue a command for every changed interface as <systemitem class="username">root</systemitem>: + <screen>~]# <command>nmcli con load /etc/sysconfig/network-scripts/ifcfg-<replaceable>device</replaceable></command></screen> + Alternatively, to reload all interfaces: +<screen>~]# <command>nmcli con reload</command></screen> + The default behavior is for <application>NetworkManager</application> not to be aware of the changes and to continue using the old configuration data. This is set by the <option>monitor-connection-files</option> option in the <filename>NetworkManager.conf</filename> file. See the <filename>NetworkManager.conf(5)</filename> manual page for more information. + </para> + + <para> + To view the status of the bond interface, issue the following command: + <screen>~]# <command>ip link show</command> +1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT + link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 +2: eth0: <BROADCAST,MULTICAST,SLAVE,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master bond0 state UP mode DEFAULT qlen 1000 + link/ether 52:54:00:e9:ce:d2 brd ff:ff:ff:ff:ff:ff +3: eth1: <BROADCAST,MULTICAST,SLAVE,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master bond0 state UP mode DEFAULT qlen 1000 + link/ether 52:54:00:38:a6:4c brd ff:ff:ff:ff:ff:ff +4: bond0: <BROADCAST,MULTICAST,MASTER,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP mode DEFAULT + link/ether 52:54:00:38:a6:4c brd ff:ff:ff:ff:ff:ff</screen> + </para> + </section> + + + + <section id="sec-Creating_Multiple_Bonds"> + <title>Creating Multiple Bonds</title> + <para> + In &MAJOROSVER;, for each bond a channel bonding interface is created including the <command>BONDING_OPTS</command> directive. This configuration method is used so that multiple bonding devices can have different configurations. To create multiple channel bonding interfaces, proceed as follows: + + <itemizedlist> + <listitem> + <para> + Create multiple <filename>ifcfg-bond<replaceable>N</replaceable></filename> files with the <command>BONDING_OPTS</command> directive; this directive will cause the network scripts to create the bond interfaces as required. + </para> + </listitem> + <listitem> + <para> + Create, or edit existing, interface configuration files to be bonded and include the <command>SLAVE</command> directive. + </para> + </listitem> + <listitem> + <para> + Assign the interfaces to be bonded, the slave interfaces, to the channel bonding interfaces by means of the <command>MASTER</command> directive. + </para> + </listitem> + </itemizedlist> + </para> + + <example id="ex-Example-multiple-bondN_interface_configuration_files"> + <title>Example multiple ifcfg-bondN interface configuration files</title> + + <para> + The following is an example of a channel bonding interface configuration file: + <programlisting>DEVICE=bondN +NAME=bondN +TYPE=Bond +BONDING_MASTER=yes +IPADDR=192.168.1.1 +PREFIX=24 +ONBOOT=yes +BOOTPROTO=none +BONDING_OPTS="<replaceable>bonding parameters separated by spaces</replaceable>"</programlisting> +</para> + <para> + In this example, replace <replaceable>N</replaceable> with the number for the bond interface. For example, to create two bonds create two configuration files, <filename>ifcfg-bond0</filename> and <filename>ifcfg-bond1</filename>, with appropriate <systemitem class="protocol">IP</systemitem> addresses. + </para> + </example> + + <para> + Create the interfaces to be bonded as per <xref linkend="ex-Example_Slave_Interface_Configuration_File" /> and assign them to the bond interfaces as required using the <command>MASTER=bond<replaceable>N</replaceable></command> directive. For example, continuing on from the example above, if two interfaces per bond are required, then for two bonds create four interface configuration files and assign the first two using <command>MASTER=bond<replaceable>0</replaceable></command> and the next two using <command>MASTER=bond<replaceable>1</replaceable></command>.</para> + </section> + + <section id="sec-Configuring_a_VLAN_over_a_Bond"> + <title>Configuring a VLAN over a Bond</title> + + <para> + This section will show configuring a VLAN over a bond consisting of two Ethernet links between a server and an Ethernet switch. The switch has a second bond to another server. Only the configuration for the first server will be shown as the other is essentially the same apart from the <systemitem class="protocol">IP</systemitem> addresses.</para> + <warning> + <para> + The use of direct cable connections without network switches is not supported for bonding. The failover mechanisms described here will not work as expected without the presence of network switches. + </para> +</warning> + + <note> + <para> + The active-backup, balance-tlb and balance-alb modes do not require any specific configuration of the switch. Other bonding modes require configuring the switch to aggregate the links. For example, a Cisco switch requires EtherChannel for Modes 0, 2, and 3, but for Mode 4 LACP and EtherChannel are required. See the documentation supplied with your switch and see <ulink url="https://www.kernel.org/doc/Documentation/networking/bonding.txt">https://www.kernel.org/doc/Documentation/networking/bonding.txt</ulink><!--the <filename>bonding.txt</filename> file in the <package>kernel-doc</package> package (see <xref linkend="s1-kernel-modules-additional-resources"/>)-->. + </para> + </note> + +<para> +Check the available interfaces on the server: +<screen>~]$ <command>ip addr</command><![CDATA[ +1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN + link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 + inet 127.0.0.1/8 scope host lo + inet6 ::1/128 scope host + valid_lft forever preferred_lft forever +2: eth0: <BROADCAST,MULTICAST> mtu 1500 qdisc pfifo_fast state DOWN qlen 1000 + link/ether 52:54:00:19:28:fe brd ff:ff:ff:ff:ff:ff +3: eth1: <BROADCAST,MULTICAST> mtu 1500 qdisc pfifo_fast state DOWN qlen 1000 + link/ether 52:54:00:f6:63:9a brd ff:ff:ff:ff:ff:ff]]></screen> +</para> + +<procedure id="proc-Configuring_the_Interfaces_on_the_Workstation"> +<title>Configuring the Interfaces on the Server</title> + + <step> +<para> + Configure a slave interface using <literal>eth0</literal>: + <screen>~]# <command>vi /etc/sysconfig/network-scripts/ifcfg-eth0</command> +NAME=bond0-slave0 +DEVICE=eth0 +TYPE=Ethernet +BOOTPROTO=none +ONBOOT=yes +MASTER=bond0 +SLAVE=yes</screen> +The use of the NAME directive is optional. It is for display by a GUI interface, such as <application>nm-connection-editor</application>. +</para> +</step> + +<step> +<para> + Configure a slave interface using <literal>eth1</literal>: + <screen>~]# <command>vi /etc/sysconfig/network-scripts/ifcfg-eth1</command> +NAME=bond0-slave1 +DEVICE=eth1 +TYPE=Ethernet +BOOTPROTO=none +ONBOOT=yes +MASTER=bond0 +SLAVE=yes</screen> +The use of the NAME directive is optional. It is for display by a GUI interface, such as <application>nm-connection-editor</application>. +</para> +</step> + +<step> + <para> + Configure a channel bonding interface <literal>ifcfg-bond0</literal>: + <screen>~]# <command>vi /etc/sysconfig/network-scripts/ifcfg-bond0</command> +NAME=bond0 +DEVICE=bond0 +BONDING_MASTER=yes +TYPE=Bond +IPADDR=192.168.100.100 +NETMASK=255.255.255.0 +ONBOOT=yes +BOOTPROTO=none +BONDING_OPTS="mode=active-backup miimon=100"</screen> +The use of the NAME directive is optional. It is for display by a GUI interface, such as <application>nm-connection-editor</application>. In this example MII is used for link monitoring, see the <xref linkend="s3-modules-bonding-directives" /> section for more information on link monitoring. + </para> + </step> + + <step> + <para> + Check the status of the interfaces on the server: + <screen>~]$ <command>ip addr</command><![CDATA[ +1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN + link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 + inet 127.0.0.1/8 scope host lo + inet6 ::1/128 scope host + valid_lft forever preferred_lft forever +2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP qlen 1000 + link/ether 52:54:00:19:28:fe brd ff:ff:ff:ff:ff:ff + inet6 fe80::5054:ff:fe19:28fe/64 scope link + valid_lft forever preferred_lft forever +3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP qlen 1000 + link/ether 52:54:00:f6:63:9a brd ff:ff:ff:ff:ff:ff + inet6 fe80::5054:ff:fef6:639a/64 scope link + valid_lft forever preferred_lft forever]]></screen> + </para> + </step> + + </procedure> + + <procedure id="proc-Resolving_Conflicts_with_Interfaces"> + <title>Resolving Conflicts with Interfaces</title> +<para> + The interfaces configured as slaves should not have <systemitem class="protocol">IP</systemitem> addresses assigned to them apart from the <systemitem class="protocol">IPv6</systemitem> link-local addresses (starting <literal>fe80</literal>). If you have an unexpected <systemitem class="protocol">IP</systemitem> address, then there may be another configuration file with ONBOOT set to <literal>yes</literal>.</para> + <step> + <para> + If this occurs, issue the following command to list all <filename>ifcfg</filename> files that may be causing a conflict: +<screen>~]$ <command>grep -r "ONBOOT=yes" /etc/sysconfig/network-scripts/ | cut -f1 -d":" | xargs grep -E "IPADDR|SLAVE"</command> +/etc/sysconfig/network-scripts/ifcfg-lo:IPADDR=127.0.0.1</screen> +The above shows the expected result on a new installation. Any file having both the ONBOOT directive as well as the IPADDR or SLAVE directive will be displayed. For example, if the <literal>ifcfg-eth1</literal> file was incorrectly configured, the display might look similar to the following: +<screen>~]# <command>grep -r "ONBOOT=yes" /etc/sysconfig/network-scripts/ | cut -f1 -d":" | xargs grep -E "IPADDR|SLAVE"</command> +/etc/sysconfig/network-scripts/ifcfg-lo:IPADDR=127.0.0.1 +/etc/sysconfig/network-scripts/ifcfg-eth1:SLAVE=yes +/etc/sysconfig/network-scripts/ifcfg-eth1:IPADDR=192.168.55.55</screen></para> +</step> +<step> +<para> +Any other configuration files found should be moved to a different directory for backup, or assigned to a different interface by means of the HWADDR directive. After resolving any conflict set the interfaces <quote>down</quote> and <quote>up</quote> again or restart the network service as <systemitem class="username">root</systemitem>: +<screen>~]# <command>systemctl restart network</command> +Shutting down interface bond0: [ OK ] +Shutting down loopback interface: [ OK ] +Bringing up loopback interface: [ OK ] +Bringing up interface bond0: Determining if ip address 192.168.100.100 is already in use for device bond0... + [ OK ]</screen> +If you are using <application>NetworkManager</application>, you might need to restart it at this point to make it forget the unwanted <systemitem class="protocol">IP</systemitem> address. As <systemitem class="username">root</systemitem>: +<screen>~]# <command>systemctl restart NetworkManager</command></screen> + </para> + </step> + + </procedure> + + +<procedure id="proc-Checking_the_bond_on_the_Server"> + <title>Checking the bond on the Server</title> + +<step> +<para> +Bring up the bond on the server as <systemitem class="username">root</systemitem>: +<screen>~]# <command>ifup /etc/sysconfig/network-scripts/ifcfg-bond0</command> +Determining if ip address 192.168.100.100 is already in use for device bond0...</screen> +</para> +</step> + + <step> + <para> + Check the status of the interfaces on the server: + <screen>~]$ <command>ip addr</command> +1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN + link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 + inet 127.0.0.1/8 scope host lo + inet6 ::1/128 scope host + valid_lft forever preferred_lft forever +2: eth0: <BROADCAST,MULTICAST,SLAVE,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast <computeroutput>master bond0 state UP</computeroutput> qlen 1000 + link/ether 52:54:00:19:28:fe brd ff:ff:ff:ff:ff:ff +3: eth1: <BROADCAST,MULTICAST,SLAVE,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast <computeroutput>master bond0 state UP</computeroutput> qlen 1000 + link/ether 52:54:00:f6:63:9a brd ff:ff:ff:ff:ff:ff +4: bond0: <BROADCAST,MULTICAST,<computeroutput>MASTER,UP</computeroutput>,LOWER_UP> mtu 1500 qdisc noqueue state UP + link/ether 52:54:00:19:28:fe brd ff:ff:ff:ff:ff:ff + inet 192.168.100.100/24 brd 192.168.100.255 scope global bond0 + inet6 fe80::5054:ff:fe19:28fe/64 scope link + valid_lft forever preferred_lft forever</screen> + Notice that <literal>eth0</literal> and <literal>eth1</literal> have <computeroutput>master bond0 state UP</computeroutput> and <literal>bond0</literal> has status of <computeroutput>MASTER,UP</computeroutput>. + </para> + </step> + + <step> + <para> +View the bond configuration details: + <screen>~]$ <command>cat /proc/net/bonding/bond0</command> +Ethernet Channel Bonding Driver: v3.6.0 (September 26, 2009) + +Bonding Mode: transmit load balancing +Primary Slave: None +Currently Active Slave: eth0 +MII Status: up +MII Polling Interval (ms): 100 +Up Delay (ms): 0 +Down Delay (ms): 0 + +Slave Interface: eth0 +MII Status: up +Speed: 100 Mbps +Duplex: full +Link Failure Count: 0 +Permanent HW addr: 52:54:00:19:28:fe +Slave queue ID: 0 + +Slave Interface: eth1 +MII Status: up +Speed: 100 Mbps +Duplex: full +Link Failure Count: 0 +Permanent HW addr: 52:54:00:f6:63:9a +Slave queue ID: 0</screen> +</para> +</step> + +<step> +<para> +Check the routes on the server: +<screen>~]$ <command>ip route</command> +192.168.100.0/24 dev bond0 proto kernel scope link src 192.168.100.100 +169.254.0.0/16 dev bond0 scope link metric 1004</screen> + </para> + </step> + + </procedure> + +<procedure id="proc-Configuring_the_VLAN_on_the_Server"> +<title>Configuring the VLAN on the Server</title> + + +<note> +<para> +A VLAN slave cannot be configured on a bond with the <option>fail_over_mac=follow</option> option, because the VLAN virtual device cannot change its MAC address to match the parent's new MAC address. In such a case, traffic would still be sent with the now incorrect source MAC address.</para> +<para> +Some older network interface cards, loopback interfaces, Wimax cards, and some Infiniband devices, are said to be <firstterm>VLAN challenged</firstterm>, meaning they cannot support VLANs. This is usually because the devices cannot cope with VLAN headers and the larger MTU size associated with VLANs. +</para> +</note> + +<step> +<para> +Create a VLAN interface file <literal>bond0.192</literal>: +<screen>~]# <command>vi /etc/sysconfig/network-scripts/ifcfg-bond0.192</command> +DEVICE=bond0.192 +NAME=bond0.192 +BOOTPROTO=none +ONPARENT=yes +IPADDR=192.168.10.1 +NETMASK=255.255.255.0 +VLAN=yes</screen> +</para> +</step> + +<step> +<para> +Bring up the VLAN interface as <systemitem class="username">root</systemitem>: +<screen>~]# <command>ifup /etc/sysconfig/network-scripts/ifcfg-bond0.192</command> +Determining if ip address 192.168.10.1 is already in use for device bond0.192...</screen> +</para> +</step> + +<step> + <para> + Enabling VLAN tagging on the network switch. Consult the documentation for the switch to see what configuration is required. + </para> +</step> + +<step> +<para> +Check the status of the interfaces on the server: +<screen>~]# <command>ip addr</command> +1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN + link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 + inet 127.0.0.1/8 scope host lo + inet6 ::1/128 scope host + valid_lft forever preferred_lft forever +2: eth0: <BROADCAST,MULTICAST,SLAVE,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master bond0 state UP qlen 1000 + link/ether 52:54:00:19:28:fe brd ff:ff:ff:ff:ff:ff +3: eth1: <BROADCAST,MULTICAST,SLAVE,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master bond0 state UP qlen 1000 + link/ether 52:54:00:f6:63:9a brd ff:ff:ff:ff:ff:ff +4: bond0: <BROADCAST,MULTICAST,MASTER,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP + link/ether 52:54:00:19:28:fe brd ff:ff:ff:ff:ff:ff + inet 192.168.100.100/24 brd 192.168.100.255 scope global bond0 + inet6 fe80::5054:ff:fe19:28fe/64 scope link + valid_lft forever preferred_lft forever +5: <computeroutput>bond0.192@bond0</computeroutput>: <BROADCAST,MULTICAST,<computeroutput>MASTER,UP</computeroutput>,LOWER_UP> mtu 1500 qdisc noqueue state UP + link/ether 52:54:00:19:28:fe brd ff:ff:ff:ff:ff:ff + inet 192.168.10.1/24 brd 192.168.10.255 scope global bond0.192 + inet6 fe80::5054:ff:fe19:28fe/64 scope link + valid_lft forever preferred_lft forever</screen> +Notice there is now <literal>bond0.192@bond0</literal> in the list of interfaces and the status is <computeroutput>MASTER,UP</computeroutput>. + </para> + </step> + + <step> + <para> + Check the route on the server: + <screen>~]$ <command>ip route</command> +192.168.100.0/24 dev bond0 proto kernel scope link src 192.168.100.100 +192.168.10.0/24 dev <computeroutput>bond0.192</computeroutput> proto kernel scope link src 192.168.10.1 +169.254.0.0/16 dev bond0 scope link metric 1004 +169.254.0.0/16 dev bond0.192 scope link metric 1005</screen> +Notice there is now a route for the <systemitem class="ipaddress">192.168.10.0/24</systemitem> network pointing to the VLAN interface <literal>bond0.192</literal>. + </para> + </step> + + </procedure> + + +<bridgehead id="bh-Configuring_the_Second_Server">Configuring the Second Server</bridgehead> + +<para> + Repeat the configuration steps for the second server, using different <systemitem class="protocol">IP</systemitem> addresses but from the same subnets respectively. +</para> + +<para> + Test the bond is up and the network switch is working as expected: + <screen>~]$ <command>ping -c4 192.168.100.100</command> +PING 192.168.100.100 (192.168.100.100) 56(84) bytes of data. +64 bytes from 192.168.100.100: icmp_seq=1 ttl=64 time=1.35 ms +64 bytes from 192.168.100.100: icmp_seq=2 ttl=64 time=0.214 ms +64 bytes from 192.168.100.100: icmp_seq=3 ttl=64 time=0.383 ms +64 bytes from 192.168.100.100: icmp_seq=4 ttl=64 time=0.396 ms + +--- 192.168.100.100 ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 3002ms +rtt min/avg/max/mdev = 0.214/0.586/1.353/0.448 ms</screen> +</para> + +<bridgehead id="bh-Testing_the_VLAN">Testing the VLAN</bridgehead> + +<para> +To test that the network switch is configured for the VLAN, try to ping the first servers' VLAN interface: +<screen>~]# <command>ping -c2 192.168.10.1</command> +PING 192.168.10.1 (192.168.10.1) 56(84) bytes of data. +64 bytes from 192.168.10.1: icmp_seq=1 ttl=64 time=0.781 ms +64 bytes from 192.168.10.1: icmp_seq=2 ttl=64 time=0.977 ms +--- 192.168.10.1 ping statistics --- +2 packets transmitted, 2 received, <literal>0% packet loss</literal>, time 1001ms +rtt min/avg/max/mdev = 0.781/0.879/0.977/0.098 ms</screen> + No packet loss suggests everything is configured correctly and that the VLAN and underlying interfaces are <quote>up</quote>. + </para> + +<bridgehead id="bh-Optional_Steps">Optional Steps</bridgehead> + +<itemizedlist> + <listitem> + <para> + If required, perform further tests by removing and replacing network cables one at a time to verify that failover works as expected. Make use of the <application>ethtool</application> utility to verify which interface is connected to which cable. For example: + + <synopsis>ethtool <option>--identify</option> <replaceable>ifname</replaceable> <replaceable>integer</replaceable></synopsis> + Where <replaceable>integer</replaceable> is the number of times to flash the LED on the network interface. +</para> + </listitem> + <listitem> + <para> + The bonding module does not support <systemitem class="protocol">STP</systemitem>, therefore consider disabling the sending of BPDU packets from the network switch. + </para> + </listitem> + <listitem> + <para> + If the system is not linked to the network except over the connection just configured, consider enabling the switch port to transition directly to sending and receiving. For example on a Cisco switch, by means of the <literal>portfast</literal> command. + </para> + </listitem> +</itemizedlist> + + </section> + + </section> + + <section + id="sec-Using_Channel_Bonding"> + <title>Using Channel Bonding</title> + <indexterm> + <primary>kernel module</primary> + <secondary>bonding module</secondary> + <tertiary>description</tertiary> + </indexterm> + <indexterm> + <primary>channel bonding</primary> + <secondary>description</secondary> + </indexterm> + <indexterm> + <primary>bonding</primary> + <see>channel bonding</see> + </indexterm> + <indexterm> + <primary>NIC</primary> + <secondary>binding into single channel</secondary> + </indexterm> + <indexterm> + <primary>channel bonding interface</primary> + <see>kernel module</see> + </indexterm> + + <indexterm> + <primary>kernel module</primary> + <secondary>bonding module</secondary> + </indexterm> + <indexterm> + <primary>channel bonding</primary> + <secondary>configuration</secondary> + </indexterm> + + <para>To enhance performance, adjust available module options to ascertain what combination works best. Pay particular attention to the <command>miimon</command> or <command>arp_interval</command> and the <command>arp_ip_target</command> parameters. See <xref + linkend="s3-modules-bonding-directives"/> for a list of available options and how to quickly determine the best ones for your bonded interface.</para> + + <section + id="s3-modules-bonding-directives"> + <title>Bonding Module Directives</title> + <indexterm> + <primary>kernel module</primary> + <secondary>bonding module</secondary> + <tertiary>parameters to bonded interfaces</tertiary> + </indexterm> + <indexterm> + <primary>kernel module</primary> + <secondary>module parameters</secondary> + <tertiary>bonding module parameters</tertiary> + </indexterm> + <indexterm> + <primary>channel bonding</primary> + <secondary>parameters to bonded interfaces</secondary> + </indexterm> + <para>It is a good idea to test which channel bonding module parameters work best for your bonded interfaces before adding them to the <option>BONDING_OPTS="<replaceable>bonding parameters</replaceable>"</option> directive in your bonding interface configuration file (<filename>ifcfg-bond0</filename> for example). Parameters to bonded interfaces can be configured without unloading (and reloading) the bonding module by manipulating files in the <systemitem + class="filesystem">sysfs</systemitem> file system.</para> + <para> + <systemitem + class="filesystem">sysfs</systemitem> is a virtual file system that represents kernel objects as directories, files and symbolic links. <systemitem + class="filesystem">sysfs</systemitem> can be used to query for information about kernel objects, and can also manipulate those objects through the use of normal file system commands. The <systemitem + class="filesystem">sysfs</systemitem> virtual file system is mounted under the <filename>/sys/</filename> directory. All bonding interfaces can be configured dynamically by interacting with and manipulating files under the <filename>/sys/class/net/</filename> directory. </para> + <para>In order to determine the best parameters for your bonding interface, create a channel bonding interface file such as <filename>ifcfg-bond0</filename> by following the instructions in <xref linkend="sec-Create_a_Channel_Bonding_Interface" />. Insert the <option>SLAVE=yes</option> and <option>MASTER=bond0</option> directives in the configuration files for each interface bonded to <literal>bond0</literal>. Once this is completed, you can proceed to testing the parameters.</para> + <para>First, bring up the bond you created by running <command>ifup <option>bond<replaceable>N</replaceable></option></command> as <systemitem class="username">root</systemitem>:</para> + <screen>~]# <command>ifup bond0</command></screen> + <para>If you have correctly created the <filename>ifcfg-bond0</filename> bonding interface file, you will be able to see <computeroutput>bond0</computeroutput> listed in the output of running <command> ip link show</command> as <systemitem class="username">root</systemitem>:</para> + <screen>~]# <command>ip link show</command> +1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT + link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 +2: eth0: <BROADCAST,MULTICAST,SLAVE,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master bond0 state UP mode DEFAULT qlen 1000 + link/ether 52:54:00:e9:ce:d2 brd ff:ff:ff:ff:ff:ff +3: eth1: <BROADCAST,MULTICAST,SLAVE,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master bond0 state UP mode DEFAULT qlen 1000 + link/ether 52:54:00:38:a6:4c brd ff:ff:ff:ff:ff:ff +4: bond0: <BROADCAST,MULTICAST,MASTER,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP mode DEFAULT + link/ether 52:54:00:38:a6:4c brd ff:ff:ff:ff:ff:ff</screen> + <para>To view all existing bonds, even if they are not up, run:</para> + <screen>~]$ <command>cat /sys/class/net/bonding_masters</command> +bond0</screen> + <para>You can configure each bond individually by manipulating the files located in the <filename>/sys/class/net/bond<replaceable>N</replaceable>/bonding/</filename> directory. First, the bond you are configuring must be taken down:</para> + <screen>~]# <command>ifdown bond0</command> + </screen> + <para>As an example, to enable MII monitoring on bond0 with a 1 second interval, run as <systemitem class="username">root</systemitem>:</para> + <screen>~]# <command>echo 1000 > /sys/class/net/bond0/bonding/miimon</command> + </screen> + <para>To configure bond0 for <parameter + class="option">balance-alb</parameter> mode, run either:</para> + <screen>~]# <command>echo 6 > /sys/class/net/bond0/bonding/mode</command> + </screen> + <para>...or, using the name of the mode:</para> + <screen>~]# <command>echo balance-alb > /sys/class/net/bond0/bonding/mode</command> + </screen> + <para>After configuring options for the bond in question, you can bring it up and test it by running <command>ifup bond<replaceable>N</replaceable></command>. If you decide to change the options, take the interface down, modify its parameters using <systemitem class="filesystem">sysfs</systemitem>, bring it back up, and re-test.</para> + <para>Once you have determined the best set of parameters for your bond, add those parameters as a space-separated list to the <parameter + class="option">BONDING_OPTS=</parameter> directive of the <filename>/etc/sysconfig/network-scripts/ifcfg-bond<replaceable>N</replaceable> + </filename> file for the bonding interface you are configuring. Whenever that bond is brought up (for example, by the system during the boot sequence if the <parameter + class="option">ONBOOT=yes</parameter> directive is set), the bonding options specified in the <parameter + class="option">BONDING_OPTS</parameter> will take effect for that bond.</para> + <para>The following list provides the names of many of the more common channel bonding parameters, along with a description of what they do. For more information, see the brief descriptions for each <computeroutput>parm</computeroutput> in <command>modinfo bonding</command> output, or for more detailed information, see <ulink url="https://www.kernel.org/doc/Documentation/networking/bonding.txt">https://www.kernel.org/doc/Documentation/networking/bonding.txt</ulink><!--the <filename>bonding.txt</filename> file in the <package>kernel-doc</package> package (see <xref + linkend="s1-kernel-modules-additional-resources"/>)-->.</para> + <variablelist + spacing="compact"> + <title>Bonding Interface Parameters</title> + + + <varlistentry> + <term> + <literal>ad_select=<replaceable>value</replaceable> + </literal> + </term> + <listitem> + <para>Specifies the 802.3ad aggregation selection logic to use. Possible values are: + <itemizedlist> + <listitem> + <para> + <userinput>stable</userinput> or <userinput>0</userinput> — Default setting. The active aggregator is chosen by largest aggregate bandwidth. Reselection of the active aggregator occurs only when all slaves of the active aggregator are down or if the active aggregator has no slaves.</para> + </listitem> + <listitem> + <para> + <userinput>bandwidth</userinput> or <userinput>1</userinput> — The active aggregator is chosen by largest aggregate bandwidth. Reselection occurs if: + <itemizedlist> + <listitem> + <para> + A slave is added to or removed from the bond; + </para> + </listitem> + <listitem> + <para> + Any slave's link state changes; + </para> + </listitem> + <listitem> + <para> + Any slave's 802.3ad association state changes; + </para> + </listitem> + <listitem> + <para> + The bond's administrative state changes to up. + </para> + </listitem> + </itemizedlist></para> + </listitem> + + <listitem> + <para> + <userinput>count</userinput> or <userinput>2</userinput> — The active aggregator is chosen by the largest number of slaves. Reselection occurs as described for the <option>bandwidth</option> setting above.</para> + </listitem> + </itemizedlist> + The <option>bandwidth</option> and <option>count</option> selection policies permit failover of 802.3ad aggregations when partial failure of the active aggregator occurs. This keeps the aggregator with the highest availability, either in bandwidth or in number of slaves, active at all times. +</para> +</listitem> +</varlistentry> + + <varlistentry> + <term>arp_all_targets=<replaceable>value</replaceable> + </term> + <listitem> + <para>Specifies the quantity of <literal>arp_ip_target</literal>s that must be reachable in order for the ARP monitor to consider a slave as being up. This option affects only active-backup mode for slaves with <literal>arp_validation</literal> enabled. Possible values are:</para> + <itemizedlist> + <listitem> + <para> + <userinput>any</userinput> or <userinput>0</userinput> — Default setting. Consider the slave up when any of the <literal>arp_ip_target</literal>s is reachable.</para> + </listitem> + <listitem> + <para> + <userinput>all</userinput> or <userinput>1</userinput> — Consider the slave up only when all of the <literal>arp_ip_target</literal>s are reachable.</para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>arp_interval=<replaceable>time_in_milliseconds</replaceable> + </literal> + </term> + <listitem> + <para>Specifies, in milliseconds, how often <systemitem class="protocol">ARP</systemitem> monitoring occurs.</para> + <important> + <!-- <title>Make sure you specify all required parameters</title> --> + <para>It is essential that both <literal>arp_interval</literal> and <literal>arp_ip_target</literal> parameters are specified, or, alternatively, the <literal>miimon</literal> parameter is specified. Failure to do so can cause degradation of network performance in the event that a link fails.</para> + </important> + <para>If using this setting while in <literal>mode=0</literal> or <literal>mode=2</literal> (the two load-balancing modes), the network switch must be configured to distribute packets evenly across the NICs. For more information on how to accomplish this, see <ulink url="https://www.kernel.org/doc/Documentation/networking/bonding.txt">https://www.kernel.org/doc/Documentation/networking/bonding.txt</ulink><!--<filename>/usr/share/doc/kernel-doc-<replaceable>kernel_version</replaceable>/Documentation/networking/bonding.txt</filename>-->. + </para> + <para>The value is set to <userinput>0</userinput> by default, which disables it.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>arp_ip_target=<replaceable>ip_address</replaceable><optional>,<replaceable>ip_address_2</replaceable>,…<replaceable>ip_address_16</replaceable></optional> + </literal> + </term> + <listitem> + <para>Specifies the target <systemitem class="protocol">IP</systemitem> address of <systemitem class="protocol">ARP</systemitem> requests when the <literal>arp_interval</literal> parameter is enabled. Up to 16 <systemitem class="protocol">IP</systemitem> addresses can be specified in a comma separated list.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>arp_validate=<replaceable>value</replaceable> + </literal> + </term> + <listitem> + <para>Validate source/distribution of <systemitem class="protocol">ARP</systemitem> probes; default is <userinput>none</userinput>. Other valid values are <userinput>active</userinput>, <userinput>backup</userinput>, and <userinput>all</userinput>.</para> + </listitem> + </varlistentry> + <!-- <varlistentry> + <term> + <literal>debug=<replaceable>number</replaceable> + </literal> + </term> + <listitem> + <para>Enables debug messages. Possible values are:</para> + <itemizedlist> + <listitem> + <para> + <userinput>0</userinput> — Debug messages are disabled. This is the default.</para> + </listitem> + <listitem> + <para> + <userinput>1</userinput> — Debug messages are enabled.</para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> --> + <varlistentry> + <term> + <literal>downdelay=<replaceable>time_in_milliseconds</replaceable> + </literal> + </term> + <listitem> + <para>Specifies (in milliseconds) how long to wait after link failure before disabling the link. The value must be a multiple of the value specified in the <literal>miimon</literal> parameter. The value is set to <userinput>0</userinput> by default, which disables it.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>fail_over_mac=<replaceable>value</replaceable> + </literal> + </term> + <listitem> + <para>Specifies whether active-backup mode should set all slaves to the same MAC address at enslavement (the traditional behavior), or, when enabled, perform special handling of the bond's MAC address in accordance with the selected policy. Possible values are: + <itemizedlist> + <listitem> + <para> + <userinput>none</userinput> or <userinput>0</userinput> — Default setting. This setting disables <literal>fail_over_mac</literal>, and causes bonding to set all slaves of an active-backup bond to the same MAC address at enslavement time.</para> + </listitem> + <listitem> + <para> + <userinput>active</userinput> or <userinput>1</userinput> — The <quote>active</quote> <literal>fail_over_mac</literal> policy indicates that the + MAC address of the bond should always be the MAC address of the currently active slave. The MAC address of the slaves is not changed; instead, the MAC address of the bond changes during a failover.</para> +<para> +This policy is useful for devices that cannot ever alter their MAC address, or for devices that refuse incoming broadcasts with their own source MAC (which interferes with the ARP monitor). The disadvantage of this policy is that every device on the network must be updated via gratuitous ARP, as opposed to the normal method of switches snooping incoming traffic to update their ARP tables. If the gratuitous ARP is lost, communication may be disrupted. +</para> +<para> + When this policy is used in conjunction with the MII monitor, devices which assert link up prior to being able to actually transmit and receive are particularly susceptible to loss of the gratuitous ARP, and an appropriate updelay setting may be required. + </para> + + </listitem> + + <listitem> + <para> + <userinput>follow</userinput> or <userinput>2</userinput> — The <quote>follow</quote> <literal>fail_over_mac</literal> policy causes the MAC address of the bond to be selected normally (normally the MAC address of the first slave added to the bond). However, the second and subsequent slaves are not set to this MAC address while they are in a backup role; a slave is programmed with the bond's MAC address at failover time (and the formerly active slave receives the newly active slave's MAC address).</para> + <para> + This policy is useful for multiport devices that either become confused or incur a performance penalty when multiple ports are programmed with the same MAC address.</para> + </listitem> + </itemizedlist></para> +</listitem> +</varlistentry> + + <varlistentry> + <term>lacp_rate=<replaceable>value</replaceable> + </term> + <listitem> + <para>Specifies the rate at which link partners should transmit LACPDU packets in 802.3ad mode. Possible values are:</para> + <itemizedlist> + <listitem> + <para> + <userinput>slow</userinput> or <userinput>0</userinput> — Default setting. This specifies that partners should transmit LACPDUs every 30 seconds.</para> + </listitem> + <listitem> + <para> + <userinput>fast</userinput> or <userinput>1</userinput> — Specifies that partners should transmit LACPDUs every 1 second.</para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>miimon=<replaceable>time_in_milliseconds</replaceable> + </literal> + </term> + <listitem> + <para>Specifies (in milliseconds) how often MII link monitoring occurs. This is useful if high availability is required because MII is used to verify that the NIC is active. To verify that the driver for a particular NIC supports the MII tool, type the following command as root:</para> + <screen>~]# <command>ethtool <replaceable>interface_name</replaceable> | grep "Link detected:"</command> + </screen> + <para>In this command, replace <replaceable>interface_name</replaceable>> with the name of the device interface, such as <userinput>eth0</userinput>, not the bond interface. If MII is supported, the command returns:</para> + <screen>Link detected: yes</screen> + <para>If using a bonded interface for high availability, the module for each NIC must support MII. Setting the value to <userinput>0</userinput> (the default), turns this feature off. When configuring this setting, a good starting point for this parameter is <userinput>100</userinput>.</para> + <important> + <!-- <title>Make sure you specify all required parameters</title> --> + <para>It is essential that both <literal>arp_interval</literal> and <literal>arp_ip_target</literal> parameters are specified, or, alternatively, the <literal>miimon</literal> parameter is specified. Failure to do so can cause degradation of network performance in the event that a link fails.</para> + </important> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>mode=<replaceable>value</replaceable> + </literal> + </term> + <listitem> + <para>Allows you to specify the bonding policy. The <replaceable>value</replaceable> can be one of:</para> + <itemizedlist> + <listitem> + <para> + <userinput>balance-rr</userinput> or <userinput>0</userinput> — Sets a round-robin policy for fault tolerance and load balancing. Transmissions are received and sent out sequentially on each bonded slave interface beginning with the first one available.</para> + </listitem> + <listitem> + <para> + <userinput>active-backup</userinput> or <userinput>1</userinput> — Sets an active-backup policy for fault tolerance. Transmissions are received and sent out via the first available bonded slave interface. Another bonded slave interface is only used if the active bonded slave interface fails.</para> + </listitem> + <listitem> + <para> + <userinput>balance-xor</userinput> or <userinput>2</userinput> — Transmissions are based on the selected hash policy. The default is to derive a hash by XOR of the source and destination MAC addresses multiplied by the modulo of the number of slave interfaces. In this mode traffic destined for specific peers will always be sent over the same interface. As the destination is determined by the MAC addresses this method works best for traffic to peers on the same link or local network. If traffic has to pass through a single router then this mode of traffic balancing will be suboptimal.</para> + </listitem> + <listitem> + <para> + <userinput>broadcast</userinput> or <userinput>3</userinput> — Sets a broadcast policy for fault tolerance. All transmissions are sent on all slave interfaces.</para> + </listitem> + <listitem> + <para> + <userinput>802.3ad</userinput> or <userinput>4</userinput> — Sets an IEEE 802.3ad dynamic link aggregation policy. Creates aggregation groups that share the same speed and duplex settings. Transmits and receives on all slaves in the active aggregator. Requires a switch that is 802.3ad compliant.</para> + </listitem> + <listitem> + <para> + <userinput>balance-tlb</userinput> or <userinput>5</userinput> — Sets a Transmit Load Balancing (TLB) policy for fault tolerance and load balancing. The outgoing traffic is distributed according to the current load on each slave interface. Incoming traffic is received by the current slave. If the receiving slave fails, another slave takes over the MAC address of the failed slave. This mode is only suitable for local addresses known to the kernel bonding module and therefore cannot be used behind a bridge with virtual machines.</para> + </listitem> + <listitem> + <para> + <userinput>balance-alb</userinput> or <userinput>6</userinput> — Sets an Adaptive Load Balancing (ALB) policy for fault tolerance and load balancing. Includes transmit and receive load balancing for <systemitem class="protocol">IPv4</systemitem> traffic. Receive load balancing is achieved through <systemitem class="protocol">ARP</systemitem> negotiation. This mode is only suitable for local addresses known to the kernel bonding module and therefore cannot be used behind a bridge with virtual machines.</para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <!--<varlistentry> + <term> + <literal>num_unsol_na=<replaceable>number</replaceable> + </literal> + </term> + <listitem> + <para>Specifies the number of unsolicited <systemitem class="protocol">IPv6</systemitem> Neighbor Advertisements to be issued after a failover event. One unsolicited NA is issued immediately after the failover.</para> + <para>The valid range is <userinput>0 - 255</userinput>; the default value is <userinput>1</userinput>. This parameter affects only the active-backup mode.</para> + </listitem> + </varlistentry> not supported by NM --> + +<varlistentry> + <term> + <literal>packets_per_slave=<replaceable>range</replaceable></literal></term> + <listitem> + <para> + Specify the number of packets to transmit through a slave before moving to the next one. When set to <literal>0</literal> then a slave is chosen at random. + </para> + <para> + The valid range is <literal>0</literal> to <literal>65535</literal>; the default value is <literal>1</literal>. This option has effect only in <command>balance-rr</command> mode.</para> + </listitem> +</varlistentry> + + <varlistentry> + <term> + <literal>primary=<replaceable>interface_name</replaceable> + </literal> + </term> + <listitem> + <para>Specifies the interface name, such as <userinput>eth0</userinput>, of the primary device. The <literal>primary</literal> device is the first of the bonding interfaces to be used and is not abandoned unless it fails. This setting is particularly useful when one NIC in the bonding interface is faster and, therefore, able to handle a bigger load.</para> + <para>This setting is only valid when the bonding interface is in <userinput>active-backup</userinput> mode. See <ulink url="https://www.kernel.org/doc/Documentation/networking/bonding.txt">https://www.kernel.org/doc/Documentation/networking/bonding.txt</ulink><!--<filename> /usr/share/doc/kernel-doc-<replaceable>kernel-version</replaceable>/Documentation/networking/bonding.txt</filename>--> for more information.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>primary_reselect=<replaceable>value</replaceable> + </literal> + </term> + <listitem> + <para>Specifies the reselection policy for the primary slave. This affects how the primary slave is chosen to become the active slave when failure of the active slave or recovery of the primary slave occurs. This parameter is designed to prevent flip-flopping between the primary slave and other slaves. Possible values are:</para> + <itemizedlist> + <listitem> + <para> + <userinput>always</userinput> or <userinput>0</userinput> (default) — The primary slave becomes the active slave whenever it comes back up.</para> + </listitem> + <listitem> + <para> + <userinput>better</userinput> or <userinput>1</userinput> — The primary slave becomes the active slave when it comes back up, if the speed and duplex of the primary slave is better than the speed and duplex of the current active slave.</para> + </listitem> + <listitem> + <para> + <userinput>failure</userinput> or <userinput>2</userinput> — The primary slave becomes the active slave only if the current active slave fails and the primary slave is up.</para> + </listitem> + </itemizedlist> + <para>The <literal>primary_reselect</literal> setting is ignored in two cases:</para> + <itemizedlist> + <listitem> + <para>If no slaves are active, the first slave to recover is made the active slave.</para> + </listitem> + <listitem> + <para>When initially enslaved, the primary slave is always made the active slave.</para> + </listitem> + </itemizedlist> + <!-- <para>If no slaves are active, the first slave to recover is made the active slave.</para> + <para>When initially enslaved, the primary slave is always made the active slave.</para>--> + <para>Changing the <literal>primary_reselect</literal> policy via <systemitem + class="filesystem">sysfs</systemitem> will cause an immediate selection of the best active slave according to the new policy. This may or may not result in a change of the active slave, depending upon the circumstances</para> + </listitem> + </varlistentry> + +<varlistentry> + <term> + <literal>resend_igmp=<replaceable>range</replaceable></literal></term> + <listitem> + <para> + Specifies the number of IGMP membership reports to be issued after a failover event. One membership report is issued immediately after the failover, subsequent packets are sent in each 200ms interval. + </para> + <para> + The valid range is <literal>0</literal> to <literal>255</literal>; the default value is <literal>1</literal>. A value of <literal>0</literal> prevents the IGMP membership report from being issued in response to the failover event. + </para> + <para> + This option is useful for bonding modes <command>balance-rr</command> (mode 0), <command>active-backup</command> (mode 1), <command>balance-tlb</command> (mode 5) and <command>balance-alb</command> (mode 6), in which a failover can switch the IGMP traffic from one slave to another. Therefore a fresh IGMP report must be issued to cause the switch to forward the incoming IGMP traffic over the newly selected slave. + </para> + </listitem> +</varlistentry> + + <varlistentry> + <term> + <literal>updelay=<replaceable>time_in_milliseconds</replaceable> + </literal> + </term> + <listitem> + <para>Specifies (in milliseconds) how long to wait before enabling a link. The value must be a multiple of the value specified in the <literal>miimon</literal> parameter. The value is set to <userinput>0</userinput> by default, which disables it.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>use_carrier=<replaceable>number</replaceable> + </literal> + </term> + <listitem> + <para>Specifies whether or not <literal>miimon</literal> should use MII/ETHTOOL ioctls or <function>netif_carrier_ok()</function> to determine the link state. The <function>netif_carrier_ok()</function> function relies on the device driver to maintain its state with <literal>netif_carrier_<replaceable>on/off</replaceable></literal>; most device drivers support this function.</para> + <para>The MII/ETHTOOL ioctls tools utilize a deprecated calling sequence within the kernel. However, this is still configurable in case your device driver does not support <literal>netif_carrier_<replaceable>on/off</replaceable></literal>.</para> + <para>Valid values are:</para> + <itemizedlist> + <listitem> + <para> + <userinput>1</userinput> — Default setting. Enables the use of <function>netif_carrier_ok()</function>.</para> + </listitem> + <listitem> + <para> + <userinput>0</userinput> — Enables the use of MII/ETHTOOL ioctls.</para> + </listitem> + </itemizedlist> + <note> + <para>If the bonding interface insists that the link is up when it should not be, it is possible that your network device driver does not support <literal>netif_carrier_<replaceable>on/off</replaceable></literal>.</para> + </note> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>xmit_hash_policy=<replaceable>value</replaceable> + </literal> + </term> + <listitem> + <para>Selects the transmit hash policy used for slave selection in <userinput>balance-xor</userinput> and <userinput>802.3ad</userinput> modes. Possible values are:</para> + <itemizedlist> + <listitem> + <para> + <userinput>0</userinput> or <userinput>layer2</userinput> — Default setting. This parameter uses the XOR of hardware MAC addresses to generate the hash. The formula used is:</para> + <screen>(<replaceable>source_MAC_address</replaceable> XOR <replaceable>destination_MAC</replaceable>) MODULO <replaceable>slave_count</replaceable> + </screen> + <para>This algorithm will place all traffic to a particular network peer on the same slave, and is 802.3ad compliant.</para> + </listitem> + <listitem> + <para> + <userinput>1</userinput> or <userinput>layer3+4</userinput> — Uses upper layer protocol information (when available) to generate the hash. This allows for traffic to a particular network peer to span multiple slaves, although a single connection will not span multiple slaves.</para> + <para>The formula for unfragmented TCP and UDP packets used is:</para> + <screen>((<replaceable>source_port</replaceable> XOR <replaceable>dest_port</replaceable>) XOR + ((<replaceable>source_IP</replaceable> XOR <replaceable>dest_IP</replaceable>) AND <constant>0xffff</constant>) + MODULO <replaceable>slave_count</replaceable> + </screen> + <para>For fragmented TCP or UDP packets and all other <systemitem class="protocol">IP</systemitem> protocol traffic, the source and destination port information is omitted. For non-<systemitem class="protocol">IP</systemitem> traffic, the formula is the same as the <command>layer2</command> transmit hash policy.</para> + <para>This policy intends to mimic the behavior of certain switches; particularly, Cisco switches with PFC2 as well as some Foundry and IBM products.</para> + <para>The algorithm used by this policy is not 802.3ad compliant.</para> + </listitem> + <listitem> + <para> + <userinput>2</userinput> or <userinput>layer2+3</userinput> — Uses a combination of layer2 and layer3 protocol information to generate the hash.</para> + <para>Uses XOR of hardware MAC addresses and <systemitem class="protocol">IP</systemitem> addresses to generate the hash. The formula is:</para> + <screen>(((<replaceable>source_IP</replaceable> XOR <replaceable>dest_IP</replaceable>) AND <constant>0xffff</constant>) XOR + ( <replaceable>source_MAC</replaceable> XOR <replaceable>destination_MAC</replaceable> )) + MODULO <replaceable>slave_count</replaceable> + </screen> + <para>This algorithm will place all traffic to a particular network peer on the same slave. For non-<systemitem class="protocol">IP</systemitem> traffic, the formula is the same as for the layer2 transmit hash policy.</para> + <para>This policy is intended to provide a more balanced distribution of traffic than layer2 alone, especially in environments where a layer3 gateway device is required to reach most destinations.</para> + <para>This algorithm is 802.3ad compliant.</para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + </variablelist> + </section> + </section> + + <section id="sec-Network_Bonding_Using_the_NetworkManager_Command_Line_Tool_nmcli"> + <title>Using the NetworkManager Command Line Tool, nmcli</title> + <para> + To create a bond, named <replaceable>mybond0</replaceable>, issue a command as follows: + <screen>~]$ <command>nmcli con add type bond con-name <replaceable>mybond0</replaceable> ifname <replaceable>mybond0</replaceable> mode active-backup</command> +Connection 'mybond0' (9301ff97-abbc-4432-aad1-246d7faea7fb) successfully added.</screen> + To add a slave interface, issue a command in the following form: + <screen>~]$ <command>nmcli con add type bond-slave ifname <replaceable>ens7</replaceable> master <replaceable>mybond0</replaceable></command></screen> + To add additional slaves, repeat the previous command with a new interface, for example: + <screen>~]$ <command>nmcli con add type bond-slave ifname <replaceable>ens3</replaceable> master <replaceable>mybond0</replaceable></command> +Connection 'bond-slave-ens3-1' (50c59350-1531-45f4-ba04-33431c16e386) successfully added.</screen> +Note that as no <command>con-name</command> was given for the slaves, the name was derived from the interface name by prepending the type. At time of writing, <application>nmcli</application> only supports Ethernet slaves. + </para> + <para> + In order to bring up a bond, the slaves must be brought up first as follows: + <screen>~]$ <command>nmcli con up bond-slave-<replaceable>ens7</replaceable></command> +Connection successfully activated (D-Bus active path: /org/freedesktop/NetworkManager/ActiveConnection/14)</screen> +<screen>~]$ <command>nmcli con up bond-slave-<replaceable>ens3</replaceable></command> +Connection successfully activated (D-Bus active path: /org/freedesktop/NetworkManager/ActiveConnection/15)</screen> +Now bring up the bond as follows: +<screen>~]$ <command>nmcli con up bond-<replaceable>mybond0</replaceable></command> +Connection successfully activated (D-Bus active path: /org/freedesktop/NetworkManager/ActiveConnection/16)</screen> + </para> + <para> + See <xref linkend="sec-Using_the_NetworkManager_Command_Line_Tool_nmcli" /> for an introduction to <application>nmcli</application> + </para> + </section> + + <!--Topics, Reference--> + <section id="sec-Configure_Network_Bonding-additional_resources"> + +<title>Additional Resources</title> +<para> + The following sources of information provide additional resources regarding network bonding. + </para> + <section id="sec-Configure_Network_Bonding-docs-inst"> + <title>Installed Documentation</title> + <itemizedlist> + <listitem> + <para> + <filename>nmcli(1)</filename> man page — Describes <application>NetworkManager</application>'s command‐line tool. + </para> + </listitem> + <listitem> + <para> + <filename>nmcli-examples(5)</filename> man page — Gives examples of <application>nmcli</application> commands. + </para> + </listitem> + <listitem> + <para> + <filename>nm-settings(5)</filename> man page — Description of settings and parameters of <application>NetworkManager</application> connections. + </para> + </listitem> +</itemizedlist> +</section> + +<!--<section id="sec-Configure_Network_Bonding-docs-installable"> + <title>Installable Documentation</title> + <itemizedlist> + + <listitem> + <para> + <filename + class="directory">/usr/share/doc/kernel-doc/Documentation/</filename> — This directory, which is provided by the <package>kernel-doc</package> package, contains information on bonding. Before accessing the kernel documentation, you must run the following command as <systemitem class="username">root</systemitem>:</para> + <screen>~]# <command>dnf install kernel-doc</command></screen> + <para> + <filename>/usr/share/doc/kernel-doc-<replaceable>version</replaceable>/Documentation/networking/bonding.txt</filename> — Describes the Linux bonding driver. + </para> + </listitem> + </itemizedlist> + </section>--> + +<section id="sec-Configure_Network_Bonding_Online_Documentation"> + <title>Online Documentation</title> + <para> +<variablelist> + <!--<varlistentry> +<term><citetitle pubwork="book">&MAJOROSVER; System Administrator's Reference Guide</citetitle></term> +<listitem> +<para> + Lists all the configurable parameters in an Ethernet interface configuration file. +</para> +</listitem> +</varlistentry>--> + + + + <varlistentry> +<term><citetitle pubwork="book">&MAJOROSVER; System Administrator's Guide</citetitle></term> +<listitem> +<para> + Explains the use of kernel module capabilities. +</para> +</listitem> +</varlistentry> + +</variablelist> +</para> +</section> +</section> + +</chapter> diff --git a/docs/guide/Configure_Network_Bridging.xml b/docs/guide/Configure_Network_Bridging.xml new file mode 100644 index 000000000..359c26024 --- /dev/null +++ b/docs/guide/Configure_Network_Bridging.xml @@ -0,0 +1,482 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "Networking_Guide.ent"> +%BOOK_ENTITIES; +]> +<chapter id="ch-Configure_Network_Bridging"> + <title>Configure Network Bridging</title> + <para> + A network bridge is a link-layer device which forwards traffic between networks based on MAC addresses. It makes forwarding decisions based on a table of MAC addresses which it builds by listening to network traffic and thereby learning what hosts are connected to each network. A software bridge can be used within a Linux host in order to emulate a hardware bridge, for example in virtualization applications for sharing a NIC with one or more virtual NICs. + </para> + <para> + Note that a bridge cannot be established over Wi-Fi networks operating in <firstterm>Ad-Hoc</firstterm> or <firstterm>Infrastructure</firstterm> modes. This is due to the IEEE 802.11 standard that specifies the use of 3-address frames in Wi-Fi for the efficient use of airtime. A system configured to be an <firstterm>access point</firstterm> (<acronym>AP</acronym>) running the <systemitem class="daemon">hostapd</systemitem> can support the necessary 4-address frames. + </para> + +<section id="sec-Configure_Network_Bridging_Using_a_GUI"> + <title>Configure Network Bridging Using a GUI</title> + + <para> + When starting a bridge interface, <application>NetworkManager</application> waits for at least one port to enter the <quote>forwarding</quote> state before beginning any network-dependent <systemitem class="protocol">IP</systemitem> configuration such as <systemitem class="protocol">DHCP</systemitem> or <systemitem class="protocol">IPv6</systemitem> autoconfiguration. Static <systemitem class="protocol">IP</systemitem> addressing is allowed to proceed before any slaves or ports are connected or begin forwarding packets. + </para> + +<section + id="sec-Establishing_a_Bridge_Connection"> + <title>Establishing a Bridge Connection</title> + + <procedure + id="procedure-Adding_a_New_Bridge_Connection"> + <title>Adding a New Bridge Connection</title> + <para> + You can configure a new Bridge connection by opening the <guilabel>Network</guilabel> window and selecting the plus symbol below the menu. + </para> + <step> + <para> + To use the graphical <application>Network</application> settings tool, press the <keycap>Super</keycap> key to enter the Activities Overview, type <command>control network</command> and then press <keycap>Enter</keycap>. The <application>Network</application> settings tool appears. + </para> + + </step> + <step> + <para> + Select the plus symbol below the menu. The <guilabel>Add Network Connection</guilabel> window appears. + </para> + </step> + <step> + <para>Select the <guilabel>Bridge</guilabel> menu entry. The <guilabel>Editing Bridge connection <replaceable>1</replaceable></guilabel> window appears.</para> + </step> + + </procedure> + <procedure + id="procedure-Editing_an_Existing_Bridge_Connection"> + <title>Editing an Existing Bridge Connection</title> + <para>You can configure an existing bridge connection by opening the <guilabel>Network</guilabel> window and selecting the name of the connection from the list. Then click the <guibutton>Edit</guibutton> button. + </para> + <step> + <para>Press the <keycap>Super</keycap> key to enter the Activities Overview, type <command>control network</command> and then press <keycap>Enter</keycap>. The <application>Network</application> settings tool appears.</para> + </step> + <step> + <para>Select the <guilabel>Bridge</guilabel> connection you want to edit from the left hand menu.</para> + </step> + <step> + <para>Click the <guilabel>Options</guilabel> button.</para> + </step> + </procedure> + <bridgehead + id="bh-Configuring_the_Connection_Name_Auto-Connect_Behavior_and_Availability_Settings-bridge">Configuring the Connection Name, Auto-Connect Behavior, and Availability Settings</bridgehead> + <para>Five settings in the <guilabel>Editing</guilabel> dialog are common to all connection types, see the <guilabel>General</guilabel> tab: + </para> + <itemizedlist> + <listitem> + <para> + <guilabel>Connection name</guilabel> — Enter a descriptive name for your network connection. This name will be used to list this connection in the menu of the <guilabel>Network</guilabel> window. + </para> + </listitem> + <listitem> + <para> + <guilabel>Automatically connect to this network when it is available</guilabel> — Select this box if you want <application>NetworkManager</application> to auto-connect to this connection when it is available. See <xref linkend="sec-Connecting_to_a_Network_Automatically"/> for more information. + </para> + </listitem> + <listitem> + <para> + <guilabel>All users may connect to this network</guilabel> — Select this box to create a connection available to all users on the system. Changing this setting may require root privileges. See <xref linkend="sec-System-wide_and_Private_Connection_Profiles"/> for details. + </para> + </listitem> + <listitem> + <para> + <guilabel>Automatically connect to VPN when using this connection</guilabel> — Select this box if you want <application>NetworkManager</application> to auto-connect to a VPN connection when it is available. Select the VPN from the dropdown menu. + </para> + </listitem> + <listitem> + <para> + <guilabel>Firewall Zone</guilabel> — Select the Firewall Zone from the dropdown menu. + </para> + </listitem> + </itemizedlist> + + <section id="sec-Configuring_the_Bridge_Tab"> + <title>Configuring the Bridge Tab</title> + <variablelist> + <varlistentry> + <term> + <guilabel>Interface name</guilabel> + </term> + <listitem> + <para>The name of the interface to the bridge.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Bridged connections</guilabel> + </term> + <listitem> + <para>One or more slave interfaces.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Aging time</guilabel> + </term> + <listitem> + <para>The time, in seconds, a MAC address is kept in the MAC address forwarding database.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Enable STP (Spanning Tree Protocol)</guilabel> + </term> + <listitem> + <para>If required, select the check box to enable <systemitem class="protocol">STP</systemitem>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Priority</guilabel> + </term> + <listitem> + <para>The bridge priority; the bridge with the lowest priority will be elected as the root bridge.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Forward delay</guilabel> + </term> + <listitem> + <para>The time, in seconds, spent in both the Listening and Learning states before entering the Forwarding state. The default is 15 seconds.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Hello time</guilabel> + </term> + <listitem> + <para>The time interval, in seconds, between sending configuration information in bridge protocol data units (BPDU).</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Max age</guilabel> + </term> + <listitem> + <para>The maximum time, in seconds, to store the configuration information from BPDUs. This value should be twice the Hello Time plus 1 but less than twice the Forwarding delay minus 1. </para> + </listitem> + </varlistentry> + </variablelist> + + <figure id="exam--Establishing_a_Bridge_Connection"> + <title>Editing Bridge Connection 1</title> + <mediaobject + id="mediaobj-Editing-Bridge-Connection-1_Gnome3.png"> + <imageobject> + <imagedata + scalefit="0" + fileref="Editing-Bridge-Connection-1_Gnome3.png" + format="PNG" /> + </imageobject> + <textobject><para>A screen shot of the Editing Bridge Connection 1</para></textobject> + </mediaobject> + </figure> + +<procedure id="procedure-Adding_a_Slave_Interface_to_a_Bridge"> + <title>Adding a Slave Interface to a Bridge</title> + <step> + <para> + To add a port to a bridge, select the <guilabel>Bridge</guilabel> tab in the <guilabel>Editing Bridge connection <replaceable>1</replaceable></guilabel> window. If necessary, open this window by following the procedure in <xref linkend="procedure-Editing_an_Existing_Bridge_Connection" />.</para> + </step> + <step> + <para> + Click <guibutton>Add</guibutton>. The <guilabel>Choose a Connection Type</guilabel> menu appears. + </para> + </step> + <step> + <para> + Select the type of connection to be created from the list. Click <guilabel>Create</guilabel>. A window appropriate to the connection type selected appears. + </para> + </step> + <step> + <para> + Select the <guilabel>Bridge Port</guilabel> tab. Configure <guilabel>Priority</guilabel> and <guilabel>Path cost</guilabel> as required. Note the STP priority for a bridge port is limited by the Linux kernel. Although the standard allows a range of <literal>0</literal> to <literal>255</literal>, Linux only allows <literal>0</literal> to <literal>63</literal>. The default is <literal>32</literal> in this case.</para> + </step> + <step> + <para> + If required, select the <guilabel>Hairpin mode</guilabel> check box to enable forwarding of frames for external processing. Also known as <firstterm>virtual Ethernet port aggregator</firstterm> (<acronym>VEPA</acronym>) mode. + </para> + </step> + + </procedure> + + <para>Then, to configure:</para> + <itemizedlist> + <listitem> + <para>An Ethernet slave, click the <guilabel>Ethernet</guilabel> tab and proceed to <xref linkend="sec-Configuring_the_Connection_Name_Auto-Connect_Behavior_and_Availability_Settings-wired"/>, or; + </para> + </listitem> + <listitem> + <para>A Bond slave, click the <guilabel>Bond</guilabel> tab and proceed to <xref linkend="sec-Configuring_the_Bond_Tab"/>, or; + </para> + </listitem> + <listitem> + <para>A Team slave, click the <guilabel>Team</guilabel> tab and proceed to <xref linkend="sec-Configuring_the_Team_Tab"/>, or; + </para> + </listitem> + <listitem> + <para>An VLAN slave, click the <guilabel>VLAN</guilabel> tab and proceed to <xref linkend="sec-Configuring_the_VLAN_Tab"/>, or; + </para> + </listitem> + + </itemizedlist> + + + <bridgehead + id="bh-Saving_Your_New_or_Modified_Connection_and_Making_Further_Configurations-bridge">Saving Your New (or Modified) Connection and Making Further Configurations</bridgehead> + <para>Once you have finished editing your new bridge connection, click the <guibutton>Save</guibutton> button to save your customized configuration. If the profile was in use while being edited, power cycle the connection to make <application>NetworkManager</application> apply the changes. If the profile is OFF, set it to ON. See <xref + linkend="sec-Connecting_to_a_Network_Using_a_GUI"/> for information on using your new or altered connection.</para> + <para>You can further configure an existing connection by selecting it in the <guilabel>Network</guilabel> window and clicking <guilabel>Options</guilabel> to return to the <guilabel>Editing</guilabel> dialog.</para> + <para>Then, to configure:</para> + <itemizedlist> + <listitem> + <para><systemitem class="protocol">IPv4</systemitem> settings for the connection, click the <guilabel>IPv4 Settings</guilabel> tab and proceed to <xref + linkend="sec-Configuring_IPv4_Settings"/>, or; + </para> + </listitem> + <listitem> + <para><systemitem class="protocol">IPv6</systemitem> settings for the connection, click the <guilabel>IPv6 Settings</guilabel> tab and proceed to <xref + linkend="sec-Configuring_IPv6_Settings"/>. + </para> + </listitem> + </itemizedlist> + </section> + </section> + +</section> +<section id="sec-Network_Bridging_Using_the_Command_Line_Interface"> + <title>Using the Command Line Interface (CLI)</title> + + <section id="sec-Check_if_Bridging_Kernel_Module_is_Installed"> + <title>Check if Bridging Kernel Module is Installed</title> + <para> + In Fedora, the bridging module is loaded by default. If necessary, you can make sure that the module is loaded by issuing the following command as <systemitem class="username">root</systemitem>: + <screen>~]# <command>modprobe --first-time bridge</command> +modprobe: ERROR: could not insert 'bridge': Module already in kernel</screen> +To display information about the module, issue the following command: +<screen>~]$ <command>modinfo bridge</command></screen> +See the <filename>modprobe(8)</filename> man page for more command options. + </para> +</section> + + <section id="sec-Create_a_Network_Bridge"> + <title>Create a Network Bridge</title> + <para> + To create a network bridge, create a file in the <filename>/etc/sysconfig/network-scripts/</filename> directory called <filename>ifcfg-br<replaceable>N</replaceable></filename>, replacing <replaceable>N</replaceable> with the number for the interface, such as <filename>0</filename>. + </para> + <para> + The contents of the file is similar to whatever type of interface is getting bridged to, such as an Ethernet interface. The differences in this example are as follows: + <itemizedlist> + <listitem> + <para> + The <option>DEVICE</option> directive is given an interface name as its argument in the format <option>br<replaceable>N</replaceable></option>, where <replaceable>N</replaceable> is replaced with the number of the interface. + </para> + </listitem> + <listitem> + <para> + The <option>TYPE</option> directive is given an argument <option>Bridge</option> or <option>Ethernet</option>. This directive determines the device type and the argument is case sensitive. + </para> + </listitem> + <listitem> + <para> + The bridge interface configuration file is given an <systemitem class="protocol">IP</systemitem> address whereas the physical interface configuration file must only have a MAC address (see below). + </para> + </listitem> + <listitem> + <para> + An extra directive, <option>DELAY=0</option>, is added to prevent the bridge from waiting while it monitors traffic, learns where hosts are located, and builds a table of MAC addresses on which to base its filtering decisions. The default delay of 30 seconds is not needed if no routing loops are possible. + </para> + </listitem> + </itemizedlist> + </para> + <para> + The following is a sample bridge interface configuration file using a static <systemitem class="protocol">IP</systemitem> address: + </para> + <example id="ex-Sample_ifcfg-br0_Interface_Configuration_File"> + <title>Sample ifcfg-br0 Interface Configuration File</title> + <programlisting>DEVICE=br0 +TYPE=Bridge +IPADDR=192.168.1.1 +PREFIX=24 +ONBOOT=yes +BOOTPROTO=none +DELAY=0</programlisting> + </example> + <para>To complete the bridge another interface is created, or an existing interface is modified, and pointed to the bridge interface. The following is a sample Ethernet interface configuration file pointing to a bridge interface. Configure your physical interface in <filename>/etc/sysconfig/network-scripts/ifcfg-eth<replaceable>X</replaceable></filename>, where <replaceable>X</replaceable> is a unique number corresponding to a specific interface, as follows:</para> + <example id="ex-Sample_ifcfg-eth0_Interface_Configuration_File"> + <title>Sample ifcfg-ethX Interface Configuration File</title> + <programlisting>DEVICE=ethX +TYPE=Ethernet +HWADDR=AA:BB:CC:DD:EE:FF +BOOTPROTO=none +ONBOOT=yes +BRIDGE=br0</programlisting> + </example> + <note> + <para> + For the <option>DEVICE</option> directive, almost any interface name could be used as it does not determine the device type. <option>TYPE=Ethernet</option> is not strictly required. If the <option>TYPE</option> directive is not set, the device is treated as an Ethernet device (unless it's name explicitly matches a different interface configuration file.) + </para> + </note> + <para> + Specifying the hardware or MAC address using the <command>HWADDR</command> directive will influence the device naming procedure as explained in <xref linkend="ch-Consistent_Network_Device_Naming" />. + </para> + + <!--<para>See the <citetitle pubwork="book">&MAJOROSVER; System Administrator's Reference Guide</citetitle> for a review of the directives and options used in network interface configuration files.</para>--> + <warning> + <para> + If you are configuring bridging on a remote host, and you are connected to that host over the physical NIC you are configuring, please consider the implications of losing connectivity before proceeding. You will lose connectivity when restarting the service and may not be able to regain connectivity if any errors have been made. Console, or out-of-band access is advised. + </para> + </warning> + <para> + Restart the networking service in order for the changes to take effect. As <systemitem class="username">root</systemitem> issue the following command:</para> + <screen>~]# <command>systemctl network restart</command></screen> +</section> + <section id="sec-Network_Bridge_with_Bond"> + <title>Network Bridge with Bond</title> + <para> + An example of a network bridge formed from two or more bonded Ethernet interfaces will now be given as this is another common application in a virtualization environment. If you are not very familiar with the configuration files for bonded interfaces then please refer to <xref linkend="sec-Create_a_Channel_Bonding_Interface"/> + </para> + <para> + Create or edit two or more Ethernet interface configuration files, which are to be bonded, as follows: + <programlisting>DEVICE=ethX +TYPE=Ethernet +SLAVE=yes +MASTER=bond0 +BOOTPROTO=none +HWADDR=AA:BB:CC:DD:EE:FF</programlisting> + </para> + <note> + <para> + Using <systemitem class="etheraddress">eth<replaceable>X</replaceable></systemitem> as the interface name is common practice but almost any name could be used. + </para> + </note> + <para> + Create or edit one interface configuration file, <filename>/etc/sysconfig/network-scripts/ifcfg-bond0</filename>, as follows: + <programlisting>DEVICE=bond0 +ONBOOT=yes +BONDING_OPTS='mode=1 miimon=100' +BRIDGE=brbond0</programlisting> + For further instructions and advice on configuring the bonding module and to view the list of bonding parameters, see <xref linkend="sec-Using_Channel_Bonding"/>. + </para> + <para> + Create or edit one interface configuration file, <filename>/etc/sysconfig/network-scripts/ifcfg-brbond0</filename>, as follows: + <programlisting>DEVICE=brbond0 +ONBOOT=yes +TYPE=Bridge +IPADDR=192.168.1.1 +PREFIX=24</programlisting> + </para> + + <para>We now have two or more interface configuration files with the <option>MASTER=bond0</option> directive. These point to the configuration file named <filename>/etc/sysconfig/network-scripts/ifcfg-bond0</filename>, which contains the <option>DEVICE=bond0</option> directive. This <filename>ifcfg-bond0</filename> in turn points to the <filename>/etc/sysconfig/network-scripts/ifcfg-brbond0</filename> configuration file, which contains the <systemitem class="protocol">IP</systemitem> address, and acts as an interface to the virtual networks inside the host.</para> + <para> + To bring up the new or recently configured interfaces, issue a command as <systemitem class="username">root</systemitem> in the following format: + <synopsis><command>ifup <replaceable>device</replaceable></command></synopsis> + This command will detect if <application>NetworkManager</application> is running and call <command>nmcli con load <replaceable>UUID</replaceable></command> and then call <command>nmcli con up <replaceable>UUID</replaceable></command>. + </para> + + <para> + Alternatively, to reload all interfaces, issue the following command as <systemitem class="username">root</systemitem>: +<screen>~]# <command>systemctl restart network</command></screen> +This command will stop the network service, start the network service, and then call <command>ifup</command> for all ifcfg files with <command>ONBOOT=yes</command>.</para> + +<note> +<para> + The default behavior is for <application>NetworkManager</application> not to be aware of changes to ifcfg files and to continue using the old configuration data until the interface is next brought up. This is set by the <option>monitor-connection-files</option> option in the <filename>NetworkManager.conf</filename> file. See the <filename>NetworkManager.conf(5)</filename> manual page for more information. + </para> + </note> + </section> + + +</section> + <section id="sec-Network_Bridging_sec-Using_the_NetworkManager_Command_Line_Tool_nmcli"> + <title>Using the NetworkManager Command Line Tool, nmcli</title> + + <para> + To create a bridge, with name <interface>bridge-br0</interface>, issue a command as follows: + <screen>~]$ <command>nmcli con add type bridge ifname br0</command> +Connection 'bridge-br0' (79cf6a3e-0310-4a78-b759-bda1cc3eef8d) successfully added.</screen> + If no interface name is specified, the name will default to <interface>bridge</interface>, <interface>bridge-1</interface>, <interface>bridge-2</interface>, and so on. + </para> + <para> + To view the connections, issue the following command: + <screen>~]$ <command>nmcli con show conf</command> +NAME UUID TYPE TIMESTAMP-REAL +eth0 4d5c449a-a6c5-451c-8206-3c9a4ec88bca 802-3-ethernet Mon 21 Oct 2013 16:01:53 BST +bridge-br0 79cf6a3e-0310-4a78-b759-bda1cc3eef8d bridge never</screen> + </para> + <para> + <firstterm>Spanning tree protocol</firstterm> (<acronym>STP</acronym>) according to the IEEE 802.1D standard is enabled by default. To disable <systemitem class="protocol">STP</systemitem> for this bridge, issue a command as follows: + <screen>~]$ <command>nmcli con bridge-br0 stp no</command></screen> + To re-enable <systemitem class="protocol">802.1D STP</systemitem> for this bridge, issue a command as follows: + <screen>~]$ <command>nmcli con bridge-br0 stp yes</command></screen> + </para> + <para> + The default bridge priority for <systemitem class="protocol">802.1D STP</systemitem> is <literal>32768</literal>. The lower number is preferred in root bridge selection. For example, a bridge with priority of <literal>28672</literal> would be selected as the root bridge in preference to a bridge with priority value of <literal>32768</literal> (the default). To create a bridge with a non-default value, issue a command as follows: +<screen>~]$ <command>nmcli con add type bridge ifname br5 stp yes priority 28672</command> +Connection 'bridge-br5' (86b83ad3-b466-4795-aeb6-4a66eb1856c7) successfully added.</screen> +The allowed values are in the range <literal>0</literal> to <literal>65535</literal>, but can only be set in multiples of <literal>4096</literal>. + </para> + <para> + To change the bridge priority of an existing bridge to a non-default value, issue a command in the following format: + <screen>~]$ <command>nmcli connection modify bridge-br5 bridge.priority 36864</command></screen> + The allowed values are in the range <literal>0</literal> to <literal>65535</literal>, but can only be set in multiples of <literal>4096</literal>. + </para> + <para> + Further options for <systemitem class="protocol">802.1D STP</systemitem> are listed in the bridge section of the <filename>nmcli(1)</filename> man page. + </para> + <para> + To add, or enslave an interface, for example <interface>eth1</interface>, to the bridge <interface>bridge-br0</interface>, issue a command as follows: +<screen>~]$ <command>nmcli con add type bridge-slave ifname eth1 master bridge-br0</command> +Connection 'bridge-slave-eth1' (70ffae80-7428-4d9c-8cbd-2e35de72476e) successfully added.</screen> +At time of writing, <application>nmcli</application> only supports Ethernet slaves. + </para> + <para> + To change a value using interactive mode, issue the following command: + <screen>~]$ <command>nmcli connection edit bridge-br0</command></screen> + You will be placed at the <application>nmcli</application> prompt. + <screen>nmcli> <command>set bridge.priority 4096</command> +nmcli> <command>save</command> +Connection 'bridge-br0' (79cf6a3e-0310-4a78-b759-bda1cc3eef8d) successfully saved. +nmcli> <command>quit</command></screen> + + </para> + <para> + See <xref linkend="sec-Using_the_NetworkManager_Command_Line_Tool_nmcli" /> for an introduction to <application>nmcli</application> + </para> +</section> + <!--Topics, Reference--> + <section id="sec-Network_Bridging-additional_resources"> + +<title>Additional Resources</title> +<para> + The following sources of information provide additional resources regarding network bridging. + </para> + <section id="sec-Network_Bridging-docs-inst"> + <title>Installed Documentation</title> + <itemizedlist> + <listitem> + <para> + <filename>nmcli(1)</filename> man page — Describes <application>NetworkManager</application>'s command‐line tool. + </para> + </listitem> + <listitem> + <para> + <filename>nmcli-examples(5)</filename> man page — Gives examples of <application>nmcli</application> commands. + </para> + </listitem> + <listitem> + <para> + <filename>nm-settings(5)</filename> man page — Description of settings and parameters of <application>NetworkManager</application> connections. + </para> + </listitem> + +</itemizedlist> +</section> + + +</section> + +</chapter> diff --git a/docs/guide/Configure_Network_Teaming.xml b/docs/guide/Configure_Network_Teaming.xml new file mode 100644 index 000000000..c04e3a499 --- /dev/null +++ b/docs/guide/Configure_Network_Teaming.xml @@ -0,0 +1,1323 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "Networking_Guide.ent"> +%BOOK_ENTITIES; +]> +<chapter id="ch-Configure_Network_Teaming"> + <title>Configure Network Teaming</title> + + + <warning> + <para> + The use of direct cable connections without network switches is not supported for teaming. The failover mechanisms described here will not work as expected without the presence of network switches. + </para> +</warning> + + <note> + <para> + The active-backup, balance-tlb and balance-alb modes do not require any specific configuration of the switch. Other bonding modes require configuring the switch to aggregate the links. For example, a Cisco switch requires EtherChannel for Modes 0, 2, and 3, but for Mode 4 LACP and EtherChannel are required. See the documentation supplied with your switch and see <ulink url="https://www.kernel.org/doc/Documentation/networking/bonding.txt">https://www.kernel.org/doc/Documentation/networking/bonding.txt</ulink>. + </para> + <para> + Unlike bonding, if a team interface is configured to use link aggregation but LACP is not correctly configured and working on the network switch, no routable connection will be formed. + </para> + </note> + + <!-- Topics, Concepts:--> +<section id="sec-Understanding_Network_Teaming"> + <title>Understanding Network Teaming</title> + <para> + The combining or aggregating together of network links in order to provide a logical link with higher throughput, or to provide redundancy, is known by many names such as <quote>channel bonding</quote>, <quote>Ethernet bonding</quote>, <quote>port trunking</quote>, <quote>channel teaming</quote>, <quote>NIC teaming</quote>, <quote>link aggregation</quote>, and so on. This concept as originally implemented in the Linux kernel is widely referred to as <quote>bonding</quote>. The term Network Teaming has been chosen to refer to this new implementation of the concept. The existing bonding driver is unaffected, Network Teaming is offered as an alternative and does not replace bonding in Fedora. + </para> + <para> + Network Teaming, or Team, is designed to implement the concept in a different way by providing a small kernel driver to implement the fast handling of packet flows, and various user-space applications to do everything else in user space. The driver has an <firstterm>Application Programming Interface</firstterm> (<acronym>API</acronym>), referred to as <quote>Team Netlink API</quote>, which implements Netlink communications. User-space applications can use this API to communicate with the driver. A library, referred to as <quote>lib</quote>, has been provided to do user space wrapping of Team Netlink communications and RT Netlink messages. An application daemon, <systemitem class="daemon">teamd</systemitem>, which uses Libteam lib is also provided. One instance of <systemitem class="daemon">teamd</systemitem> can control one instance of the Team driver. The daemon implements the load-balancing and active-backup logic, such as round-robin, by using additional code referred to as <quote>runners</quote>. By separating the code in this way, the Network Teaming implementation presents an easily extensible and scalable solution for load-balancing and redundancy requirements. For example, custom runners can be relatively easily written to implement new logic via <systemitem class="daemon">teamd</systemitem>, and even <systemitem class="daemon">teamd</systemitem> is optional, users can write their own application to use <application>libteam</application>. + </para> + <para> + A tool to control a running instance of <systemitem class="daemon">teamd</systemitem> using D-bus is provided by <application>teamdctl</application>. It provides a D-Bus wrapper around the <systemitem class="daemon">teamd</systemitem> D-Bus API. By default, <systemitem class="daemon">teamd</systemitem> listens and communicates using Unix Domain Sockets but still monitors D-Bus. This is to ensure that <systemitem class="daemon">teamd</systemitem> can be used in environments where D-Bus is not present or not yet loaded. For example, when booting over <systemitem class="daemon">teamd</systemitem> links D-Bus would not yet be loaded. The <application>teamdctl</application> tool can be used during run time to read the configuration, the state of link-watchers, check and change the state of ports, add and remove ports, and to change ports between active and backup states. + </para> + <para> + Team Netlink API communicates with user-space applications using Netlink messages. The user-space library <application>libteam</application> does not directly interact with the API, but uses <application>libnl</application> or <application>teamnl</application> to interact with the driver API. + </para> + <para> + To sum up, the instances of Team driver, running in the kernel, do not get configured or controlled directly. All configuration is done with the aid of user space applications, such as the <application>teamd</application> application. The application then directs the kernel driver part accordingly. + </para> +</section> + +<section id="sec-Comparison_of_Network_Teaming_to_Bonding"> + <title>Comparison of Network Teaming to Bonding</title> + + <table id="Bonding_Teaming_Comparison" frame='all'> + <title>A Comparison of Features in Bonding and Team</title> + <tgroup cols='3' align='left' colsep='1' rowsep='1'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname="c3"/> + <thead> + <row> + <entry>Feature</entry> + <entry>Bonding</entry> + <entry>Team</entry> + </row> + </thead> + <tbody> + <row><entry>broadcast Tx policy</entry> <entry>Yes</entry> <entry>Yes</entry></row> + <row><entry>round-robin Tx policy</entry> <entry>Yes</entry> <entry>Yes</entry></row> + <row><entry>active-backup Tx policy</entry> <entry>Yes</entry> <entry>Yes</entry></row> + <row><entry>LACP (802.3ad) support</entry> <entry>Yes (passive only)</entry> <entry>Yes</entry></row> + <row><entry>Hash-based Tx policy</entry> <entry>Yes</entry> <entry>Yes</entry></row> + <row><entry>User can set hash function</entry> <entry>No</entry> <entry>Yes</entry></row> + <row><entry>Tx load-balancing support (TLB)</entry> <entry>Yes</entry> <entry>Yes</entry></row> + <row><entry>LACP hash port select</entry> <entry>Yes</entry> <entry>Yes</entry></row> + <row><entry>load-balancing for LACP support</entry> <entry>No</entry> <entry>Yes</entry></row> + <row><entry>Ethtool link monitoring</entry> <entry>Yes</entry> <entry>Yes</entry></row> + <row><entry>ARP link monitoring</entry> <entry>Yes</entry> <entry>Yes</entry></row> + <row><entry>NS/NA (IPv6) link monitoring</entry> <entry>No</entry> <entry>Yes</entry></row> + <row><entry>ports up/down delays</entry> <entry>Yes</entry> <entry>Yes</entry></row> + <row><entry>port priorities and stickiness (<quote>primary</quote> option enhancement)</entry> <entry>No</entry> <entry>Yes</entry></row> + <row><entry>separate per-port link monitoring setup</entry> <entry>No</entry> <entry>Yes</entry></row> + <row><entry>multiple link monitoring setup</entry> <entry>Limited</entry> <entry>Yes</entry></row> + <row><entry>lockless Tx/Rx path</entry> <entry>Yes (RCU)</entry> <entry>Yes (RCU)</entry></row> + <row><entry>VLAN support</entry> <entry>Yes</entry> <entry>Yes</entry></row> + <row><entry>user-space runtime control</entry> <entry>Limited</entry> <entry>Full</entry></row> + <row><entry>Logic in user-space</entry> <entry>No</entry> <entry>Yes</entry></row> + <row><entry>Extensibility</entry> <entry>Hard</entry> <entry>Easy</entry></row> + <row><entry>Modular design</entry> <entry>No</entry> <entry>Yes</entry></row> + <row><entry>Performance overhead</entry> <entry>Low</entry> <entry>Very Low</entry></row> + <row><entry>D-Bus interface</entry> <entry>No</entry> <entry>Yes</entry></row> + <row><entry>multiple device stacking</entry> <entry>Yes</entry> <entry>Yes</entry></row> + <row><entry>zero config using LLDP</entry> <entry>No</entry> <entry>(in planning)</entry></row> + <row><entry>NetworkManager support</entry> <entry>Yes</entry> <entry>Yes</entry></row> +</tbody> +</tgroup> + + </table> +</section> + +<section id="sec-Team-Understanding_the_Default_Behavior_of_Master_and_Slave_Interfaces"> +<title>Understanding the Default Behavior of Master and Slave Interfaces</title> +<para> +When controlling teamed port interfaces using the <systemitem class="daemon">NetworkManager</systemitem> daemon, and especially when fault finding, keep the following in mind: +<orderedlist> + <listitem> + <para> + Starting the master interface does not automatically start the port interfaces. + </para> + </listitem> + <listitem> + <para> + Starting a port interface always starts the master interface. + </para> + </listitem> + <listitem> + <para> + Stopping the master interface also stops the port interfaces. + </para> + </listitem> + <listitem> + <para> + A master without ports can start static <systemitem class="protocol">IP</systemitem> connections. + </para> + </listitem> + <listitem> + <para> + A master without ports waits for ports when starting <systemitem class="protocol">DHCP</systemitem> connections. + </para> + </listitem> + <listitem> + <para> + A master with a <systemitem class="protocol">DHCP</systemitem> connection waiting for ports completes when a port with a carrier is added. + </para> + </listitem> + <listitem> + <para> + A master with a <systemitem class="protocol">DHCP</systemitem> connection waiting for ports continues waiting when a port without a carrier is added. + </para> + </listitem> +</orderedlist> +</para> + +<warning> + <para> + The use of direct cable connections without network switches is not supported for teaming. The failover mechanisms described here will not work as expected without the presence of network switches. +</para> +</warning> +</section> + +<section id="sec-Understanding_the_Network_Teaming_Daemon_and_the_Runners"> + <title>Understanding the Network Teaming Daemon and the "Runners"</title> + <para> +The Team daemon, <systemitem class="daemon">teamd</systemitem>, uses <application>libteam</application> to control one instance of the team driver. This instance of the team driver adds instances of a hardware device driver to form a <quote>team</quote> of network links. The team driver presents a network interface, <interface>team0</interface> for example, to the other parts of the kernel. The interfaces created by instances of the team driver are given names such as <interface>team0</interface>, <interface>team1</interface>, and so forth in the documentation. This is for ease of understanding and other names can be used. The logic common to all methods of teaming is implemented by <systemitem class="daemon">teamd</systemitem>; those functions that are unique to the different load sharing and backup methods, such as round-robin, are implemented by separate units of code referred to as <quote>runners</quote>. Because words such as <quote>module</quote> and <quote>mode</quote> already have specific meanings in relation to the kernel, the word <quote>runner</quote> was chosen to refer to these units of code. The user specifies the runner in the JSON format configuration file and the code is then compiled into an instance of <systemitem class="daemon">teamd</systemitem> when the instance is created. A runner is not a plug-in because the code for a runner is compiled into an instance of <systemitem class="daemon">teamd</systemitem> as it is being created. Code could be created as a plug-in for <systemitem class="daemon">teamd</systemitem> should the need arise. + </para> + <para> + The following runners are available at time of writing. + <itemizedlist> + <listitem> + <para> + broadcast (data is transmitted over all ports) + </para> + </listitem> + <listitem> + <para> + round-robin (data is transmitted over all ports in turn) + </para> + </listitem> + <listitem> + <para> + active-backup (one port or link is used while others are kept as a backup) + </para> + </listitem> + <listitem> + <para> + loadbalance (with active Tx load balancing and BPF-based Tx port selectors) + </para> + </listitem> + <listitem> + <para> + lacp (implements the 802.3ad Link Aggregation Control Protocol) + </para> + </listitem> + </itemizedlist> + </para> + <para> + In addition, the following link-watchers are available: + <itemizedlist> + <listitem> + <para> + <application>ethtool</application> (Libteam lib uses <application>ethtool</application> to watch for link state changes). This is the default if no other link-watcher is specified in the configuration file. + </para> + </listitem> + <listitem> + <para> + <application>arp_ping</application> (The <application>arp_ping</application> utility is used to monitor the presence of a far-end hardware address using ARP packets.) + </para> + </listitem> + <listitem> + <para> + <application>nsna_ping</application> (Neighbor Advertisements and Neighbor Solicitation from the <systemitem class="protocol">IPv6</systemitem> Neighbor Discovery protocol are used to monitor the presence of a neighbor's interface) + </para> + </listitem> + </itemizedlist> + There are no restrictions in the code to prevent a particular link-watcher from being used with a particular runner, however when using the <application>lacp</application> runner, <application>ethtool</application> is the only recommended link-watcher. + </para> +</section> +<!--Topics, Tasks:--> + <section id="sec-Install_the_Network_Teaming_Daemon"> + <title>Install the Network Teaming Daemon</title> + <para> + The networking teaming daemon, <systemitem class="daemon">teamd</systemitem>, is not installed by default. To install <systemitem class="daemon">teamd</systemitem>, issue the following command as <systemitem class="username">root</systemitem>: + <screen>~]# <command>dnf install teamd</command></screen> + </para> +</section> + +<section id="sec-Converting_a_Bond_to_a_Team"> + <title>Converting a Bond to a Team</title> + <para> + It is possible to convert existing bonding configuration files to team configuration files using the <application>bond2team</application> tool. It can convert bond configuration files in <filename>ifcfg</filename> format to team configuration files in either <filename>ifcfg</filename> or JSON format. Note that firewall rules, alias interfaces, and anything that might be tied to the original interface name can break after the renaming because the tool will only change the <filename>ifcfg</filename> file, nothing else. + </para> + <para> + To see some examples of the command format, issue the following command: + <screen>~]$ <command>bond2team --examples</command></screen> + New files will be created in a directory whose name starts with <filename class="directory">/tmp/bond2team.XXXXXX/</filename>, where XXXXXX is a random string. After creating the new configuration files, move the old bonding files to a backup folder and then move the new files to the <filename class="directory">/etc/sysconfig/network-scripts/</filename> directory. + </para> + +<example id="ex-Convert_a_Bond_to_a_Team"> + <title>Convert a Bond to a Team</title> + <para> + To convert a current <literal>bond0</literal> configuration to team <literal>ifcfg</literal>, issue a command as <systemitem class="username">root</systemitem>: +<screen>~]# <command>/usr/bin/bond2team --master bond0</command></screen> +Note that this will retain the name <literal>bond0</literal>. To use a new name to save the configuration, use the <option>--rename</option> as follows: +<screen>~]# <command>/usr/bin/bond2team --master bond0 --rename team0</command></screen> +add the <option>--json</option> option to output JSON format files instead of <literal>ifcfg</literal> files. See the <filename>teamd.conf(5)</filename> man page for examples of JSON format. + </para> +</example> + +<example id="ex_Convert_a_Bond_to_a_Team_and_Specify_the_File_Path"> +<title>Convert a Bond to a Team and Specify the File Path</title> + <para> + To convert a current <literal>bond0</literal> configuration to team <literal>ifcfg</literal>, and to manually specify the path to the <literal>ifcfg</literal> file, issue a command as <systemitem class="username">root</systemitem>: +<screen>~]# <command>/usr/bin/bond2team --master bond0 --configdir <replaceable>/path/to/ifcfg-file</replaceable></command></screen> +add the <option>--json</option> option to output JSON format files instead of <literal>ifcfg</literal> files. + </para> +</example> + +<example id="ex_Create_a_Team_Configuration_Using_Bond2team"> +<title>Create a Team Configuration Using Bond2team</title> + <para> + It is also possible to create a team configuration by supplying the <application>bond2team</application> tool with a list of bonding parameters. For example: + <screen>~]# <command>/usr/bin/bond2team --bonding_opts "mode=1 miimon=500"</command></screen> + Ports can also be supplied on the command line as follows: +<screen>~]# <command>/usr/bin/bond2team --bonding_opts "mode=1 miimon=500 primary=eth1 \</command> + <command>primary_reselect-0" --port eth1 --port eth2 --port eth3 --port eth4</command></screen> + </para> + </example> + +<para> + See the <filename>bond2team(1)</filename> man page for further details. For an explanation of bonding parameters, see <xref linkend="sec-Using_Channel_Bonding" /> +</para> +</section> + +<section id="sec-Selecting_Interfaces_to_Use_as_Port_for_a_Network_Team"> + <title>Selecting Interfaces to Use as Ports for a Network Team</title> + <para> + To view the available interfaces, issue the following command: + <screen>~]$ <command>ip link show</command> +1: lo: <LOOPBACK,UP,LOWER_UP > mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT + link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 +2: em1: <BROADCAST,MULTICAST,UP,LOWER_UP > mtu 1500 qdisc pfifo_fast state UP mode DEFAULT qlen 1000 + link/ether 52:54:00:6a:02:8a brd ff:ff:ff:ff:ff:ff +3: em2: <BROADCAST,MULTICAST,UP,LOWER_UP > mtu 1500 qdisc pfifo_fast state UP mode DEFAULT qlen 1000 +link/ether 52:54:00:9b:6d:2a brd ff:ff:ff:ff:ff:ff</screen> +From the available interfaces, determine which are suitable for adding to your network team and then proceed to <xref linkend="sec-Selecting_Network_Team_Configuration_Methods"/> + </para> + <note> + <para> + The Team developers prefer the term <quote>port</quote> rather than <quote>slave</quote>, however <application>NetworkManager</application> uses the term <quote>team-slave</quote> to refer to interfaces that make up a team.</para> + </note> +</section> + +<section id="sec-Selecting_Network_Team_Configuration_Methods"> +<title>Selecting Network Team Configuration Methods</title> + + <para> + <emphasis role="bold">To configure a network team using a graphical user interface</emphasis>, see <xref linkend="sec-Creating_a_Network_Team_Using_a_GUI" /> + </para> + + <para> + <emphasis role="bold">To create a network team using the Team daemon</emphasis>, <systemitem class="daemon">teamd</systemitem>, proceed to <xref linkend="sec-Creating_a_Network_Team_Using_teamd"/>. + </para> + + <para> + <emphasis role="bold">To create a network team using configuration files</emphasis>, proceed to <xref linkend="sec-Creating_a_Network_Team_Using_ifcfg_Files" />. + </para> + + <para> + <emphasis role="bold">To create a network team using the command-line tool</emphasis>, <application>nmcli</application>, proceed to <xref linkend="sec-Configure_Network_Teaming_Using_nmcli"/>. + </para> + +</section> + + <section id="sec-Creating_a_Network_Team_Using_a_GUI"> + <title>Creating a Network Team Using a GUI</title> +<section + id="sec-Establishing_a_Team_Connection"> + <title>Establishing a Team Connection</title> + <para>You can use the GNOME <application>control-center</application> utility to direct <application>NetworkManager</application> to create a team from two or more Wired or InfiniBand connections. It is not necessary to create the connections to be teamed first. They can be configured as part of the process to configure the team. You must have the MAC addresses of the interfaces available in order to complete the configuration process.</para> + + <procedure + id="procedure-Adding_a_New_Team_Connection"> + <title>Adding a New Team Connection</title> + <para>You can configure a team connection by opening the <guilabel>Network</guilabel> window, clicking the plus symbol, and selecting <guilabel>Team</guilabel> from the list.</para> + + <step> + <para>Press the <keycap>Super</keycap> key to enter the Activities Overview, type <command>control network</command> and then press <keycap>Enter</keycap>. The <application>Network</application> settings tool appears.</para> + </step> + + <step> + <para>Click the plus symbol to open the selection list. Select <guilabel>Team</guilabel>. The <guilabel>Editing Team Connection <replaceable>1</replaceable></guilabel> window appears.</para> + </step> + <step> + <para>On the <guilabel>Team</guilabel> tab, click <guibutton>Add</guibutton> and select the type of interface you want to use with the team connection. Click the <guibutton>Create</guibutton> button. Note that the dialog to select the port type only comes up when you create the first port; after that, it will automatically use that same type for all further ports.</para> + </step> + <step> + <para>The <guilabel>Editing team0 port 1</guilabel> window appears. Fill in the MAC address of the first interface to be added to the team.</para> + </step> + <step> + <para> + If custom port settings are to be applied, click on the <guilabel>Team Port</guilabel> tab and enter a JSON configuration string or import it from a file. + </para> + </step> + <step> + <para> + Click the <guibutton>Save</guibutton> button. + </para> + </step> + <step> + <para>The name of the teamed port appears in the <guilabel>Teamed connections</guilabel> window. Click the <guibutton>Add</guibutton> button to add further port connections.</para> + </step> + <step><para>Review and confirm the settings and then click the <guilabel>Save</guilabel> button.</para> + </step> + <step> + <para>Edit the team-specific settings by referring to <xref linkend="sec-Configuring_the_Team_Tab"/> below.</para> + </step> + </procedure> + + <procedure + id="procedure-Editing_an_Existing_Team_Connection"> + <title>Editing an Existing Team Connection</title> + <para>Follow these steps to edit an existing bond connection.</para> + <step> + <para>Press the <keycap>Super</keycap> key to enter the Activities Overview, type <command>control network</command> and then press <keycap>Enter</keycap>. The <application>Network</application> settings tool appears.</para> + </step> + + <step> + <para>Select the connection you want to edit and click the <guilabel>Options</guilabel> button.</para> + </step> + <step> + <para>Select the <guilabel>General</guilabel> tab.</para> + </step> + <step> + <para>Configure the connection name, auto-connect behavior, and availability settings.</para> + <para>Five settings in the <guilabel>Editing</guilabel> dialog are common to all connection types, see the <guilabel>General</guilabel> tab: + </para> + <itemizedlist> + <listitem> + <para> + <guilabel>Connection name</guilabel> — Enter a descriptive name for your network connection. This name will be used to list this connection in the menu of the <guilabel>Network</guilabel> window. + </para> + </listitem> + <listitem> + <para> + <guilabel>Automatically connect to this network when it is available</guilabel> — Select this box if you want <application>NetworkManager</application> to auto-connect to this connection when it is available. See <xref linkend="sec-Connecting_to_a_Network_Automatically"/> for more information. + </para> + </listitem> + <listitem> + <para> + <guilabel>All users may connect to this network</guilabel> — Select this box to create a connection available to all users on the system. Changing this setting may require root privileges. See <xref linkend="sec-System-wide_and_Private_Connection_Profiles"/> for details. + </para> + </listitem> + <listitem> + <para> + <guilabel>Automatically connect to VPN when using this connection</guilabel> — Select this box if you want <application>NetworkManager</application> to auto-connect to a VPN connection when it is available. Select the VPN from the drop-down menu. + </para> + </listitem> + <listitem> + <para> + <guilabel>Firewall Zone</guilabel> — Select the firewall zone from the drop-down menu. + </para> + </listitem> + </itemizedlist> + </step> + + <step> + <para>Edit the team-specific settings by referring to <xref linkend="sec-Configuring_the_Team_Tab"/> below.</para> + </step> + </procedure> + <bridgehead + id="bh-Saving_Your_New_or_Modified_Connection_and_Making_Further_Configurations-team">Saving Your New (or Modified) Connection and Making Further Configurations</bridgehead> + + <para>Once you have finished editing your team connection, click the <guibutton>Save</guibutton> button to save your customized configuration. If the profile was in use while being edited, power cycle the connection to make <application>NetworkManager</application> apply the changes. If the profile is OFF, set it to ON. See <xref + linkend="sec-Connecting_to_a_Network_Using_a_GUI"/> for information on using your new or altered connection.</para> + <para>You can further configure an existing connection by selecting it in the <guilabel>Network</guilabel> window and clicking <guilabel>Options</guilabel> to return to the <guilabel>Editing</guilabel> dialog.</para> + <para>Then, to configure:</para> + <itemizedlist> + + <listitem> + <para><systemitem class="protocol">IPv4</systemitem> settings for the connection, click the <guilabel>IPv4 Settings</guilabel> tab and proceed to <xref + linkend="sec-Configuring_IPv4_Settings"/>; or, + </para> + </listitem> + <listitem> + <para>IPv6 settings for the connection, click the <guilabel>IPv6 Settings</guilabel> tab and proceed to <xref + linkend="sec-Configuring_IPv6_Settings"/>. + </para> + </listitem> + </itemizedlist> + +<section id="sec-Configuring_the_Team_Tab"> +<title>Configuring the Team Tab</title> + <para>If you have already added a new team connection you can enter a custom JSON configuration string in the text box or import a configuration file. Click <guilabel>Save</guilabel> to apply the JSON configuration to the team interface.</para> + <para> + For examples of JSON strings, see <xref linkend="sec-Configure_teamd_Runners" /> + </para> + <para> + See <xref linkend="procedure-Adding_a_New_Team_Connection"/> for instructions on how to add a new team. + </para> + </section> + + </section> + </section> + + +<section id="sec-Configure_a_Network_Team_Using-the_Command_Line"> + <title>Configure a Network Team Using the Command Line</title> + + + <section id="sec-Creating_a_Network_Team_Using_teamd"> + <title>Creating a Network Team Using teamd</title> + <para> + To create a network team, a JSON format configuration file is required for the virtual interface that will serve as the interface to the team of ports or links. A quick way is to copy the example configuration files and then edit them using an editor running with <systemitem class="username">root</systemitem> privileges. To list the available example configurations, enter the following command: + <screen>~]$ <command>ls /usr/share/doc/teamd-*/example_configs/</command> +activebackup_arp_ping_1.conf activebackup_multi_lw_1.conf loadbalance_2.conf +activebackup_arp_ping_2.conf activebackup_nsna_ping_1.conf loadbalance_3.conf +activebackup_ethtool_1.conf broadcast.conf random.conf +activebackup_ethtool_2.conf lacp_1.conf roundrobin_2.conf +activebackup_ethtool_3.conf loadbalance_1.conf roundrobin.conf</screen> + To view one of the included files, such as <filename>activebackup_ethtool_1.conf</filename>, enter the following command: + <screen>~]$ <command>cat /usr/share/doc/teamd-*/example_configs/activebackup_ethtool_1.conf</command> +{ + "device": "team0", + "runner": {"name": "activebackup"}, + "link_watch": {"name": "ethtool"}, + "ports": { + "eth1": { + "prio": -10, + "sticky": true + }, + "eth2": { + "prio": 100 + } + } +}</screen> + Create a working configurations directory to store <systemitem class="daemon">teamd</systemitem> configuration files. For example, as normal user, enter a command with the following format: + <screen>~]$ <command>mkdir ~/<replaceable>teamd_working_configs</replaceable></command></screen> + Copy the file you have chosen to your working directory and edit it as necessary. As an example, you could use a command with the following format: + <screen>~]$ <command>cp /usr/share/doc/teamd-*/example_configs/activebackup_ethtool_1.conf \ ~/<replaceable>teamd_working_configs</replaceable>/activebackup_ethtool_1.conf</command></screen> + To edit the file to suit your environment, for example to change the interfaces to be used as ports for the network team, open the file for editing as follows: + <screen>~]$ <command>vi ~/<replaceable>teamd_working_configs</replaceable>/activebackup_ethtool_1.conf</command></screen> + Make any necessary changes and save the file. See the <filename>vi(1)</filename> man page for help on using the <application>vi</application> editor or use your preferred editor. +</para> +<para> + Note that it is essential that the interfaces to be used as ports within the team must not be active, that is to say, they must be <quote>down</quote>, when adding them into a team device. To check their status, issue the following command: + <screen>~]$ <command>ip link show</command> +1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT + link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 +2: em1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP mode DEFAULT qlen 1000 + link/ether 52:54:00:d5:f7:d4 brd ff:ff:ff:ff:ff:ff +3: em2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP mode DEFAULT qlen 1000 + link/ether 52:54:00:d8:04:70 brd ff:ff:ff:ff:ff:ff</screen> +In this example we see that both the interfaces we plan to use are <quote>UP</quote>. +</para> +<para> + To take down an interface, issue a command as <systemitem class="username">root</systemitem> in the following format: + <screen>~]# <command>ip link set down em1</command></screen> + Repeat for each interface as necessary. +</para> +<para> + To create a team interface based on the configuration file, as <systemitem class="username">root</systemitem> user, change to the working configurations directory (<replaceable>teamd_working_configs</replaceable> in this example): + <screen>~]# <command>cd /home/<replaceable>user</replaceable><replaceable>teamd_working_configs</replaceable></command></screen> + Then issue a command in the following format: + <screen>~]# <command>teamd -g -f activebackup_ethtool_1.conf -d</command> +Using team device "team0". +Using PID file "/var/run/teamd/team0.pid" +Using config file "/home/<replaceable>user</replaceable>/teamd_working_configs/activebackup_ethtool_1.conf"</screen> + The <option>-g</option> option is for debug messages, <option>-f</option> option is to specify the configuration file to load, and the <option>-d</option> option is to make the process run as a daemon after startup. See the <filename>teamd(8)</filename> man page for other options. + </para> + +<para> + To check the status of the team, issue the following command as <systemitem class="username">root</systemitem>: + <screen>~]# <command>teamdctl team0 state</command> +setup: + runner: activebackup +ports: + em1 + link watches: + link summary: up + instance[link_watch_0]: + name: ethtool + link: up + em2 + link watches: + link summary: up + instance[link_watch_0]: + name: ethtool + link: up +runner: + active port: em1</screen> +</para> +<para> + To apply an address to the network team interface, <interface>team0</interface>, issue a command as <systemitem class="username">root</systemitem> in the following format: + <screen>~]# <command>ip addr add 192.168.23.2/24 dev team0</command></screen> + </para> + + <para> + To check the IP address of a team interface, issue a command as follows: + <screen>~]$ <command>ip addr show team0</command> +4: team0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP + link/ether 16:38:57:60:20:6f brd ff:ff:ff:ff:ff:ff + inet 192.168.23.2/24 scope global team0 + valid_lft forever preferred_lft forever + inet6 2620:52:0:221d:1438:57ff:fe60:206f/64 scope global dynamic + valid_lft 2591880sec preferred_lft 604680sec + inet6 fe80::1438:57ff:fe60:206f/64 scope link + valid_lft forever preferred_lft forever</screen> + </para> + +<para> + To activate the team interface, or to bring it <quote>up</quote>, issue a command as <systemitem class="username">root</systemitem> in the following format: + <screen>~]# <command>ip link set dev team0 up</command></screen> +</para> + +<para> + To temporarily deactivate the team interface, or to take it <quote>down</quote>, issue a command as <systemitem class="username">root</systemitem> in the following format: + <screen>~]# <command>ip link set dev team0 down</command></screen> +</para> + +<para> + To terminate, or kill, an instance of the team daemon, as <systemitem class="username">root</systemitem> user, issue a command in the following format: + <screen>~]# <command>teamd -t team0 -k</command></screen> + The <option>-k</option> option is to specify that the instance of the daemon associated with the device <interface>team0</interface> is to be killed. See the <filename>teamd(8)</filename> man page for other options. +</para> + + <para> + For help on command-line options for <systemitem class="daemon">teamd</systemitem>, issue the following command: + <screen>~]$ <command>teamd -h</command></screen> + In addition, see the <filename>teamd(8)</filename> man page. + </para> + +</section> + + +<section id="sec-Creating_a_Network_Team_Using_ifcfg_Files"> + <title>Creating a Network Team Using ifcfg Files</title> + <para> + To create a networking team using <literal>ifcfg</literal> files, create a file in the <filename class="directory">/etc/sysconfig/network-scripts/</filename> directory as follows: + <screen>DEVICE=team0 +DEVICETYPE=Team +ONBOOT=yes +BOOTPROTO=none +IPADDR=192.168.11.1 +PREFIX=24 +TEAM_CONFIG='{"runner": {"name": "activebackup"}, "link_watch": {"name": "ethtool"}}'</screen> +This creates the interface to the team, in other words, this is the master. + </para> + <para> + To create a port to be a member of <interface>team0</interface>, create one or more files in the <filename class="directory">/etc/sysconfig/network-scripts/</filename> directory as follows: + <screen>DEVICE=eth1 +HWADDR=D4:85:64:01:46:9E +DEVICETYPE=TeamPort +ONBOOT=yes +TEAM_MASTER=team0 +TEAM_PORT_CONFIG='{"prio": 100}'</screen> +Add additional port interfaces similar to the above as required, changing the DEVICE and HWADDR field to match the ports (the network devices) being added. If port priority is not specified by <literal>prio</literal> it defaults to <literal>0</literal>; it accepts negative and positive values in the range <literal>-32,767</literal> to <literal>+32,767</literal>. +</para> + <para> + Specifying the hardware or MAC address using the <command>HWADDR</command> directive will influence the device naming procedure. This is explained in <xref linkend="ch-Consistent_Network_Device_Naming" />. + </para> + + +<para> + To bring up the network team, issue the following command as <systemitem class="username">root</systemitem>: + <screen>~]# <command>ifup team0</command></screen> + To view the network team, issue the following command: + <screen>~]$ <command>ip link show</command></screen> +</para> + +</section> + +<section id="sec-Add_a_port_to_a_Network_Team_Using_iputils"> + <title>Add a Port to a Network Team Using iputils</title> + <para> + To add a port <interface>em1</interface> to a network team <interface>team0</interface>, using the <application>ip</application> utility, issue the following commands as <systemitem class="username">root</systemitem>: + <screen>~]# <command>ip link set dev em1 down</command> +~]# <command>ip link set dev em1 master team0</command></screen> + Add additional ports as required. Team driver will bring ports up automatically. + </para> +</section> + +<section id="sec-Listing_the_ports_of_a_Team_Using_teamnl"> + <title>Listing the ports of a Team Using teamnl</title> + <para> + To view or list the ports in a network team, using the <application>teamnl</application> utility, issue the following command as <systemitem class="username">root</systemitem>: + <screen>~]# <command>teamnl team0 ports</command> +em2: up 100 fullduplex +em1: up 100 fullduplex</screen> + </para> +</section> + +<section id="sec-Configuring_Options_of_a_Team_Using_teamnl"> + <title>Configuring Options of a Team Using teamnl</title> + <para> + To view or list all currently available options, using the <application>teamnl</application> utility, issue the following command as <systemitem class="username">root</systemitem>: + <screen>~]# <command>teamnl team0 options</command></screen> + To configure a team to use active backup mode, issue the following command as <systemitem class="username">root</systemitem>: + <screen>~]# <command>teamnl team0 setoption mode activebackup</command></screen> + </para> +</section> + + +<section id="sec-Add_an_address_to_a_Network_Team_Using_iputils"> + <title>Add an Address to a Network Team Using iputils</title> + <para> + To add an address to a team <interface>team0</interface>, using the <application>ip</application> utility, issue the following command as <systemitem class="username">root</systemitem>: + <screen>~]# <command>ip addr add 192.168.252.2/24 dev team0</command></screen> + </para> +</section> + +<section id="sec-Bring_Up_an_interface_to_a_Network_Team_Using_iputils"> + <title>Bring up an Interface to a Network Team Using iputils</title> + <para> + To activate or <quote>bring up</quote> an interface to a network team, <interface>team0</interface>, using the <application>ip</application> utility, issue the following command as <systemitem class="username">root</systemitem>: + <screen>~]# <command>ip link set team0 up</command></screen> + </para> +</section> + +<section id="sec-Viewing_the_Active_Ports_of_a_Team_Using_teamnl"> + <title>Viewing the Active Port Options of a Team Using teamnl</title> + <para> + To view or list the <option>activeport</option> option in a network team, using the <application>teamnl</application> utility, issue the following command as <systemitem class="username">root</systemitem>: + <screen>~]# <command>teamnl team0 getoption activeport</command> +0</screen> + </para> +</section> + +<section id="sec-Setting_the_Active_Ports_of_a_Team_Using_teamnl"> + <title>Setting the Active Port Options of a Team Using teamnl</title> + <para> + To set the <option>activeport</option> option in a network team, using the <application>teamnl</application> utility, issue the following command as <systemitem class="username">root</systemitem>: + <screen>~]# <command>teamnl team0 setoption activeport 5</command></screen> +To check the change in team port options, issue the following command as <systemitem class="username">root</systemitem>: +<screen>~]# <command>teamnl team0 getoption activeport</command> +5</screen> + </para> +</section> + +</section> + +<section id="sec-Controlling_teamd_with_teamdctl"> + <title>Controlling teamd with teamdctl</title> + + <para> + In order to query a running instance of <systemitem class="daemon">teamd</systemitem> for statistics or configuration information, or to make changes, the control tool <application>teamdctl</application> is used. + </para> +<para> +To view the current team state of a team <interface>team0</interface>, enter the following command as <systemitem class="username">root</systemitem>: + <screen>~]# <command>teamdctl team0 state view</command></screen> + For a more verbose output: + <screen>~]# <command>teamdctl team0 state view -v</command></screen> +</para> + +<para> +For a complete state dump in JSON format (useful for machine processing) of <interface>team0</interface>, use the following command: + <screen>~]# <command>teamdctl team0 state dump</command></screen> +</para> + +<para> +For a configuration dump in JSON format of <interface>team0</interface>, use the following command: + <screen>~]# <command>teamdctl team0 config dump</command></screen> +</para> + +<para> +To view the configuration of a port <interface>em1</interface>, that is part of a team <interface>team0</interface>, enter the following command: + <screen>~]# <command>teamdctl team0 port config dump em1</command></screen> +</para> + +<section id="sec-Add_a_port_to_a_Network_Team"> + <title>Add a Port to a Network Team</title> + <para> + To add a port <interface>em1</interface> to a network team <interface>team0</interface>, issue the following command as <systemitem class="username">root</systemitem>: + <screen>~]# <command>teamdctl team0 port add em1</command></screen> + </para> +</section> + +<section id="sec-Remove_a_Port_From_a_Network_Team"> + <title>Remove a Port From a Network Team</title> + <para> + To remove an interface <interface>em1</interface> from a network team <interface>team0</interface>, issue the following command as <systemitem class="username">root</systemitem>: + <screen>~]# <command>teamdctl team0 port remove em1</command></screen> + </para> + </section> + + + <section id="sec-Apply_a_Configuration_to_a_Port_in_a_Network_Team"> + <title>Apply a Configuration to a Port in a Network Team</title> + <para> + To apply a JSON format configuration to a port <interface>em1</interface> in a network team <interface>team0</interface>, issue a command as <systemitem class="username">root</systemitem> in the following format: + <screen>~]# <command>teamdctl team0 port config update em1 <replaceable>JSON-config-string</replaceable></command></screen> + Where <replaceable>JSON-config-string</replaceable> is the configuration as a string of text in JSON format. This will update the configuration of the port using the JSON format string supplied. An example of a valid JSON string for configuring a port would be the following: + <screen> +{ + "prio": -10, + "sticky": true +}</screen> +Use single quotes around the JSON configuration string and omit the line breaks. + </para> + <para> + Note that the old configuration will be overwritten and that any options omitted will be reset to the default values. See the <filename>teamdctl(8)</filename> man page for more team daemon control tool command examples.</para> +</section> + + <section id="sec-View_the_Configuration_of_a_Port_in_a_Network_Team"> + <title>View the Configuration of a Port in a Network Team</title> + <para> + To copy the configuration of a port <interface>em1</interface> in a network team <interface>team0</interface>, issue the following command as <systemitem class="username">root</systemitem>: + <screen>~]# <command>teamdctl team0 port config dump em1</command></screen> + This will dump the JSON format configuration of the port to standard output. + </para> +</section> +</section> + + <section id="sec-Configure_teamd_Runners"> + <title>Configure teamd Runners</title> + <para> + Runners are units of code which are compiled into the Team daemon when an instance of the daemon is created. For an introduction to the <systemitem class="daemon">teamd</systemitem> runners, see <xref linkend="sec-Understanding_the_Network_Teaming_Daemon_and_the_Runners" />. + </para> + + <section id="sec-Configure_the_broadcast_Runner"> + <title>Configure the broadcast Runner</title> + <para> + To configure the broadcast runner, using an editor as <systemitem class="username">root</systemitem>, add the following to the team JSON format configuration file: + <screen> +{ + "device": "team0", + "runner": {"name": "broadcast"}, + "ports": {"em1": {}, "em2": {}} +}</screen> + </para> +<para> +Please see the <filename>teamd.conf(5)</filename> man page for more information. +</para> +</section> + + <section id="sec-Configure_the_random_Runner"> + <title>Configure the random Runner</title> + <para> + The random runner behaves similarly to the roundrobin runner. + </para> + <para> + To configure the random runner, using an editor as <systemitem class="username">root</systemitem>, add the following to the team JSON format configuration file: + <screen> +{ + "device": "team0", + "runner": {"name": "random"}, + "ports": {"em1": {}, "em2": {}} +}</screen> + </para> +<para> +Please see the <filename>teamd.conf(5)</filename> man page for more information. +</para> +</section> + +<section id="sec-Configure_the_roundrobin_Runner"> + <title>Configure the roundrobin Runner</title> + <para> + To configure the roundrobin runner, using an editor as <systemitem class="username">root</systemitem>, add the following to the team JSON format configuration file: + <screen> +{ + "device": "team0", + "runner": {"name": "roundrobin"}, + "ports": {"em1": {}, "em2": {}} +}</screen> + A very basic configuration for roundrobin. + </para> +<para> +Please see the <filename>teamd.conf(5)</filename> man page for more information. +</para> +</section> +<section id="sec-Configure_the_activebackup_Runner"> +<title>Configure the activebackup Runner</title> +<para> + The active backup runner can use all of the link-watchers to determine the status of links in a team. Any one of the following examples can be added to the team JSON format configuration file: + </para> +<para> + <screen> +{ + "device": "team0", + "runner": { + "name": "activebackup" + }, + "link_watch": { + "name": "ethtool" + }, + "ports": { + "em1": { + "prio": -10, + "sticky": true + }, + "em2": { + "prio": 100 + } + } +}</screen> + This example configuration uses the active-backup runner with <application>ethtool</application> as the link watcher. Port <interface>em2</interface> has higher priority. The sticky flag ensures that if <interface>em1</interface> becomes active, it stays active as long as the link remains up. +</para> + + <para> + <screen> +{ + "device": "team0", + "runner": { + "name": "activebackup" + }, + "link_watch": { + "name": "ethtool" + }, + "ports": { + "em1": { + "prio": -10, + "sticky": true, + "queue_id": 4 + }, + "em2": { + "prio": 100 + } + } +}</screen> + This example configuration adds a queue ID of <literal>4</literal>. It uses active-backup runner with <application>ethtool</application> as the link watcher. Port <interface>em2</interface> has higher priority. But the sticky flag ensures that if <interface>em1</interface> becomes active, it will stay active as long as the link remains up. + </para> + + <para> + To configure the activebackup runner using <application>ethtool</application> as the link watcher and applying a delay, using an editor as <systemitem class="username">root</systemitem>, add the following to the team JSON format configuration file: + <screen> +{ + "device": "team0", + "runner": { + "name": "activebackup" + }, + "link_watch": { + "name": "ethtool", + "delay_up": 2500, + "delay_down": 1000 + }, + "ports": { + "em1": { + "prio": -10, + "sticky": true + }, + "em2": { + "prio": 100 + } + } +}</screen> + This example configuration uses the active-backup runner with <application>ethtool</application> as the link watcher. Port <interface>em2</interface> has higher priority. But the sticky flag ensures that if <interface>em1</interface> becomes active, it stays active while the link remains up. Link changes are not propagated to the runner immediately, but delays are applied. + </para> +<para> +Please see the <filename>teamd.conf(5)</filename> man page for more information. +</para> +</section> +<section id="sec-Configure_the_loadbalance_Runner"> +<title>Configure the loadbalance Runner</title> +<para> + This runner can be used for two types of load balancing, active and passive. In active mode, constant re-balancing of traffic is done by using statistics of recent traffic to share out traffic as evenly as possible. In static mode, streams of traffic are distributed randomly across the available links. This has a speed advantage due to lower processing overhead. In high volume traffic applications this is often preferred as traffic usually consists of multiple stream which will be distributed randomly between the available links, in this way load sharing is accomplished without intervention by <systemitem class="daemon">teamd</systemitem>. +</para> +<para> + To configure the loadbalance runner for passive transmit (Tx) load balancing, using an editor as <systemitem class="username">root</systemitem>, add the following to the team JSON format configuration file: + <screen> +{ + "device": "team0", + "runner": { + "name": "loadbalance", + "tx_hash": ["eth", "ipv4", "ipv6"] + }, + "ports": {"em1": {}, "em2": {}} +}</screen> + Configuration for hash-based passive transmit (Tx) load balancing. + </para> + +<para> + To configure the loadbalance runner for active transmit (Tx) load balancing, using an editor as <systemitem class="username">root</systemitem>, add the following to the team JSON format configuration file: + <screen> +{ + "device": "team0", + "runner": { + "name": "loadbalance", + "tx_hash": ["eth", "ipv4", "ipv6"], + "tx_balancer": { + "name": "basic" + } + }, + "ports": {"em1": {}, "em2": {}} +}</screen> + Configuration for active transmit (Tx) load balancing using basic load balancer. + </para> +<para> +Please see the <filename>teamd.conf(5)</filename> man page for more information. +</para> +</section> + +<section id="sec-Configure_the_LACP_Runner"> +<title>Configure the LACP (802.3ad) Runner</title> +<para> + To configure the LACP runner using <application>ethtool</application> as a link watcher, using an editor as <systemitem class="username">root</systemitem>, add the following to the team JSON format configuration file: + <screen> +{ + "device": "team0", + "runner": { + "name": "lacp", + "active": true, + "fast_rate": true, + "tx_hash": ["eth", "ipv4", "ipv6"] + }, + "link_watch": {"name": "ethtool"}, + "ports": {"em1": {}, "em2": {}} +}</screen> + Configuration for connection to a <firstterm>link aggregation control protocol</firstterm> (<acronym>LACP</acronym>) capable counterpart. The LACP runner should use <application>ethtool</application> to monitor the status of a link. It does not make sense to use any other link monitoring method besides the <application>ethtool</application> because, for example in the case of <application>arp_ping</application>, the link would never come up. The reason is that the link has to be established first and only after that can packets, ARP included, go through. Using <application>ethtool</application> prevents this because it monitors each link layer individually.</para> + <para> + Active load balancing is possible with this runner in the same way as it is done for the loadbalance runner. To enable active transmit (Tx) load balancing, add the following section: + <screen>"tx_balancer": { + "name": "basic" +}</screen> +</para> +<para> +Please see the <filename>teamd.conf(5)</filename> man page for more information. +</para> +</section> + + <section id="sec-Configure_Monitoring_of_the_Link_State"> + <title>Configure Monitoring of the Link State</title> + <para> + The following methods of link state monitoring are available. To implement one of the methods, add the JSON format string to the team JSON format configuration file using an editor running with <systemitem class="username">root</systemitem> privileges. + </para> + <section id="sec-Configure_Ethtool_for_Link-state_Monitoring"> + <title>Configure Ethtool for link-state Monitoring</title> + <para> + To add or edit an existing delay, in milliseconds, between the link coming up and the runner being notified about it, add or edit a section as follows: + <screen> +"link_watch": { + "name": "ethtool", + "delay_up": 2500 +}</screen> + </para> + <para> + To add or edit an existing delay, in milliseconds, between the link going down and the runner being notified about it, add or edit a section as follows: + <screen> +"link_watch": { + "name": "ethtool", + "delay_down": 1000 +}</screen> + </para> +</section> + + <section id="sec-Configure_ARP_Ping_for_Link-state_Monitoring"> + <title>Configure ARP Ping for Link-state Monitoring</title> + <para> + The team daemon <systemitem class="daemon">teamd</systemitem> sends an ARP REQUEST to an address at the remote end of the link in order to determine if the link is up. The method used is the same as the <application>arping</application> utility but it does not use that utility. + </para> + <para> + Prepare a file containing the new configuration in JSON format similar to the following example: + <screen> +{ + "device": "team0", + "runner": {"name": "activebackup"}, + "link_watch":{ + "name": "arp_ping", + "interval": 100, + "missed_max": 30, + "source_host": "192.168.23.2", + "target_host": "192.168.23.1" + }, + "ports": { + "em1": { + "prio": -10, + "sticky": true + }, + "em2": { + "prio": 100 + } + } +}</screen> + This configuration uses <application>arp_ping</application> as the link watcher. The <option>missed_max</option> option is a limit value of the maximum allowed number of missed replies (ARP replies for example). It should be chosen in conjunction with the <option>interval</option> option in order to determine the total time before a link is reported as down. + </para> + <para> + To load a new configuration for a team port <interface>em2</interface>, from a file containing a JSON configuration, issue the following command as <systemitem class="username">root</systemitem>: + <screen>~]# port config update em2 <replaceable>JSON-config-file</replaceable></screen> + Note that the old configuration will be overwritten and that any options omitted will be reset to the default values. See the <filename>teamdctl(8)</filename> man page for more team daemon control tool command examples. + </para> + </section> + <section id="sec-Configure_IPv6_NA_NS_for_Link-state_Monitoring"> + <title>Configure IPv6 NA/NS for Link-state Monitoring</title> + <para> + <screen> +{ + "device": "team0", + "runner": {"name": "activebackup"}, + "link_watch": { + "name": "nsna_ping", + "interval": 200, + "missed_max": 15, + "target_host": "fe80::210:18ff:feaa:bbcc" + }, + "ports": { + "em1": { + "prio": -10, + "sticky": true + }, + "em2": { + "prio": 100 + } + } +}</screen> + </para> + <para> + To configure the interval between sending NS/NA packets, add or edit a section as follows: + <screen> +"link_watch": { + "name": "nsna_ping", + "interval": 200 +}</screen> + Value is positive number in milliseconds. It should be chosen in conjunction with the <option>missed_max</option> option in order to determine the total time before a link is reported as down. + </para> + + <para> + To configure the maximum number of missed NS/NA reply packets to allow before reporting the link as down, add or edit a section as follows: + <screen> +"link_watch": { + "name": "nsna_ping", + "missed_max": 15 +}</screen> + Maximum number of missed NS/NA reply packets. If this number is exceeded, the link is reported as down. The <option>missed_max</option> option is a limit value of the maximum allowed number of missed replies (ARP replies for example). It should be chosen in conjunction with the <option>interval</option> option in order to determine the total time before a link is reported as down. + </para> + + <para> + To configure the host name that is resolved to the <systemitem class="protocol">IPv6</systemitem> address target address for the NS/NA packets, add or edit a section as follows: + <screen> +"link_watch": { + "name": "nsna_ping", + "target_host": "MyStorage" +}</screen> +The <quote>target_host</quote> option contains the host name to be converted to an <systemitem class="protocol">IPv6</systemitem> address which will be used as the target address for the NS/NA packets. An <systemitem class="protocol">IPv6</systemitem> address can be used in place of a host name. + </para> +<para> +Please see the <filename>teamd.conf(5)</filename> man page for more information. +</para> + </section> + + </section> + + <section id="sec-Configure_Port_Selection_Override"> + <title>Configure Port Selection Override</title> +<para> +The physical port which transmits a frame is normally selected by the kernel part of the team driver, and is not relevant to the user or system administrator. The output port is selected using the policies of the selected team mode (<systemitem class="daemon">teamd</systemitem> runner). On occasion however, it is helpful to direct certain classes of outgoing traffic to certain physical interfaces to implement slightly more complex policies. By default the team driver is multiqueue aware and 16 queues are created when the driver initializes (see <ulink url="https://www.kernel.org/doc/Documentation/networking/multiqueue.txt">https://www.kernel.org/doc/Documentation/networking/multiqueue.txt</ulink> for details). If more or less queues are desired, the Netlink attribute <command>tx_queues</command> can be used to change this value during the team driver instance creation. + </para> + <para> +The queue ID for a port can be set by the port configuration option <option>queue_id</option> as follows: +<screen> +{ + "queue_id": 3 +}</screen> +These queue ID's can be used in conjunction with the <application>tc</application> utility to configure a multiqueue queue discipline and filters to bias certain traffic to be transmitted on certain port devices. For example, if using the above configuration and wanting to force all traffic bound to <systemitem class="ipaddress">192.168.1.100</systemitem> to use <interface>eth1</interface> in the team as its output device, issue commands as <systemitem class="username">root</systemitem> in the following format: +<screen>~]# <command>tc qdisc add dev team0 handle 1 root multiq</command> +~]# <command>tc filter add dev team0 protocol ip parent 1: prio 1 u32 match ip dst \</command> +<command> 192.168.1.100 action skbedit queue_mapping 3</command></screen> +This mechanism of overriding runner selection logic in order to bind traffic to a specific port can be used with all runners. +</para> + </section> + + <section id="sec-Configure_BPF-based_Tx_Port_Selectors_for_Hash_Computation_Algorithm"> + <title>Configure BPF-based Tx Port Selectors</title> + <para> + The loadbalance and LACP runners uses hashes of packets to sort network traffic flow. The hash computation mechanism is based on the <firstterm>Berkeley Packet Filter</firstterm> (<acronym>BPF</acronym>) code. The BPF code is used to generate a hash rather than make a policy decision for outgoing packets. The hash length is 8 bits giving 256 variants. This means many different <firstterm>socket buffers</firstterm> (<acronym>SKB</acronym>) can have the same hash and therefore pass traffic over the same link. The use of a short hash is a quick way to sort traffic into different streams for the purposes of load balancing across multiple links. In static mode, the hash is only used to decide out of which port the traffic should be sent. In active mode, the runner will continually reassign hashes to different ports in an attempt to reach a perfect balance.</para> + +<para> + The following fragment types or strings can be used for packet Tx hash computation: +<itemizedlist> +<listitem> + <para> + <option>eth</option> — Uses source and destination MAC addresses. + </para> +</listitem> + <listitem> + <para> + <option>vlan</option> — Uses VLAN ID. + </para> + </listitem> + <listitem> + <para> + <option>ipv4</option> — Uses source and destination <systemitem class="protocol">IPv4</systemitem> addresses. + </para> + </listitem> + <listitem> + <para> + <option>ipv6</option> — Uses source and destination <systemitem class="protocol">IPv6</systemitem> addresses. + </para> + </listitem> + <listitem> + <para> + <option>ip</option> — Uses source and destination <systemitem class="protocol">IPv4</systemitem> and <systemitem class="protocol">IPv6</systemitem> addresses. + </para> + </listitem> + <listitem> + <para> + <option>l3</option> — Uses source and destination <systemitem class="protocol">IPv4</systemitem> and <systemitem class="protocol">IPv6</systemitem> addresses. + </para> + </listitem> + <listitem> + <para> + <option>tcp</option> — Uses source and destination <systemitem class="protocol">TCP</systemitem> ports. + </para> + </listitem> + <listitem> + <para> + <option>udp</option> — Uses source and destination <systemitem class="protocol">UDP</systemitem> ports. + </para> + </listitem> + <listitem> + <para> + <option>sctp</option> — Uses source and destination <systemitem class="protocol">SCTP</systemitem> ports. + </para> + </listitem> + <listitem> + <para> + <option>l4</option> — Uses source and destination <systemitem class="protocol">TCP</systemitem> and <systemitem class="protocol">UDP</systemitem> and <systemitem class="protocol">SCTP</systemitem> ports. + </para> + </listitem> +</itemizedlist> + </para> + + <para> + These strings can be used by adding a line in the following format to the load balance runner: + <synopsis>"tx_hash": ["eth", "ipv4", "ipv6"]</synopsis> + See <xref linkend="sec-Configure_the_loadbalance_Runner" /> for an example. + </para> + +</section> + </section> + +<section id="sec-Configure_Network_Teaming_Using_nmcli"> + <title>Configure Network Teaming Using nmcli</title> + <para> + To view the devices available on the system, issue the following command: + <screen>~]$ <command>nmcli connection show</command> +NAME UUID TYPE DEVICE +eth1 0e8185a1-f0fd-4802-99fb-bedbb31c689b 802-3-ethernet -- +eth0 dfe1f57b-419d-4d1c-aaf5-245deab82487 802-3-ethernet --</screen> + </para> +<para> + To create a new team interface, with name <replaceable>team-ServerA</replaceable>, issue a command as follows: + <screen>~]$ <command>nmcli connection add type team ifname <replaceable>team-ServerA</replaceable></command> +Connection 'team-ServerA' (b954c62f-5fdd-4339-97b0-40efac734c50) successfully added.</screen> +<application>NetworkManager</application> will set its internal parameter <option>connection.autoconnect</option> to <literal>yes</literal> and as no <systemitem class="protocol">IP</systemitem> address was given <option>ipv4.method</option> will be set to <literal>auto</literal>. <application>NetworkManager</application> will also write a configuration file to <filename>/etc/sysconfig/network-scripts/ifcfg-team-ServerA</filename> where the corresponding ONBOOT will be set to <literal>yes</literal> and BOOTPROTO will be set to <literal>dhcp</literal>.</para> +<para> +Note that manual changes to the ifcfg file will not be noticed by <application>NetworkManager</application> until the interface is next brought up. See <xref linkend="sec-Network_Configuration_Using_sysconfig_Files" /> for more information on using configuration files. +</para> +<para> +To view the other values assigned, issue a command as follows: +<screen>~]$ <command>nmcli con show <replaceable>team-ServerA</replaceable></command> +connection.id: team-ServerA +connection.uuid: b954c62f-5fdd-4339-97b0-40efac734c50 +connection.interface-name: ServerA +connection.type: team +connection.autoconnect: yes +<lineannotation>…</lineannotation> +ipv4.method: auto +<lineannotation>[output truncated]</lineannotation></screen> +As no JSON configuration file was specified the default values apply. See the <filename>teamd.conf(5)</filename> man page for more information on the team JSON parameters and their default values. +Notice that the name was derived from the interface name by prepending the type. +Alternatively, specify a name with the <option>con-name</option> option as follows: + <screen>~]$ <command>nmcli connection add type team con-name <replaceable>Team0</replaceable> ifname <replaceable>ServerB</replaceable></command> +Connection 'Team0' (5f7160a1-09f6-4204-8ff0-6d96a91218a7) successfully added.</screen> +</para> +<para> + To view the team interfaces just configured, issue a command as follows: + <screen>~]$ <command>nmcli con show</command> +NAME UUID TYPE DEVICE +team-ServerA b954c62f-5fdd-4339-97b0-40efac734c50 team ServerA +eth1 0e8185a1-f0fd-4802-99fb-bedbb31c689b 802-3-ethernet -- +eth0 dfe1f57b-419d-4d1c-aaf5-245deab82487 802-3-ethernet -- +Team0 5f7160a1-09f6-4204-8ff0-6d96a91218a7 team ServerB</screen> +</para> +<para> + To change the name assigned to a team, issue a command in the following format: +<synopsis><command>nmcli con mod <replaceable>old-team-name</replaceable> connection.id <replaceable>new-team-name</replaceable></command></synopsis> +</para> +<para> + To load a team configuration file for a team that already exists, issue a command in the following format: + <synopsis><command>nmcli connection modify <replaceable>team-name</replaceable> team.config <replaceable>JSON-config</replaceable></command></synopsis> + You can specify the team configuration either as a JSON string or provide a file name containing the configuration. The file name can include the path. In both cases, what is stored in the <parameter>team.config</parameter> property is the JSON string. In the case of a JSON string, use single quotes around the string and paste the entire string to the command line. +</para> +<para> + To review the <literal>team.config</literal> property, enter a command in the following format: + <synopsis><command>nmcli con show <replaceable>team-name</replaceable> | grep team.config</command></synopsis> +</para> +<para> + To add an interface <replaceable>eth0</replaceable> to <literal>Team0</literal>, with the name <replaceable>Team0-port1</replaceable>, issue a command as follows: + <screen>~]$ <command>nmcli con add type team-slave con-name <replaceable>Team0-port1</replaceable> ifname <replaceable>eth0</replaceable> master <replaceable>Team0</replaceable></command> +Connection 'Team0-port1' (ccd87704-c866-459e-8fe7-01b06cf1cffc) successfully added.</screen> +Similarly, to add another interface, <replaceable>eth1</replaceable>, with the name <replaceable>Team0-port2</replaceable>, issue a command as follows: +<screen>~]$ <command>nmcli con add type team-slave con-name <replaceable>Team0-port2</replaceable> ifname <replaceable>eth1</replaceable> master <replaceable>Team0</replaceable></command> +Connection 'Team0-port2' (a89ccff8-8202-411e-8ca6-2953b7db52dd) successfully added.</screen> +At time of writing, <application>nmcli</application> only supports Ethernet ports. +</para> + <para> + In order to bring up a team, the ports must be brought up first as follows: + <screen>~]$ <command>nmcli connection up <replaceable>Team0-port1</replaceable></command> +Connection successfully activated (D-Bus active path: /org/freedesktop/NetworkManager/ActiveConnection/2)</screen> + +<screen>~]$ <command>nmcli connection up <replaceable>Team0-port2</replaceable></command> +Connection successfully activated (D-Bus active path: /org/freedesktop/NetworkManager/ActiveConnection/3)</screen> +</para> +<para> +You can verify that the team interface was brought up by the activation of the ports, as follows: +<screen>~]$ <command>ip link</command> +3: Team0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP mode DEFAULT + link/ether 52:54:00:76:6f:f0 brd ff:ff:ff:ff:ff:f</screen> +Alternatively, issue a command to bring up the team as follows: +<screen>~]$ <command>nmcli connection up <replaceable>Team0</replaceable></command> +Connection successfully activated (D-Bus active path: /org/freedesktop/NetworkManager/ActiveConnection/4)</screen> + </para> + + <para> + See <xref linkend="sec-Using_the_NetworkManager_Command_Line_Tool_nmcli" /> for an introduction to <application>nmcli</application> + </para> +</section> + + + + <!--Topics, Reference--> + <section id="sec-Network_Teaming-additional_resources"> + +<title>Additional Resources</title> +<para> + The following sources of information provide additional resources regarding network teaming. + </para> + <section id="sec-teamd-docs-inst"> + <title>Installed Documentation</title> + <itemizedlist> + <listitem> + <para> + <filename>teamd(8)</filename> man page — Describes the <systemitem class="daemon">teamd</systemitem> service. + </para> + </listitem> + <listitem> + <para> + <filename>teamdctl(8)</filename> man page — Describes the <systemitem class="daemon">teamd</systemitem> control tool. + </para> + </listitem> + <listitem> + <para> + <filename>teamd.conf(5)</filename> man page — Describes the <systemitem class="daemon">teamd</systemitem> configuration file. + </para> + </listitem> + <listitem> + <para> + <filename>teamnl(8)</filename> man page — Describes the <systemitem class="daemon">teamd</systemitem> Netlink library. + </para> + </listitem> + <listitem> + <para> + <filename>bond2team(1)</filename> man page — Describes a tool to convert bonding options to team. + </para> + </listitem> +</itemizedlist> +</section> + +<!--<section id="sec-Configure_teamd-docs-installable"> + <title>Installable Documentation</title> + <itemizedlist> + <listitem> + <para> + <filename + class="directory">/usr/share/doc/kernel-doc-<replaceable>kernel_version</replaceable>/Documentation/</filename> — This directory, which is provided by the <package>kernel-doc</package> package, contains information on bonding which is also relevant to teaming. Before accessing the kernel documentation, you must run the following command as <systemitem class="username">root</systemitem>:</para> + <screen>~]# <command>dnf install kernel-doc</command></screen> + <para> + <filename>/usr/share/doc/kernel-doc/Documentation/networking/multiqueue.txt</filename> — Describes kernel support for multiqueue devices. + </para> + </listitem> + </itemizedlist> + </section>--> + +<section id="sec-teamd_docs-online"> + <title>Online Documentation</title> + <para> +<variablelist> + <varlistentry> +<term><ulink url="http://www.libteam.org"/></term> +<listitem> +<para> + The upstream project. +</para> +</listitem> +</varlistentry> + + <varlistentry> +<term><ulink url="http://www.w3schools.com/json/json_syntax.asp"/></term> +<listitem> +<para> + An explanation of JSON syntax. +</para> +</listitem> +</varlistentry> + +</variablelist> + + </para> + </section> +</section> + </chapter> diff --git a/docs/guide/Configure_Networking.xml b/docs/guide/Configure_Networking.xml new file mode 100644 index 000000000..b070e1876 --- /dev/null +++ b/docs/guide/Configure_Networking.xml @@ -0,0 +1,2374 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "Networking_Guide.ent"> +%BOOK_ENTITIES; +]> +<chapter id="ch-Configure_Networking"> + <title>Configure Networking</title> + <!-- Topics, Concepts --> + + <section id="sec-Static_and_Dynamic_Interface_Settings"> + <title>Static and Dynamic Interface Settings</title> + <para> + When to use static addressing and when to use dynamic addressing? These decisions are subjective, they depend on your accessed needs, your specific requirements. Having a policy, documenting it, and applying it consistently are usually more important than the specific decisions you make. In a traditional company LAN, this is an easier decision to make as you typically have fewer servers than other hosts. Provisioning and installation tools make providing static configurations to new hosts easy and using such tools will change your work flow and requirements. The following two sections are intended to provide guidance to those who have not already been through this decision-making process. For more information on automated configuration and management, see the <application>OpenLMI</application> section in the <citetitle pubwork="book">System Administrators Guide</citetitle>. The <citetitle pubwork="book">System Installation Guide</citetitle> documents the use of <application>kickstart</application> which can also be used for automating the assignment of network settings. + </para> +<section id="sec-When_to_Use_Static_Network_Interface_Settings"> + <title>When to Use Static Network Interface Settings</title> + <para> + </para> + <para> + Use static <systemitem class="protocol">IP</systemitem> addressing on those servers and devices whose network availability you want to ensure when automatic assignment methods, such as <systemitem class="protocol">DHCP</systemitem>, fail. <systemitem class="protocol">DHCP</systemitem>, <systemitem class="protocol">DNS</systemitem>, and authentication servers are typical examples. Interfaces for out-of-band management devices are also worth configuring with static settings as these devices are supposed to work, as far as is possible, independently of other network infrastructure.</para> + <para>For hosts which are not considered vital, but for which static <systemitem class="protocol">IP</systemitem> addressing is still considered desirable, use an automated provisioning method when possible. For example, <systemitem class="protocol">DHCP</systemitem> servers can be configured to provide the same <systemitem class="protocol">IP</systemitem> address to the same host every time. This method could be used for communal printers for example. + </para> + <para> + All the configuration tools listed in <xref linkend="sec-Selecting_Network_Configuration_Methods" /> allow assigning static <systemitem class="protocol">IP</systemitem> addresses manually. The <application>nmcli</application> tool is also suitable for use with scripted assignment of network configuration. + </para> + +</section> +<section id="sec-When_to_Use_Dynamic_Interface_Settings"> +<title>When to Use Dynamic Interface Settings</title> + <para> + </para> + <para> + Enable and use dynamic assignment of <systemitem class="protocol">IP</systemitem> addresses and other network information whenever there is no compelling reason not to. The time saved in planning and documenting manual settings can be better spent elsewhere. The <firstterm>dynamic host control protocol</firstterm> (<acronym>DHCP</acronym>) is a traditional method of dynamically assigning network configurations to hosts. See <xref linkend="sec-dhcp-why" /> for more information on this subject. + </para> + <para> + <application>NetworkManager</application> will by default call the <systemitem class="protocol">DHCP</systemitem> client, <application>dhclient</application>, when a profile has been set to obtain addresses automatically, or when an interface configuration file has BOOTPROTO set to <literal>dhcp</literal>. Where <systemitem class="protocol">DHCP</systemitem> is required, an instance of <systemitem class="service">dhclient</systemitem> is started for every Internet protocol, <systemitem class="protocol">IPv4</systemitem> and <systemitem class="protocol">IPv6</systemitem>, on an interface. Where <application>NetworkManager</application> is not running, or not managing an interface, then the legacy network service will call instances of <systemitem class="service">dhclient</systemitem> as required. + </para> +</section> +<section id="sec-Selecting_Network_Configuration_Methods"> +<title>Selecting Network Configuration Methods</title> + <itemizedlist> + <listitem> + <para> + To configure a network using graphical user interface tools, proceed to <xref linkend="sec-Using_NetworkManager_with_the_GNOME_Graphical_User_Interface" /> + </para> + </listitem> + <listitem> + <para> + To configure a network interface manually, see <xref linkend="sec-Using_the_Command_Line_Interface" />. + </para> + </listitem> + <listitem> + <para> + To configure an interface using <application>NetworkManager</application>'s command-line tool, <application>nmcli</application>, proceed to <xref linkend="sec-Using_the_NetworkManager_Command_Line_Tool_nmcli" /> + </para> + </listitem> + </itemizedlist> + </section> +</section> +<section id="sec-Using_NetworkManager_with_the_GNOME_Graphical_User_Interface"> + <title>Using NetworkManager with the GNOME Graphical User Interface</title> +<para> + As of <application>Fedora 20</application>, <application>NetworkManager</application>'s own graphical user interface (GUI) is not used by default. The <guilabel>Network</guilabel> settings configuration tool is provided as part of the new GNOME <application>control-center</application> GUI. The old <application>nm-connection-editor</application> GUI is still available for certain tasks. + </para> + <section + id="sec-Connecting_to_a_Network_Using_a_GUI"> + <title>Connecting to a Network Using a GUI</title> + <para> + Access the <guilabel>Network</guilabel> settings window of the <application>control-center</application> application as follows:</para> + <itemizedlist> + <listitem> + <para>Press the <keycap>Super</keycap> key to enter the Activities Overview, type <command>control network</command> and then press <keycap>Enter</keycap>. The <guilabel>Network</guilabel> settings tool appears. Proceed to <xref linkend="sec-Configuring_New_and_Editing_Existing_Connections" /></para> + </listitem> + </itemizedlist> + + </section> +<!-- Topics, Tasks --> + <section + id="sec-Configuring_New_and_Editing_Existing_Connections"> + <title>Configuring New and Editing Existing Connections</title> + <para> + The <guilabel>Network</guilabel> settings window shows the connection status, its type and interface, its <systemitem class="protocol">IP</systemitem> address and routing details, and so on.</para> + <figure id="exam-Configuring_New_and_Editing_Existing_Connections_Network-Settings-Window"> + <title>Configure Networks Using the Network Settings Window</title> + <mediaobject + id="mediaobj-Network-Wired_Gnome3.png"> + <imageobject> + <imagedata + scalefit="0" + fileref="Network-Wired_Gnome3.png" + format="PNG" /> + </imageobject> + <textobject><para>A screen shot of the GNOME control-center Network Settings window. The menu is on the left, the connection status button on the right.</para></textobject> + </mediaobject> + </figure> + <para> + The <guilabel>Network</guilabel> settings window has a menu on the left-hand side showing the available network devices or interfaces. This includes software interfaces such as for VLANs, bridges, bonds, and teams. On the right-hand side, the <firstterm>connection profiles</firstterm> are shown for the selected network device or interface. A profile is a named collection of settings that can be applied to an interface. Below that is a plus and a minus button for adding and deleting new network connections, and on the right a gear wheel icon will appear for editing the connection details of the selected network device or VPN connection. To add a new connection, click the plus symbol to open the <guilabel>Add Network Connection</guilabel> window and proceed to <xref linkend="sec-Configuring_a_New_Connection" />.</para> + <bridgehead id="bh-Editing_an_Existing_Connection">Editing an Existing Connection</bridgehead> + <para>Clicking on the gear wheel icon of an existing connection profile in the <guilabel>Network</guilabel> settings window opens the <guilabel>Network</guilabel> details window, from where you can perform most network configuration tasks such as <systemitem class="protocol">IP</systemitem> addressing, <systemitem class="protocol">DNS</systemitem>, and routing configuration.</para> + <figure id="exam-Configuring_New_and_Editing_Existing_Connections_Network-Details-Window"> + <title>Configure Networks Using the Network Connection Details Window</title> + <mediaobject + id="mediaobj-Network-Details-Wired_Gnome3.png"> + <imageobject> + <imagedata + scalefit="0" + fileref="Network-Details-Wired_Gnome3.png" + format="PNG" /> + </imageobject> + <textobject><para>A screen shot of GNOME's Network Interface Detail window. The menu is on the left.</para></textobject> + </mediaobject> + </figure> + <section id="sec-Configuring_a_New_Connection"><title>Configuring a New Connection</title> + <para> + In the <guilabel>Network</guilabel> settings window, click the plus sign below the menu to open the <guilabel>Add Network Connection</guilabel> window. This displays a list of connection types that can be added. + </para> + + <para>Then, to configure:</para> + <itemizedlist> + <listitem> + <para>VPN connections, click the <guilabel>VPN</guilabel> entry and proceed to <xref + linkend="sec-Establishing_a_VPN_Connection"/>; + </para> + </listitem> + <listitem> + <para>Bond connections, click the <guilabel>Bond</guilabel> entry and proceed to <xref + linkend="sec-Establishing_a_Bond_Connection"/>; + </para> + </listitem> + <listitem> + <para>Bridge connections, click the <guilabel>Bridge</guilabel> entry and proceed to <xref + linkend="sec-Establishing_a_Bridge_Connection"/>; + </para> + </listitem> + <listitem> + <para>VLAN connections, click the <guilabel>VLAN</guilabel> entry and proceed to <xref + linkend="sec-Establishing_a_VLAN_Connection"/>;or, + </para> + </listitem> + <listitem> + <para>Team connections, click the <guilabel>Team</guilabel> entry and proceed to <xref linkend="sec-Creating_a_Network_Team_Using_a_GUI" />. + </para> + </listitem> + </itemizedlist> + </section> + </section> + + <section + id="sec-Connecting_to_a_Network_Automatically"> + <title>Connecting to a Network Automatically</title> + <para>For any connection type you add or configure, you can choose whether you want <application>NetworkManager</application> to try to connect to that network automatically when it is available.</para> + <procedure + id="procedure-Configuring_NetworkManager_to_Connect_to_a_Network_Automatically_When_Detected"> + <title>Configuring NetworkManager to Connect to a Network Automatically When Detected</title> + <step> + <para>Press the <keycap>Super</keycap> key to enter the Activities Overview, type <command>control network</command> and then press <keycap>Enter</keycap>. The <guilabel>Network</guilabel> settings tool appears.</para> + </step> + <step> + <para>Select the network interface from the left-hand-side menu.</para> + </step> + <step> + <para>Click on the gear wheel icon of a connection profile on the right-hand side menu. If you have only one profile associated with the selected interface the gear wheel icon will be in the lower right-hand-side corner. The <guilabel>Network</guilabel> details window appears.</para> + </step> + <step> + <para>Select the <guilabel>Identity</guilabel> menu entry on the left. The <guilabel>Network</guilabel> window changes to the identity view.</para> + </step> + <step> + <para>Select <guilabel>Connect automatically</guilabel> to cause <application>NetworkManager</application> to auto-connect to the connection whenever <application>NetworkManager</application> detects that it is available. Clear the check box if you do not want <application>NetworkManager</application> to connect automatically. If the check box is clear, you will have to select that connection manually in the network settings tool to cause it to connect.</para> + </step> + </procedure> + </section> + + <section + id="sec-System-wide_and_Private_Connection_Profiles"> + <title>System-wide and Private Connection Profiles</title> + <para> + <application>NetworkManager</application> stores all <firstterm>connection profiles</firstterm>. A profile is a named collection of settings that can be applied to an interface. <application>NetworkManager</application> stores these connection profiles for system-wide use (<firstterm>system connections</firstterm>), as well as all <firstterm>user connection</firstterm> profiles. Access to the connection profiles is controlled by permissions which are stored by <application>NetworkManager</application>. See the <filename>nm-settings(5)</filename> man page for more information on the <option>connection</option> settings <option>permissions</option> property. The permissions correspond to the <command>USERS</command> directive in the <filename>ifcfg</filename> files. If the <command>USERS</command> directive is not present, the network profile will be available to all users. As an example, the following command in an <filename>ifcfg</filename> file will make the connection available only to the users listed: + <synopsis>USERS="joe bob alice"</synopsis> + This can also be set using graphical user interface tools. In <application>nm-connection-editor</application>, there is the corresponding <guilabel>All users may connect to this network</guilabel> check box on the <guilabel>General</guilabel> tab, and in the GNOME <application>control-center</application> Network settings Identity window, there is the <guilabel>Make available to other users</guilabel> check box. + </para> + <para> + <application>NetworkManager</application>'s default policy is to allow all users to create and modify system-wide connections. Profiles that should be available at boot time cannot be private because they will not be visible until the user logs in. For example, if user <systemitem class="username">user</systemitem> creates a connection profile <literal>user-em2</literal> with the <guilabel>Connect Automatically</guilabel> check box selected but with the <guilabel>Make available to other users</guilabel> not selected, then the connection will not be available at boot time.</para> + <para> +To restrict connections and networking, there are two options which can be used alone or in combination: + <itemizedlist> + <listitem> + <para> + Clear the <guilabel>Make available to other users</guilabel> check box, which changes the connection to be modifiable and usable only by the user doing the changing. + </para> + </listitem> + <listitem> + <para> + Use the <application>polkit</application> framework to restrict permissions of general network operations on a per-user basis. + </para> + </listitem> + </itemizedlist> + The combination of these two options provides fine-grained security and control over networking. See the <filename>polkit(8)</filename> man page for more information on <application>polkit</application>. + </para> + + <para> + Note that VPN connections are <emphasis role="bold">always</emphasis> created as private-per-user, since they are assumed to be more private than a Wi-Fi or Ethernet connection. + </para> + + <procedure> + <title>Changing a Connection to Be User-specific Instead of System-Wide, or Vice Versa</title> + <para>Depending on the system's policy, you may need root privileges on the system in order to change whether a connection is user-specific or system-wide.</para> + <step> + <para>Press the <keycap>Super</keycap> key to enter the Activities Overview, type <command>control network</command> and then press <keycap>Enter</keycap>. The <guilabel>Network</guilabel> settings tool appears.</para> + </step> + <step> + <para>Select the network interface from the left-hand-side menu.</para> + </step> + <step> + <para>Click on the gear wheel icon of a connection profile on the right-hand side menu. If you have only one profile associated with the selected interface the gear wheel icon will be in the lower right-hand-side corner. The <guilabel>Network</guilabel> details window appears.</para> + </step> + <step> + <para>Select the <guilabel>Identity</guilabel> menu entry on the left. The <guilabel>Network</guilabel> window changes to the identity view.</para> + </step> + <step> + <para>Select the <guilabel>Make available to other users</guilabel> check box to cause <application>NetworkManager</application> to make the connection available system-wide. Depending on system policy, you may then be prompted for an administrator or <systemitem class="username">root</systemitem> password by the <application>polkit</application> application. If so, enter the appropriate password to finalize the changes.</para> + <para>Conversely, clear the <guilabel>Make available to other users</guilabel> check box to make the connection user-specific.</para> + </step> + </procedure> + </section> + + + <section + id="sec-Configuring_a_Wired_Ethernet_Connection"> + <title>Configuring a Wired (Ethernet) Connection</title> + <para>To configure a wired network connection, press the <keycap>Super</keycap> key to enter the Activities Overview, type <command>control network</command> and then press <keycap>Enter</keycap>. The <guilabel>Network</guilabel> settings tool appears.</para> + <para> + Select the <guilabel>Wired</guilabel> network interface from the left-hand-side menu if it is not already highlighted.</para> + + <para>The system creates and configures a single wired <firstterm>connection profile</firstterm> called <guilabel>Wired</guilabel> by default. A profile is a named collection of settings that can be applied to an interface. More than one profile can be created for an interface and applied as needed. The default profile cannot be deleted but its settings can be changed. You can edit the default <guilabel>Wired</guilabel> profile by clicking the gear wheel icon. You can create a new wired connection profile by clicking the <guilabel>Add Profile</guilabel> button. Connection profiles associated with a selected interface are shown on the right-hand side menu. +</para> + <para>When you add a new connection by clicking the <guibutton>Add Profile</guibutton> button, <application>NetworkManager</application> creates a new configuration file for that connection and then opens the same dialog that is used for editing an existing connection. The difference between these dialogs is that an existing connection profile has a <guilabel>Details</guilabel> and <guilabel>Reset</guilabel> menu entry. In effect, you are always editing a connection profile; the difference only lies in whether that connection previously existed or was just created by <application>NetworkManager</application> when you clicked <guibutton>Add Profile</guibutton>.</para> + + <section id="sec-Configuring_the_Connection_Name_Auto-Connect_Behavior_and_Availability_Settings-wired"> + <title>Configuring the Connection Name, Auto-Connect Behavior, and Availability Settings</title> + <para>Many settings in the <guilabel>Editing</guilabel> dialog are common to all connection types, see the <guilabel>Identity</guilabel> view if using the GNOME tool or the <guilabel>General</guilabel> tab if using <application>nm-connection-editor</application>: + </para> + <itemizedlist> + <listitem> + <para> + <guilabel>Name</guilabel> — Enter a descriptive name for your network connection. This name will be used to list this connection in the menu of the <guilabel>Network</guilabel> window. + </para> + </listitem> + <listitem> + <para> + <guilabel>MAC Address</guilabel> — Select the MAC address of the interface this profile must be applied to. + </para> + </listitem> + <listitem> + <para> + <guilabel>Cloned Address</guilabel> — If required, enter a different MAC address to use. + </para> + </listitem> + <listitem> + <para> + <guilabel>MTU</guilabel> — If required, enter a specific <firstterm>maximum transmission unit</firstterm> (<acronym>MTU</acronym>) to use. The MTU value represents the size in bytes of the largest packet that the link-layer will transmit. This value defaults to <constant>1500</constant> and does not generally need to be specified or changed. + </para> + </listitem> + <listitem> + <para> + <guilabel>Firewall Zone</guilabel> — If required, select a different firewall zone to apply. See the <citetitle pubwork="book"><ulink url="https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Security_Guide/">Red Hat Enterprise Linux 7 Security Guide</ulink></citetitle> for more information on firewall zones. + </para> + </listitem> + <listitem> + <para> + <guilabel>Connect Automatically</guilabel> — Select this box if you want <application>NetworkManager</application> to auto-connect to this connection when it is available. See <xref linkend="sec-Connecting_to_a_Network_Automatically"/> for more information. + </para> + </listitem> + <listitem> + <para> + <guilabel>Make available to other users</guilabel> — Select this box to create a connection available to all users on the system. Changing this setting may require root privileges. See <xref linkend="sec-System-wide_and_Private_Connection_Profiles"/> for details. + </para> + </listitem> + <listitem> + <para> + <guilabel>Automatically connect to VPN when using this connection</guilabel> — Select this box if you want <application>NetworkManager</application> to auto-connect to the selected VPN connection when this connection profile is connected. Select the VPN from the drop-down menu. + </para> + </listitem> + </itemizedlist> + + + <bridgehead + id="bh-Saving_Your_New_or_Modified_Connection_and_Making_Further_Configurations-Wired">Saving Your New (or Modified) Connection and Making Further Configurations</bridgehead> + <para>Once you have finished editing your wired connection, click the <guibutton>Apply</guibutton> button to save your customized configuration. If the profile was in use while being edited, power cycle the connection to make <application>NetworkManager</application> apply the changes. If the profile is OFF, set it to ON. See <xref + linkend="sec-Connecting_to_a_Network_Using_a_GUI"/> for information on using your new or altered connection.</para> + <para>You can further configure an existing connection by selecting it in the <guilabel>Network</guilabel> window and clicking the gear wheel icon to return to the editing dialog.</para> + <para>Then, to configure:</para> + <itemizedlist> + <listitem> + <para>port-based Network Access Control (PNAC), click the <guilabel>802.1X Security</guilabel> tab and proceed to <xref + linkend="sec-Configuring_802.1X_Security"/>; + </para> + </listitem> + <listitem> + <para><systemitem class="protocol">IPv4</systemitem> settings for the connection, click the <guilabel>IPv4 Settings</guilabel> tab and proceed to <xref + linkend="sec-Configuring_IPv4_Settings"/>; or, + </para> + </listitem> + <listitem> + <para><systemitem class="protocol">IPv6</systemitem> settings for the connection, click the <guilabel>IPv6 Settings</guilabel> tab and proceed to <xref + linkend="sec-Configuring_IPv6_Settings"/>. + </para> + </listitem> + </itemizedlist> + </section> + </section> + + <section + id="sec-Configuring_a_Wi-Fi_Connection"> + <title>Configuring a Wi-Fi Connection</title> + <para> + This section explains how to use <application>NetworkManager</application> to configure a Wi-Fi (also known as wireless or 802.11<replaceable>a/b/g/n</replaceable>) connection to an Access Point.</para> + <para>To configure a mobile broadband (such as 3G) connection, see <xref + linkend="sec-Establishing_a_Mobile_Broadband_Connection"/>.</para> + <bridgehead + id="bh-Quickly_Connecting_to_an_Available_Access_Point">Quickly Connecting to an Available Access Point</bridgehead> + <para>The easiest way to connect to an available access point is to click on the network connection icon to activate the network connection, locate the <firstterm>Service Set Identifier</firstterm> (<acronym>SSID</acronym>) of the access point in the list of <guilabel>Wi-Fi</guilabel> networks, and click on it. A padlock symbol indicates the access point requires authentication. If the access point is secured, a dialog prompts you for an authentication key or password.</para> + <para> + <application>NetworkManager</application> tries to auto-detect the type of security used by the access point. If there are multiple possibilities, <application>NetworkManager</application> guesses the security type and presents it in the <guilabel>Wi-Fi security</guilabel> drop-down menu. For WPA-PSK security (WPA with a passphrase) no choice is necessary. For WPA Enterprise (802.1X) you have to specifically select the security, because that cannot be auto-detected. If you are unsure, try connecting to each type in turn. Finally, enter the key or passphrase in the <guilabel>Password</guilabel> field. Certain password types, such as a 40-bit WEP or 128-bit WPA key, are invalid unless they are of a requisite length. The <guilabel>Connect</guilabel> button will remain inactive until you enter a key of the length required for the selected security type. To learn more about wireless security, see <xref + linkend="sec-Configuring_Wi-Fi_Security"/>.</para> + + + <para>If <application>NetworkManager</application> connects to the access point successfully, the network connection icon will change into a graphical indicator of the wireless connection's signal strength.</para> + <para>You can also edit the settings for one of these auto-created access point connections just as if you had added it yourself. The <guilabel>Wi-Fi</guilabel> page of the <guilabel>Network</guilabel> window has a <guilabel>History</guilabel> button. Clicking it reveals a list of all the connections you have ever tried to connect to. See <xref linkend="sec-Editing_a_Connection_or_Creating_a_Completely_New_One" /></para> + + <section id="sec-Connecting_to_a_Hidden_Wi-Fi_Network"> + <title>Connecting to a Hidden Wi-Fi Network</title> + <para>All access points have a <firstterm>Service Set Identifier</firstterm> (<acronym>SSID</acronym>) to identify them. However, an access point may be configured not to broadcast its SSID, in which case it is <emphasis>hidden</emphasis>, and will not show up in <application>NetworkManager</application>'s list of <guilabel>Available</guilabel> networks. You can still connect to a wireless access point that is hiding its SSID as long as you know its SSID, authentication method, and secrets.</para> + <para>To connect to a hidden wireless network, press the <keycap>Super</keycap> key to enter the Activities Overview, type <command>control network</command> and then press <keycap>Enter</keycap>. The <guilabel>Network</guilabel> window appears. Select <guilabel>Wi-Fi</guilabel> from the menu and then select <guilabel>Connect to Hidden Network</guilabel> to cause a dialog to appear. If you have connected to the hidden network before, use the <guilabel>Connection</guilabel> drop-down to select it, and click <guibutton>Connect</guibutton>. If you have not, leave the <guilabel>Connection</guilabel> drop-down as <guimenuitem>New</guimenuitem>, enter the SSID of the hidden network, select its <guilabel>Wi-Fi security</guilabel> method, enter the correct authentication secrets, and click <guibutton>Connect</guibutton>.</para> + <para>For more information on wireless security settings, see <xref + linkend="sec-Configuring_Wi-Fi_Security"/>.</para> + </section> + + <section id="sec-Editing_a_Connection_or_Creating_a_Completely_New_One"> + <title>Editing a Connection, or Creating a Completely New One</title> + <para>You can edit an existing connection that you have tried or succeeded in connecting to in the past by opening the <guilabel>Wi-Fi</guilabel> page of the <guilabel>Network</guilabel> dialog and selecting the gear wheel icon to the right of the Wi-Fi connection name. If the network is not currently in range, click <guilabel>History</guilabel> to display past connections. When you click the gear wheel icon the editing connection dialog appears. The <guilabel>Details</guilabel> window shows the connection details.</para> + + + <para>To configure a new connection whose SSID is in range, first attempt to connect to it by opening the <guilabel>Network</guilabel> window, selecting the <guilabel>Wi-Fi</guilabel> menu entry, and clicking the connection name (by default, the same as the SSID). If the SSID is not in range, see <xref linkend="sec-Connecting_to_a_Hidden_Wi-Fi_Network" />. If the SSID is in range, the procedure is as follows:</para> + + <procedure> + <step> + <para>Press the <keycap>Super</keycap> key to enter the Activities Overview, type <command>control network</command> and then press <keycap>Enter</keycap>. The <guilabel>Network</guilabel> settings tool appears.</para> + </step> + <step> + <para>Select the <guilabel>Wi-Fi</guilabel> interface from the left-hand-side menu entry.</para> + </step> + <step> + <para>Click the Wi-Fi connection profile on the right-hand side menu you want to connect to. A padlock symbol indicates a key or password is required.</para> + </step> + <step> + <para> + If requested, enter the authentication details. + </para> + </step> + </procedure> + + <bridgehead + id="bh-Configuring_the_SSID-Connect_Behavior_and_Availability_Settings-wireless">Configuring the SSID, Auto-Connect Behavior, and Availability Settings</bridgehead> + <para> + To edit a Wi-Fi connection's settings, select <guilabel>Wi-Fi</guilabel> in the <guilabel>Network</guilabel> page and then select the gear wheel icon to the right of the Wi-Fi connection name. Select <guilabel>Identity</guilabel>. The following settings are available: + </para> + + <variablelist> + <varlistentry> + <term> + <guilabel>SSID</guilabel> + </term> + <listitem> + <para> + The <firstterm>Service Set Identifier</firstterm> (<acronym>SSID</acronym>) of the access point (AP). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>BSSID</guilabel> + </term> + <listitem> + <para>The <firstterm>Basic Service Set Identifier</firstterm> (<acronym>BSSID</acronym>) is the MAC address, also known as a <firstterm>hardware address</firstterm>, of the specific wireless access point you are connecting to when in <guilabel>Infrastructure</guilabel> mode. This field is blank by default, and you are able to connect to a wireless access point by <guilabel>SSID</guilabel> without having to specify its <guilabel>BSSID</guilabel>. If the BSSID is specified, it will force the system to associate to a specific access point only.</para> + <para>For ad-hoc networks, the <guilabel>BSSID</guilabel> is generated randomly by the <application>mac80211</application> subsystem when the ad-hoc network is created. It is not displayed by <application>NetworkManager</application></para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>MAC address</guilabel> + </term> + <listitem> + <para> + Select the MAC address, also known as a <firstterm>hardware address</firstterm>, of the Wi-Fi interface to use.</para> + + <para>A single system could have one or more wireless network adapters connected to it. The <guilabel>MAC address</guilabel> field therefore allows you to associate a specific wireless adapter with a specific connection (or connections).</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Cloned Address</guilabel> + </term> + <listitem> + <para> + A cloned MAC address to use in place of the real hardware address. Leave blank unless required. + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + The following settings are common to all connection profiles: + </para> + <itemizedlist> + <listitem> + <para> + <guilabel>Connect automatically</guilabel> — Select this box if you want <application>NetworkManager</application> to auto-connect to this connection when it is available. See <xref + linkend="sec-Connecting_to_a_Network_Automatically"/> for more information.</para> + </listitem> + <listitem> + <para> + <guilabel>Make available to other users</guilabel> — Select this box to create a connection available to all users on the system. Changing this setting may require root privileges. See <xref + linkend="sec-System-wide_and_Private_Connection_Profiles"/> for details. + </para> + </listitem> + </itemizedlist> + + <bridgehead + id="bh-Saving_Your_New_or_Modified_Connection_and_Making_Further_Configurations-wireless">Saving Your New (or Modified) Connection and Making Further Configurations</bridgehead> + <para>Once you have finished editing the wireless connection, click the <guibutton>Apply</guibutton> button to save your configuration. Given a correct configuration, you can connect to your modified connection by selecting it from the GNOME Shell notification area menu in the top right-hand corner of the screen. Click in the top right-hand side corner to open the menu. Select <guimenuitem>Wi-Fi</guimenuitem>. See <xref + linkend="sec-Connecting_to_a_Network_Using_a_GUI"/> for details on selecting and connecting to a network.</para> + <para>You can further configure an existing connection by selecting it in the <guilabel>Network</guilabel> window and clicking the gear wheel icon to reveal the connection details.</para> + <para>Then, to configure:</para> + <itemizedlist> + <listitem> + <para>security authentication for the wireless connection, click <guilabel>Security</guilabel> and proceed to <xref + linkend="sec-Configuring_Wi-Fi_Security"/>;</para> + </listitem> + <listitem> + <para><systemitem class="protocol">IPv4</systemitem> settings for the connection, click <guilabel>IPv4</guilabel> and proceed to <xref + linkend="sec-Configuring_IPv4_Settings"/>; or, + </para> + </listitem> + <listitem> + <para><systemitem class="protocol">IPv6</systemitem> settings for the connection, click <guilabel>IPv6</guilabel> and proceed to <xref + linkend="sec-Configuring_IPv6_Settings"/>. + </para> + </listitem> + </itemizedlist> + </section> + </section> + +<section + id="sec-Establishing_a_VPN_Connection"> + <title>Establishing a VPN Connection</title> + <!--<para> + IPsec, provided by <application>Libreswan</application> (a fork of Openswan), is the preferred method for creating a VPN in Fedora. The GNOME graphical user interface tool described below requires the <package>NetworkManager-libreswan-gnome</package> package. If required, to ensure this package is installed issue the following command as <systemitem class="username">root</systemitem>: + <screen>~]# <command>dnf install NetworkManager-libreswan-gnome</command></screen> + </para> +<para> +See <citetitle pubwork="book">&MAJOROSVER; System Administrator's Guide</citetitle> for more information on how to install new packages in &MAJOROSVER;. +</para>--> + <para>Establishing a Virtual Private Network (VPN) enables communication between your Local Area Network (LAN), and another, remote LAN. This is done by setting up a tunnel across an intermediate network such as the Internet. The VPN tunnel that is set up typically uses authentication and encryption. After successfully establishing a VPN connection using a secure tunnel, a VPN router or gateway performs the following actions upon the packets you transmit:</para> + <orderedlist> + <listitem> + <para>it adds an <firstterm>Authentication Header</firstterm> for routing and authentication purposes;</para> + </listitem> + <listitem> + <para>it encrypts the packet data; and,</para> + </listitem> + <listitem> + <para>it encloses the data in packets according to the Encapsulating Security Payload (ESP) protocol, which constitutes the decryption and handling instructions.</para> + </listitem> + </orderedlist> + <para>The receiving VPN router strips the header information, decrypts the data, and routes it to its intended destination (either a workstation or other node on a network). Using a network-to-network connection, the receiving node on the local network receives the packets already decrypted and ready for processing. The encryption and decryption process in a network-to-network VPN connection is therefore transparent to clients.</para> + <para>Because they employ several layers of authentication and encryption, VPNs are a secure and effective means of connecting multiple remote nodes to act as a unified intranet.</para> + + <procedure + id="procedure-Adding_a_New_VPN_Connection"> + <title>Adding a New VPN Connection</title> + <para> + You can configure a new VPN connection by opening the <guilabel>Network</guilabel> window and selecting the plus symbol below the menu. + </para> + <step> + <para>Press the <keycap>Super</keycap> key to enter the Activities Overview, type <command>control network</command> and then press <keycap>Enter</keycap>. The <guilabel>Network</guilabel> settings tool appears.</para> + </step> + <step> + <para> + Select the plus symbol below the menu. The <guilabel>Add Network Connection</guilabel> window appears. + </para> + </step> + <step> + <para>Select the <guilabel>VPN</guilabel> menu entry. The view now changes to offer configuring a VPN manually, or importing a VPN configuration file.</para> + + <para>The appropriate <application>NetworkManager</application> VPN plug-in for the VPN type you want to configure must be installed. (see <citetitle pubwork="book">&MAJOROSVER; System Administrator's Guide</citetitle> for more information on how to install new packages in &MAJOROSVER;).</para> + </step> + <step> + <para>Click the <guibutton>Add</guibutton> button to open the <guilabel>Choose a VPN Connection Type</guilabel> assistant.</para> + </step> + <step> + <para>Select the VPN protocol for the gateway you are connecting to from the menu. The VPN protocols available for selection in the menu correspond to the <application>NetworkManager</application> VPN plug-ins installed. For example, if the <package>NetworkManager-openswan-gnome</package> package is installed then the IPsec based VPN will be selectable from the menu.</para> + + <!-- There are three VPN protocols to select from:</para> + <para>Cisco Compatible VPN (vpnc) — </para> + <para>OpenVPN — </para> + <para>Point-to-Point Tunneling Protocol (pptp) — </para> --> + </step> + <step> + <para>The <guilabel>Add Network Connection</guilabel> window changes to present the settings customized for the type of VPN connection you selected in the previous step.</para> + </step> + + </procedure> + <procedure + id="procedure-Editing_an_Existing_VPN_Connection"> + <title>Editing an Existing VPN Connection</title> + <para>You can configure an existing VPN connection by opening the <guilabel>Network</guilabel> window and selecting the name of the connection from the list. Then click the <guibutton>Edit</guibutton> button. + </para> + <step> + <para>Press the <keycap>Super</keycap> key to enter the Activities Overview, type <command>control network</command> and then press <keycap>Enter</keycap>. The <guilabel>Network</guilabel> settings tool appears.</para> + </step> + <step> + <para>Select the <guilabel>VPN</guilabel> connection you want to edit from the left hand menu.</para> + </step> + <step> + <para>Click the <guilabel>Configure</guilabel> button.</para> + </step> + </procedure> + <bridgehead + id="bh-Configuring_the_Connection_Name_Auto-Connect_Behavior_and_Availability_Settings-vpn">Configuring the Connection Name, Auto-Connect Behavior, and Availability Settings</bridgehead> + <para>Five settings in the <guilabel>Editing</guilabel> dialog are common to all connection types, see the <guilabel>General</guilabel> tab: + </para> + <itemizedlist> + <listitem> + <para> + <guilabel>Connection name</guilabel> — Enter a descriptive name for your network connection. This name will be used to list this connection in the menu of the <guilabel>Network</guilabel> window. + </para> + </listitem> + <listitem> + <para> + <guilabel>Automatically connect to this network when it is available</guilabel> — Select this box if you want <application>NetworkManager</application> to auto-connect to this connection when it is available. See <xref linkend="sec-Connecting_to_a_Network_Automatically"/> for more information. + </para> + </listitem> + <listitem> + <para> + <guilabel>All users may connect to this network</guilabel> — Select this box to create a connection available to all users on the system. Changing this setting may require root privileges. See <xref linkend="sec-System-wide_and_Private_Connection_Profiles"/> for details. + </para> + </listitem> + <listitem> + <para> + <guilabel>Automatically connect to VPN when using this connection</guilabel> — Select this box if you want <application>NetworkManager</application> to auto-connect to a VPN connection when it is available. Select the VPN from the drop-down menu. + </para> + </listitem> + <listitem> + <para> + <guilabel>Firewall Zone</guilabel> — Select the Firewall Zone from the dropdown menu. + </para> + </listitem> + + </itemizedlist> + <bridgehead id="bh-Configuring_the_VPN_Tab">Configuring the VPN Tab</bridgehead> + <variablelist> + <varlistentry> + <term> + <guilabel>Gateway</guilabel> + </term> + <listitem> + <para>The name or <systemitem class="protocol">IP</systemitem> address of the remote VPN gateway.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Group name</guilabel> + </term> + <listitem> + <para>The name of a VPN group configured on the remote gateway.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>User password</guilabel> + </term> + <listitem> + <para>If required, enter the password used to authenticate with the VPN.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Group password</guilabel> + </term> + <listitem> + <para>If required, enter the password used to authenticate with the VPN.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>User name</guilabel> + </term> + <listitem> + <para>If required, enter the user name used to authenticate with the VPN.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Phase1 Algorithms</guilabel> + </term> + <listitem> + <para>If required, enter the algorithms to be used to authenticate and set up an encrypted channel.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Phase2 Algorithms</guilabel> + </term> + <listitem> + <para>If required, enter the algorithms to be used for the IPsec negotiations.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Domain</guilabel> + </term> + <listitem> + <para>If required, enter the Domain Name.</para> + </listitem> + </varlistentry> + <!-- this section is for vpnc I think + <varlistentry> + <term> + <guilabel>Encryption Method</guilabel> + </term> + <listitem> + <para> + <guimenuitem>Secure (default)</guimenuitem> — </para> + <para> + <guimenuitem>Weak (use with caution)</guimenuitem> — </para> + <para> + <guimenuitem>None (completely insecure)</guimenuitem> — </para> + </listitem> + </varlistentry> + --> + <!-- maybe also for vpnc? + <varlistentry> + <term> + <guilabel>NAT traversal</guilabel> + </term> + <listitem> + <para> + <guimenuitem>Cisco UDP (default)</guimenuitem> — IPsec over UDP.</para> + <para> + <guimenuitem>NAT-T</guimenuitem> — ESP encapsulation and IKE extensions are used to handle NAT Traversal.</para> + <para> + <guimenuitem>Disabled</guimenuitem> — No special NAT measures required.</para> + <para> + <guilabel>Disable Dead Peer Detection</guilabel> — Disable the sending of probes to the remote gateway or endpoint.</para> + </listitem> + </varlistentry>--> + </variablelist> + <bridgehead + id="bh-Saving_Your_New_or_Modified_Connection_and_Making_Further_Configurations-vpn">Saving Your New (or Modified) Connection and Making Further Configurations</bridgehead> + <para>Once you have finished editing your new VPN connection, click the <guibutton>Save</guibutton> button to save your customized configuration. If the profile was in use while being edited, power cycle the connection to make <application>NetworkManager</application> apply the changes. If the profile is OFF, set it to ON. See <xref + linkend="sec-Connecting_to_a_Network_Using_a_GUI"/> for information on using your new or altered connection.</para> + <para>You can further configure an existing connection by selecting it in the <guilabel>Network</guilabel> window and clicking <guilabel>Configure</guilabel> to return to the <guilabel>Editing</guilabel> dialog.</para> + <para>Then, to configure:</para> + <itemizedlist> + <!--<listitem> + <para>;</para> + </listitem>--> + <listitem> + <para><systemitem class="protocol">IPv4</systemitem> settings for the connection, click the <guilabel>IPv4 Settings</guilabel> tab and proceed to <xref + linkend="sec-Configuring_IPv4_Settings"/>. + </para> + </listitem> + </itemizedlist> + </section> + +<section + id="sec-Establishing_a_Mobile_Broadband_Connection"> + <title>Establishing a Mobile Broadband Connection</title> + <para>You can use <application>NetworkManager</application>'s mobile broadband connection abilities to connect to the following <firstterm>2G</firstterm> and <firstterm>3G</firstterm> services:</para> + <itemizedlist> + <listitem> + <para>2G — <firstterm>GPRS</firstterm> (<firstterm>General Packet Radio Service</firstterm>), <firstterm>EDGE</firstterm> (<firstterm>Enhanced Data Rates for GSM Evolution</firstterm>), or CDMA (Code Division Multiple Access).</para> + </listitem> + <listitem> + <para>3G — <firstterm>UMTS</firstterm> (<firstterm>Universal Mobile Telecommunications System</firstterm>), <firstterm>HSPA</firstterm> (<firstterm>High Speed Packet Access</firstterm>), or EVDO (EVolution Data-Only). + </para> + </listitem> + </itemizedlist> + <para>Your computer must have a mobile broadband device (modem), which the system has discovered and recognized, in order to create the connection. Such a device may be built into your computer (as is the case on many notebooks and netbooks), or may be provided separately as internal or external hardware. Examples include PC card, USB Modem or Dongle, mobile or cellular telephone capable of acting as a modem.</para> + + <procedure + id="procedure-Adding_a_New_Mobile_Broadband_Connection"> + <title>Adding a New Mobile Broadband Connection</title> + <para>You can configure a mobile broadband connection by opening the <guilabel>Network Connections</guilabel> tool and selecting the <guilabel>Mobile Broadband</guilabel> tab.</para> + + <step> + <para>Press the <keycap>Super</keycap> key to enter the Activities Overview, type <command>nm-connection-editor</command> and then press <keycap>Enter</keycap>. The <guilabel>Network Connections</guilabel> tool appears.</para> + </step> + <step> + <para>Click the <guibutton>Add</guibutton> button. The <guilabel>Choose a Connection Type</guilabel> menu opens.</para> + </step> + <step> + <para>Select the <guimenu>Mobile Broadband</guimenu> menu entry.</para> + </step> + <step> + <para>Click <guibutton>Create</guibutton> to open the <guilabel>Set up a Mobile Broadband Connection</guilabel> assistant.</para> + </step> + <step> + <para>Under <guilabel>Create a connection for this mobile broadband device</guilabel>, choose the 2G- or 3G-capable device you want to use with the connection. If the drop-down menu is inactive, this indicates that the system was unable to detect a device capable of mobile broadband. In this case, click <guilabel>Cancel</guilabel>, ensure that you do have a mobile broadband-capable device attached and recognized by the computer and then retry this procedure. Click the <guilabel>Continue</guilabel> button.</para> + </step> + <step> + <para>Select the country where your service provider is located from the list and click the <guilabel>Continue</guilabel> button.</para> + </step> + <step> + <para>Select your provider from the list or enter it manually. Click the <guilabel>Continue</guilabel> button.</para> + </step> + <step><para>Select your payment plan from the drop-down menu and confirm the <firstterm>Access Point Name</firstterm> (<acronym>APN</acronym>) is correct. Click the <guilabel>Continue</guilabel> button.</para> + </step> + <step> + <para>Review and confirm the settings and then click the <guilabel>Apply</guilabel> button.</para> + </step> + <step> + <para>Edit the mobile broadband-specific settings by referring to <xref linkend="sec-Configuring_the_Mobile_Broadband_Tab"/>.</para> + </step> + </procedure> + + <procedure + id="procedure-Editing_an_Existing_Mobile_Broadband_Connection"> + <title>Editing an Existing Mobile Broadband Connection</title> + <para>Follow these steps to edit an existing mobile broadband connection.</para> + <step> + <para>Press the <keycap>Super</keycap> key to enter the Activities Overview, type <command>nm-connection-editor</command> and then press <keycap>Enter</keycap>. The <guilabel>Network Connections</guilabel> tool appears.</para> + </step> + <step> + <para>Select the <guilabel>Mobile Broadband</guilabel> tab.</para> + </step> + <step> + <para>Select the connection you want to edit and click the <guilabel>Edit</guilabel> button.</para> + </step> + <step> + <para>Configure the connection name, auto-connect behavior, and availability settings.</para> + <para>Five settings in the <guilabel>Editing</guilabel> dialog are common to all connection types, see the <guilabel>General</guilabel> tab: + </para> + <itemizedlist> + <listitem> + <para> + <guilabel>Connection name</guilabel> — Enter a descriptive name for your network connection. This name will be used to list this connection in the menu of the <guilabel>Network</guilabel> window. + </para> + </listitem> + <listitem> + <para> + <guilabel>Automatically connect to this network when it is available</guilabel> — Select this box if you want <application>NetworkManager</application> to auto-connect to this connection when it is available. See <xref linkend="sec-Connecting_to_a_Network_Automatically"/> for more information. + </para> + </listitem> + <listitem> + <para> + <guilabel>All users may connect to this network</guilabel> — Select this box to create a connection available to all users on the system. Changing this setting may require root privileges. See <xref linkend="sec-System-wide_and_Private_Connection_Profiles"/> for details. + </para> + </listitem> + <listitem> + <para> + <guilabel>Automatically connect to VPN when using this connection</guilabel> — Select this box if you want <application>NetworkManager</application> to auto-connect to a VPN connection when it is available. Select the VPN from the drop-down menu. + </para> + </listitem> + <listitem> + <para> + <guilabel>Firewall Zone</guilabel> — Select the Firewall Zone from the drop-down menu. + </para> + </listitem> + </itemizedlist> + </step> + + <step> + <para>Edit the mobile broadband-specific settings by referring to <xref linkend="sec-Configuring_the_Mobile_Broadband_Tab"/>.</para> + </step> + </procedure> + + <bridgehead + id="bh-Saving_Your_New_or_Modified_Connection_and_Making_Further_Configurations-mobile_broadband">Saving Your New (or Modified) Connection and Making Further Configurations</bridgehead> + + <para>Once you have finished editing your mobile broadband connection, click the <guibutton>Apply</guibutton> button to save your customized configuration. If the profile was in use while being edited, power cycle the connection to make <application>NetworkManager</application> apply the changes. If the profile is OFF, set it to ON. See <xref + linkend="sec-Connecting_to_a_Network_Using_a_GUI"/> for information on using your new or altered connection.</para> + <para>You can further configure an existing connection by selecting it in the <guilabel>Network Connections</guilabel> window and clicking <guilabel>Edit</guilabel> to return to the <guilabel>Editing</guilabel> dialog.</para> + <para>Then, to configure:</para> + <itemizedlist> + <listitem> + <para><emphasis role="bold">Point-to-point</emphasis> settings for the connection, click the <guilabel>PPP Settings</guilabel> tab and proceed to <xref + linkend="sec-Configuring_PPP_Point-to-Point_Settings"/>;</para> + </listitem> + <listitem> + <para><systemitem class="protocol">IPv4</systemitem> settings for the connection, click the <guilabel>IPv4 Settings</guilabel> tab and proceed to <xref + linkend="sec-Configuring_IPv4_Settings"/>; or, + </para> + </listitem> + <listitem> + <para><systemitem class="protocol">IPv6</systemitem> settings for the connection, click the <guilabel>IPv6 Settings</guilabel> tab and proceed to <xref + linkend="sec-Configuring_IPv6_Settings"/>. + </para> + </listitem> + </itemizedlist> + + <section id="sec-Configuring_the_Mobile_Broadband_Tab"> + <title>Configuring the Mobile Broadband Tab</title> + <para>If you have already added a new mobile broadband connection using the assistant (see <xref linkend="procedure-Adding_a_New_Mobile_Broadband_Connection"/> for instructions), you can edit the <guilabel>Mobile Broadband</guilabel> tab to disable roaming if home network is not available, assign a network ID, or instruct <application>NetworkManager</application> to prefer a certain technology (such as 3G or 2G) when using the connection.</para> + <variablelist> + <varlistentry> + <term> + <guilabel>Number</guilabel> + </term> + <listitem> + <para>The number that is dialed to establish a PPP connection with the GSM-based mobile broadband network. This field may be automatically populated during the initial installation of the broadband device. You can usually leave this field blank and enter the <guilabel>APN</guilabel> instead.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Username</guilabel> + </term> + <listitem> + <para>Enter the user name used to authenticate with the network. Some providers do not provide a user name, or accept any user name when connecting to the network.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Password</guilabel> + </term> + <listitem> + <para>Enter the password used to authenticate with the network. Some providers do not provide a password, or accept any password.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>APN</guilabel> + </term> + <listitem> + <para>Enter the <firstterm>Access Point Name</firstterm> (<acronym>APN</acronym>) used to establish a connection with the GSM-based network. Entering the correct APN for a connection is important because it often determines:</para> + <itemizedlist> + <listitem> + <para>how the user is billed for their network usage; and/or</para> + </listitem> + <listitem> + <para>whether the user has access to the Internet, an intranet, or a subnetwork.</para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Network ID</guilabel> + </term> + <listitem> + <para>Entering a <guilabel>Network ID</guilabel> causes <application>NetworkManager</application> to force the device to register only to a specific network. This can be used to ensure the connection does not roam when it is not possible to control roaming directly.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Type</guilabel> + </term> + <listitem> + <para> + <guilabel>Any</guilabel> — The default value of <guilabel>Any</guilabel> leaves the modem to select the fastest network. + </para> + <para> + <guilabel>3G (UMTS/HSPA)</guilabel> — Force the connection to use only 3G network technologies.</para> + <para> + <guilabel>2G (GPRS/EDGE)</guilabel> — Force the connection to use only 2G network technologies.</para> + <para> + <guilabel>Prefer 3G (UMTS/HSPA)</guilabel> — First attempt to connect using a 3G technology such as HSPA or UMTS, and fall back to GPRS or EDGE only upon failure.</para> + <para> + <guilabel>Prefer 2G (GPRS/EDGE)</guilabel> — First attempt to connect using a 2G technology such as GPRS or EDGE, and fall back to HSPA or UMTS only upon failure.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Allow roaming if home network is not available</guilabel> + </term> + <listitem> + <para>Uncheck this box if you want <application>NetworkManager</application> to terminate the connection rather than transition from the home network to a roaming one, thereby avoiding possible roaming charges. If the box is checked, <application>NetworkManager</application> will attempt to maintain a good connection by transitioning from the home network to a roaming one, and vice versa.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>PIN</guilabel> + </term> + <listitem> + <para>If your device's <firstterm>SIM</firstterm> (<firstterm>Subscriber Identity Module</firstterm>) is locked with a <firstterm>PIN</firstterm> (<firstterm>Personal Identification Number</firstterm>), enter the PIN so that <application>NetworkManager</application> can unlock the device. <application>NetworkManager</application> must unlock the SIM if a PIN is required in order to use the device for any purpose.</para> + </listitem> + </varlistentry> + </variablelist> + <para> + CDMA and EVDO have fewer options. They do not have the <option>APN</option>, <option>Network ID</option>, or <option>Type</option> options. + </para> + </section> + </section> + +<section + id="sec-Establishing_a_DSL_Connection"> + <title>Establishing a DSL Connection</title> + <para>This section is intended for those installations which have a DSL card fitted within a host rather than the external combined DSL modem router combinations typical of private consumer or SOHO installations.</para> + <procedure + id="procedure-Adding_a_New_DSL_Connection"> + <title>Adding a New DSL Connection</title> + <para> + You can configure a new DSL connection by opening the <guilabel>Network Connections</guilabel> window, clicking the <guibutton>Add</guibutton> button and selecting <guilabel>DSL</guilabel> from the <guilabel>Hardware</guilabel> section of the new connection list. + </para> + <step> + <para>Press the <keycap>Super</keycap> key to enter the Activities Overview, type <command>nm-connection-editor</command> and then press <keycap>Enter</keycap>. The <guilabel>Network Connections</guilabel> tool appears.</para> + </step> + <step> + <para>Click the <guibutton>Add</guibutton> button.</para> + </step> + <step> + <para>The <guilabel>Choose a Connection Type</guilabel> list appears.</para> + </step> + <step> + <para>Select <guimenu>DSL</guimenu> and press the <guibutton>Create</guibutton> button.</para> + </step> + <step> + <para>The <guilabel>Editing DSL Connection <replaceable>1</replaceable></guilabel> window appears.</para> + </step> + </procedure> + + <procedure + id="procedure-Editing_an_Existing_DSL_Connection"> + <title>Editing an Existing DSL Connection</title> + <para>You can configure an existing DSL connection by opening the <guilabel>Network Connections</guilabel> window and selecting the name of the connection from the list. Then click the <guibutton>Edit</guibutton> button. + </para> + <step> + <para>Press the <keycap>Super</keycap> key to enter the Activities Overview, type <command>nm-connection-editor</command> and then press <keycap>Enter</keycap>. The <guilabel>Network Connections</guilabel> tool appears.</para> + </step> + <step> + <para>Select the connection you want to edit and click the <guilabel>Edit</guilabel> button.</para> + </step> + </procedure> + + <bridgehead + id="bh-Configuring_the_Connection_Name_Auto-Connect_Behavior_and_Availability_Settings-dsl">Configuring the Connection Name, Auto-Connect Behavior, and Availability Settings</bridgehead> + <para>Five settings in the <guilabel>Editing</guilabel> dialog are common to all connection types, see the <guilabel>General</guilabel> tab: + </para> + <itemizedlist> + <listitem> + <para> + <guilabel>Connection name</guilabel> — Enter a descriptive name for your network connection. This name will be used to list this connection in the menu of the <guilabel>Network</guilabel> window. + </para> + </listitem> + <listitem> + <para> + <guilabel>Automatically connect to this network when it is available</guilabel> — Select this box if you want <application>NetworkManager</application> to auto-connect to this connection when it is available. See <xref linkend="sec-Connecting_to_a_Network_Automatically"/> for more information. + </para> + </listitem> + <listitem> + <para> + <guilabel>All users may connect to this network</guilabel> — Select this box to create a connection available to all users on the system. Changing this setting may require root privileges. See <xref linkend="sec-System-wide_and_Private_Connection_Profiles"/> for details. + </para> + </listitem> + <listitem> + <para> + <guilabel>Automatically connect to VPN when using this connection</guilabel> — Select this box if you want <application>NetworkManager</application> to auto-connect to a VPN connection when it is available. Select the VPN from the drop-down menu. + </para> + </listitem> + <listitem> + <para> + <guilabel>Firewall Zone</guilabel> — Select the Firewall Zone from the drop-down menu. + </para> + </listitem> + </itemizedlist> + + <bridgehead id="bh-Configuring_the_DSL_Tab">Configuring the DSL Tab</bridgehead> + <variablelist> + <varlistentry> + <term> + <guilabel>Username</guilabel> + </term> + <listitem> + <para>Enter the user name used to authenticate with the service provider.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Service</guilabel> + </term> + <listitem> + <para>Leave blank unless otherwise directed by your service provider.</para> + <!-- "Service-Name" (section 5.3) of RFC2516 --> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Password</guilabel> + </term> + <listitem> + <para>Enter the password supplied by the service provider.</para> + </listitem> + </varlistentry> + </variablelist> + + <bridgehead + id="bh-Saving_Your_New_or_Modified_Connection_and_Making_Further_Configurations-DSL">Saving Your New (or Modified) Connection and Making Further Configurations</bridgehead> + + <para>Once you have finished editing your DSL connection, click the <guibutton>Apply</guibutton> button to save your customized configuration. If the profile was in use while being edited, power cycle the connection to make <application>NetworkManager</application> apply the changes. If the profile is OFF, set it to ON. See <xref + linkend="sec-Connecting_to_a_Network_Using_a_GUI"/> for information on using your new or altered connection.</para> + <para>You can further configure an existing connection by selecting it in the <guilabel>Network Connections</guilabel> window and clicking <guilabel>Edit</guilabel> to return to the <guilabel>Editing</guilabel> dialog.</para> + <para>Then, to configure:</para> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">The MAC address and MTU</emphasis> settings, click the <guilabel>Wired</guilabel> tab and proceed to <xref + linkend="sec-Configuring_the_Connection_Name_Auto-Connect_Behavior_and_Availability_Settings-wired" />; + </para> + </listitem> + + <listitem> + <para><emphasis role="bold">Point-to-point</emphasis> settings for the connection, click the <guilabel>PPP Settings</guilabel> tab and proceed to <xref + linkend="sec-Configuring_PPP_Point-to-Point_Settings"/>;</para> + </listitem> + <listitem> + <para><systemitem class="protocol">IPv4</systemitem> settings for the connection, click the <guilabel>IPv4 Settings</guilabel> tab and proceed to <xref + linkend="sec-Configuring_IPv4_Settings"/>. + </para> + </listitem> + </itemizedlist> + </section> + + <section + id="sec-Configuring_Connection_Settings"> + <title>Configuring Connection Settings</title> + <section + id="sec-Configuring_802.1X_Security"> + <title>Configuring 802.1X Security</title> + <para>802.1X security is the name of the IEEE standard for <firstterm>port-based Network Access Control</firstterm> (<acronym>PNAC</acronym>). It is also called <firstterm>WPA Enterprise</firstterm>. Simply put, 802.1X security is a way of controlling access to a <firstterm>logical network</firstterm> from a physical one. All clients who want to join the logical network must authenticate with the server (a router, for example) using the correct 802.1X authentication method.</para> + <para>802.1X security is most often associated with securing wireless networks (WLANs), but can also be used to prevent intruders with physical access to the network (LAN) from gaining entry. In the past, <systemitem class="protocol">DHCP</systemitem> servers were configured not to lease <systemitem class="protocol">IP</systemitem> addresses to unauthorized users, but for various reasons this practice is both impractical and insecure, and thus is no longer recommended. Instead, 802.1X security is used to ensure a logically-secure network through port-based authentication.</para> + <para>802.1X provides a framework for WLAN and LAN access control and serves as an envelope for carrying one of the Extensible Authentication Protocol (EAP) types. An EAP type is a protocol that defines how security is achieved on the network.</para> + <para>You can configure 802.1X security for a wired or wireless connection type by opening the <guilabel>Network</guilabel> window (see <xref linkend="sec-Connecting_to_a_Network_Using_a_GUI"/>) and following the applicable procedure below. Press the <keycap>Super</keycap> key to enter the Activities Overview, type <command>control network</command> and then press <keycap>Enter</keycap>. The <guilabel>Network</guilabel> settings tool appears. Proceed to <xref linkend="procedure-For_a_Wired_Connection" /> or <xref linkend="procedure-For_a_Wireless_Connection" />:</para> + + <procedure + id="procedure-For_a_Wired_Connection"> + <title>For a Wired Connection</title> + <step> + <para>Select a <guilabel>Wired</guilabel> network interface from the left-hand-side menu.</para> + </step> + <step> + <para>Either click on <guibutton>Add Profile</guibutton> to add a new network connection profile for which you want to configure 802.1X security, or select an existing connection profile and click the gear wheel icon.</para> + </step> + <step> + <para>Then select <guilabel>Security</guilabel> and set the symbolic power button to <guilabel>ON</guilabel> to enable settings configuration.</para> + </step> + <step> + <para>Proceed to <xref + linkend="sec-Configuring_TLS_Transport_Layer_Security_Settings"/></para> + </step> + </procedure> + <procedure + id="procedure-For_a_Wireless_Connection"> + <title>For a Wireless Connection</title> + <step> + <para>Select a <guilabel>Wireless</guilabel> network interface from the left-hand-side menu. If necessary, set the symbolic power button to <guilabel>ON</guilabel> and check that your hardware switch is on.</para> + </step> + <step> + <para>Either select the connection name of a new connection, or click the gear wheel icon of an existing connection profile, for which you want to configure 802.1X security. In the case of a new connection, complete any authentication steps to complete the connection and then click the gear wheel icon.</para> + </step> + <step> + <para>Select <guilabel>Security</guilabel>.</para> + </step> + <step> + <para> + From the drop-down menu select one of the following security methods: <guimenuitem>LEAP</guimenuitem>, <guimenuitem>Dynamic WEP (802.1X)</guimenuitem>, or <guimenuitem>WPA & WPA2 Enterprise</guimenuitem>.</para> + </step> + <step> + <para>Refer to <xref + linkend="sec-Configuring_TLS_Transport_Layer_Security_Settings"/> for descriptions of which <firstterm>extensible authentication protocol</firstterm> (<acronym>EAP</acronym>) types correspond to your selection in the <guilabel>Security</guilabel> drop-down menu.</para> + </step> + </procedure> + <section + id="sec-Configuring_TLS_Transport_Layer_Security_Settings"> + <title>Configuring TLS (Transport Layer Security) Settings</title> + <para>With Transport Layer Security, the client and server mutually authenticate using the TLS protocol. The server demonstrates that it holds a digital certificate, the client proves its own identity using its client-side certificate, and key information is exchanged. Once authentication is complete, the TLS tunnel is no longer used. Instead, the client and server use the exchanged keys to encrypt data using AES, TKIP or WEP.</para> + <para>The fact that certificates must be distributed to all clients who want to authenticate means that the EAP-TLS authentication method is very strong, but also more complicated to set up. Using TLS security requires the overhead of a public key infrastructure (PKI) to manage certificates. The benefit of using TLS security is that a compromised password does not allow access to the (W)LAN: an intruder must also have access to the authenticating client's private key.</para> + <para><application>NetworkManager</application> does not determine the version of TLS supported. <application>NetworkManager</application> gathers the parameters entered by the user and passes them to the daemon, <application>wpa_supplicant</application>, that handles the procedure. It in turn uses OpenSSL to establish the TLS tunnel. OpenSSL itself negotiates the SSL/TLS protocol version. It uses the highest version both ends support.</para> + +<bridgehead id="Selecting_an_Authentication_Method">Selecting an Authentication Method</bridgehead> + +<para>Select from one of following authentication methods:</para> + <itemizedlist> + <listitem> + <para> + Select <guilabel>TLS</guilabel> for <firstterm>Transport Layer Security</firstterm> and proceed to <xref + linkend="sec-Configuring_TLS_Settings" />; + </para> + </listitem> + <listitem> + <para> + Select <guilabel>FAST</guilabel> for <firstterm>Flexible Authentication via Secure Tunneling</firstterm> and proceed to <xref + linkend="sec-Configuring_Tunneled_TLS_Settings" />; + </para> + </listitem> + <listitem> + <para> + Select <guilabel>Tunneled TLS</guilabel> for <firstterm>Tunneled Transport Layer Security</firstterm>, otherwise known as TTLS, or EAP-TTLS and proceed to <xref + linkend="sec-Configuring_Tunneled_TLS_Settings" />; + </para> + </listitem> + <listitem> + <para> + Select <guilabel>Protected EAP (PEAP)</guilabel> for <firstterm>Protected Extensible Authentication Protocol</firstterm> and proceed to <xref + linkend="sec-Configuring_Protected_EAP_PEAP_Settings" />. + </para> + </listitem> + </itemizedlist> + </section> + + <section + id="sec-Configuring_TLS_Settings"> + <title>Configuring TLS Settings</title> + <para></para> + <variablelist> + <varlistentry> + <term> + <guilabel>Identity</guilabel> + </term> + <listitem> + <para>Provide the identity of this server.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>User certificate</guilabel> + </term> + <listitem> + <para>Click to browse for, and select, a personal X.509 certificate file encoded with <firstterm>Distinguished Encoding Rules</firstterm> (<acronym>DER</acronym>) or <firstterm>Privacy Enhanced Mail</firstterm> (<acronym>PEM</acronym>).</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>CA certificate</guilabel> + </term> + <listitem> + <para>Click to browse for, and select, an X.509 <firstterm>certificate authority</firstterm> certificate file encoded with <firstterm>Distinguished Encoding Rules</firstterm> (<acronym>DER</acronym>) or <firstterm>Privacy Enhanced Mail</firstterm> (<acronym>PEM</acronym>).</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Private key</guilabel> + </term> + <listitem> + <para>Click to browse for, and select, a <firstterm>private key</firstterm> file encoded with <firstterm>Distinguished Encoding Rules</firstterm> (<acronym>DER</acronym>), <firstterm>Privacy Enhanced Mail</firstterm> (<acronym>PEM</acronym>), or the <firstterm>Personal Information Exchange Syntax Standard</firstterm> (<acronym>PKCS #12</acronym>).</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Private key password</guilabel> + </term> + <listitem> + <para>Enter the password for the private key in the <guilabel>Private key</guilabel> field. Select <guilabel>Show password</guilabel> to make the password visible as you type it.</para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section + id="sec-Configuring_FAST_Settings"> + <title>Configuring FAST Settings</title> + <para></para> + <variablelist> + <varlistentry> + <term> + <guilabel>Anonymous Identity</guilabel> + </term> + <listitem> + <para>Provide the identity of this server.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>PAC provisioning</guilabel> + </term> + <listitem> + <para>Select the check box to enable and then select from <guimenu>Anonymous</guimenu>, <guimenu>Authenticated</guimenu>, and <guimenu>Both</guimenu>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>PAC file</guilabel> + </term> + <listitem> + <para>Click to browse for, and select, a <firstterm>protected access credential</firstterm> (<acronym>PAC</acronym>) file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Inner authentication</guilabel> + </term> + <listitem> + <para> + <guimenuitem>GTC</guimenuitem> — Generic Token Card.</para> + <para> + <guimenuitem>MSCHAPv2</guimenuitem> — Microsoft Challenge Handshake Authentication Protocol version 2.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Username</guilabel> + </term> + <listitem> + <para>Enter the user name to be used in the authentication process.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Password</guilabel> + </term> + <listitem> + <para>Enter the password to be used in the authentication process.</para> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section + id="sec-Configuring_Tunneled_TLS_Settings"> + <title>Configuring Tunneled TLS Settings</title> + <para></para> + <variablelist> + <varlistentry> + <term> + <guilabel>Anonymous identity</guilabel> + </term> + <listitem> + <para>This value is used as the unencrypted identity.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>CA certificate</guilabel> + </term> + <listitem> + <para>Click to browse for, and select, a Certificate Authority's certificate.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Inner authentication</guilabel> + </term> + <listitem> + <para> + <guimenuitem>PAP</guimenuitem> — Password Authentication Protocol.</para> + <para> + <guimenuitem>MSCHAP</guimenuitem> — Challenge Handshake Authentication Protocol.</para> + <para> + <guimenuitem>MSCHAPv2</guimenuitem> — Microsoft Challenge Handshake Authentication Protocol version 2.</para> + <para> + <guimenuitem>CHAP</guimenuitem> — Challenge Handshake Authentication Protocol.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Username</guilabel> + </term> + <listitem> + <para>Enter the user name to be used in the authentication process.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Password</guilabel> + </term> + <listitem> + <para>Enter the password to be used in the authentication process.</para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section + id="sec-Configuring_Protected_EAP_PEAP_Settings"> + <title>Configuring Protected EAP (PEAP) Settings</title> + <variablelist> + <varlistentry> + <term> + <guilabel>Anonymous Identity</guilabel> + </term> + <listitem> + <para>This value is used as the unencrypted identity.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>CA certificate</guilabel> + </term> + <listitem> + <para>Click to browse for, and select, a Certificate Authority's certificate.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>PEAP version</guilabel> + </term> + <listitem> + <para>The version of Protected EAP to use. Automatic, 0 or 1.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Inner authentication</guilabel> + </term> + <listitem> + <para> + <guimenuitem>MSCHAPv2</guimenuitem> — Microsoft Challenge Handshake Authentication Protocol version 2.</para> + <para> + <guimenuitem>MD5</guimenuitem> — Message Digest 5, a cryptographic hash function.</para> + <para> + <guimenuitem>GTC</guimenuitem> — Generic Token Card.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Username</guilabel> + </term> + <listitem> + <para>Enter the user name to be used in the authentication process.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Password</guilabel> + </term> + <listitem> + <para>Enter the password to be used in the authentication process.</para> + </listitem> + </varlistentry> + </variablelist> + </section> + </section> + <section + id="sec-Configuring_Wi-Fi_Security"> + <title>Configuring Wi-Fi Security</title> + <variablelist> + <varlistentry> + <term> + <guilabel>Security</guilabel> + </term> + <listitem> + <para> + <guimenuitem>None</guimenuitem> — Do not encrypt the Wi-Fi connection.</para> + <para> + <guimenuitem>WEP 40/128-bit Key</guimenuitem> — Wired Equivalent Privacy (WEP), from the IEEE 802.11 standard. Uses a single pre-shared key (PSK).</para> + <para> + <guimenuitem>WEP 128-bit Passphrase</guimenuitem> — An MD5 hash of the passphrase will be used to derive a WEP key.</para> + <para> + <guimenuitem>LEAP</guimenuitem> — Lightweight Extensible Authentication Protocol, from Cisco Systems.</para> + <para> + <guimenuitem>Dynamic WEP (802.1X)</guimenuitem> — WEP keys are changed dynamically. Use with <xref linkend="sec-Configuring_TLS_Transport_Layer_Security_Settings" /> </para> + <para> + <guimenuitem>WPA & WPA2 Personal</guimenuitem> — Wi-Fi Protected Access (WPA), from the draft IEEE 802.11i standard. A replacement for WEP. Wi-Fi Protected Access II (WPA2), from the 802.11i-2004 standard. Personal mode uses a pre-shared key (WPA-PSK).</para> + <para> + <guimenuitem>WPA & WPA2 Enterprise</guimenuitem> — WPA for use with a RADIUS authentication server to provide IEEE 802.1X network access control. Use with <xref linkend="sec-Configuring_TLS_Transport_Layer_Security_Settings" /></para> + </listitem> + </varlistentry> + <varlistentry> + <term>Password</term> + <listitem> + <para>Enter the password to be used in the authentication process.</para> + </listitem> + </varlistentry> + </variablelist> + + </section> + <section + id="sec-Configuring_PPP_Point-to-Point_Settings"> + <title>Configuring PPP (Point-to-Point) Settings</title> + <para></para> + <variablelist> + <varlistentry> + <term> + <guilabel>Configure Methods</guilabel> + </term> + <listitem> + <para></para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Use point-to-point encryption (MPPE)</guilabel> + </term> + <listitem> + <para>Microsoft Point-To-Point Encryption protocol (<ulink url="http://www.rfc-editor.org/info/rfc3078"><citetitle pubwork="webpage">RFC 3078</citetitle></ulink>).</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Allow BSD data compression</guilabel> + </term> + <listitem> + <para>PPP BSD Compression Protocol (<ulink url="http://www.rfc-editor.org/info/rfc1977"><citetitle pubwork="webpage">RFC 1977</citetitle></ulink>).</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Allow Deflate data compression</guilabel> + </term> + <listitem> + <para>PPP Deflate Protocol (<ulink url="http://www.rfc-editor.org/info/rfc1979"><citetitle pubwork="webpage">RFC 1979</citetitle></ulink>).</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Use TCP header compression</guilabel> + </term> + <listitem> + <para>Compressing TCP/IP Headers for Low-Speed Serial Links (<ulink url="http://www.rfc-editor.org/info/rfc1144"><citetitle pubwork="webpage">RFC 1144</citetitle></ulink>).</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Send PPP echo packets</guilabel> + </term> + <listitem> + <para>LCP Echo-Request and Echo-Reply Codes for loopback tests (<ulink url="http://www.rfc-editor.org/info/rfc1661"><citetitle pubwork="webpage">RFC 1661</citetitle></ulink>).</para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section + id="sec-Configuring_IPv4_Settings"> + <title>Configuring IPv4 Settings</title> + <para>The <guilabel>IPv4 Settings</guilabel> tab allows you to configure the method used to connect to a network, to enter <systemitem class="protocol">IP</systemitem> address, route, and <systemitem class="protocol">DNS</systemitem> information as required. The <guilabel>IPv4 Settings</guilabel> tab is available when you create and modify one of the following connection types: wired, wireless, mobile broadband, VPN or DSL. If you need to configure <systemitem class="protocol">IPv6</systemitem> addresses, see <xref linkend="sec-Configuring_IPv6_Settings"/>. If you need to configure static routes, click the <guibutton>Routes</guibutton> button and proceed to <xref linkend="sec-Configuring_Routes"/>.</para> + <para>If you are using <systemitem class="protocol">DHCP</systemitem> to obtain a dynamic <systemitem class="protocol">IP</systemitem> address from a <systemitem class="protocol">DHCP</systemitem> server, you can simply set <guilabel>Method</guilabel> to <guimenuitem>Automatic (DHCP)</guimenuitem>.</para> + <bridgehead + id="bh-Setting_the_Method">Setting the Method</bridgehead> + <variablelist + id="varlist-Available_IPv4_Methods_by_Connection_Type"> + <title>Available IPv4 Methods by Connection Type</title> + <para>When you click the <guilabel>Method</guilabel> drop-down menu, depending on the type of connection you are configuring, you are able to select one of the following <systemitem class="protocol">IPv4</systemitem> connection methods. All of the methods are listed here according to which connection type, or types, they are associated with:</para> + <varlistentry> + <term> + <guilabel>Method</guilabel> + </term> + <listitem> + <para> + <guimenuitem>Automatic (DHCP)</guimenuitem> — Choose this option if the network you are connecting to uses a <systemitem class="protocol">DHCP</systemitem> server to assign <systemitem class="protocol">IP</systemitem> addresses. You do not need to fill in the <guilabel>DHCP client ID</guilabel> field.</para> + <para> + <guimenuitem>Automatic (DHCP) addresses only</guimenuitem> — Choose this option if the network you are connecting to uses a <systemitem class="protocol">DHCP</systemitem> server to assign <systemitem class="protocol">IP</systemitem> addresses but you want to assign <systemitem class="protocol">DNS</systemitem> servers manually.</para> + <para> + <guimenuitem>Link-Local Only</guimenuitem> — Choose this option if the network you are connecting to does not have a <systemitem class="protocol">DHCP</systemitem> server and you do not want to assign <systemitem class="protocol">IP</systemitem> addresses manually. Random addresses will be assigned as per <ulink url="http://www.rfc-editor.org/info/rfc3927"><citetitle pubwork="webpage">RFC 3927</citetitle></ulink> with prefix <systemitem class="ipaddress">169.254/16</systemitem>.</para> + <para> + <guimenuitem>Shared to other computers</guimenuitem> — Choose this option if the interface you are configuring is for sharing an Internet or WAN connection. The interface is assigned an address in the <systemitem class="ipaddress">10.42.x.1/24</systemitem> range, a <systemitem class="protocol">DHCP</systemitem> server and <systemitem class="protocol">DNS</systemitem> server are started, and the interface is connected to the default network connection on the system with <firstterm>network address translation</firstterm> (<acronym>NAT</acronym>).</para> + <para> + <guimenuitem>Disabled</guimenuitem> — <systemitem class="protocol">IPv4</systemitem> is disabled for this connection. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Wired, Wireless and DSL Connection Methods</term> + <listitem> + <para> + <guimenuitem>Manual</guimenuitem> — Choose this option if you want to assign <systemitem class="protocol">IP</systemitem> addresses manually.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Mobile Broadband Connection Methods</term> + <listitem> + <para> + <guimenuitem>Automatic (PPP)</guimenuitem> — Choose this option if the network you are connecting to assigns your <systemitem class="protocol">IP</systemitem> address and <systemitem class="protocol">DNS</systemitem> servers automatically.</para> + <para> + <guimenuitem>Automatic (PPP) addresses only</guimenuitem> — Choose this option if the network you are connecting to assigns your <systemitem class="protocol">IP</systemitem> address automatically, but you want to manually specify <systemitem class="protocol">DNS</systemitem> servers.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>VPN Connection Methods</term> + <listitem> + <para> + <guimenuitem>Automatic (VPN)</guimenuitem> — Choose this option if the network you are connecting to assigns your <systemitem class="protocol">IP</systemitem> address and <systemitem class="protocol">DNS</systemitem> servers automatically.</para> + <para> + <guimenuitem>Automatic (VPN) addresses only</guimenuitem> — Choose this option if the network you are connecting to assigns your <systemitem class="protocol">IP</systemitem> address automatically, but you want to manually specify <systemitem class="protocol">DNS</systemitem> servers.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>DSL Connection Methods</term> + <listitem> + <para> + <guimenuitem>Automatic (PPPoE)</guimenuitem> — Choose this option if the network you are connecting to assigns your <systemitem class="protocol">IP</systemitem> address and <systemitem class="protocol">DNS</systemitem> servers automatically.</para> + <para> + <guimenuitem>Automatic (PPPoE) addresses only</guimenuitem> — Choose this option if the network you are connecting to assigns your <systemitem class="protocol">IP</systemitem> address automatically, but you want to manually specify <systemitem class="protocol">DNS</systemitem> servers.</para> + </listitem> + </varlistentry> + </variablelist> + <para>For information on configuring static routes for the network connection, go to <xref + linkend="sec-Configuring_Routes"/>.</para> + </section> + <section + id="sec-Configuring_IPv6_Settings"> + <title>Configuring IPv6 Settings</title> + <variablelist> + <varlistentry> + <term> + <guilabel>Method</guilabel> + </term> + <listitem> + <para> + <guimenuitem>Ignore</guimenuitem> — Choose this option if you want to ignore <systemitem class="protocol">IPv6</systemitem> settings for this connection.</para> + <para> + <guimenuitem>Automatic</guimenuitem> — Choose this option to use <firstterm>SLAAC</firstterm> to create an automatic, stateless configuration based on the hardware address and <firstterm>router advertisements</firstterm> (RA).</para> + <para> + <guimenuitem>Automatic, addresses only</guimenuitem> — Choose this option if the network you are connecting to uses <firstterm>router advertisements</firstterm> (RA) to create an automatic, stateless configuration, but you want to assign <systemitem class="protocol">DNS</systemitem> servers manually.</para> + <para> + <guimenuitem>Automatic, DHCP only</guimenuitem> — Choose this option to not use RA, but request information from <systemitem class="protocol">DHCPv6</systemitem> directly to create a stateful configuration.</para> + <para> + <guimenuitem>Manual</guimenuitem> — Choose this option if you want to assign <systemitem class="protocol">IP</systemitem> addresses manually.</para> + <para> + <guimenuitem>Link-Local Only</guimenuitem> — Choose this option if the network you are connecting to does not have a <systemitem class="protocol">DHCP</systemitem> server and you do not want to assign <systemitem class="protocol">IP</systemitem> addresses manually. Random addresses will be assigned as per <ulink url="http://www.rfc-editor.org/info/rfc4862"><citetitle pubwork="webpage">RFC 4862</citetitle></ulink> with prefix <systemitem class="ipaddress">FE80::0</systemitem>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Addresses</guilabel> + </term> + <listitem> + <para> + <guimenuitem>DNS servers</guimenuitem> — Enter a comma separated list of <systemitem class="protocol">DNS</systemitem> servers.</para> + <para> + <guimenuitem>Search domains</guimenuitem> — Enter a comma separated list of domain controllers.</para> + </listitem> + </varlistentry> + </variablelist> + <para>For information on configuring static routes for the network connection, go to <xref + linkend="sec-Configuring_Routes"/>.</para> + </section> + + <section + id="sec-Configuring_Routes"> + <title>Configuring Routes</title> + <para>A host's routing table will be automatically populated with routes to directly connected networks. The routes are learned by examining the network interfaces when they are <quote>up</quote>. This section describes entering static routes to networks or hosts which can be reached by traversing an intermediate network or connection, such as a VPN tunnel or leased line. In order to reach a remote network or host, the system is given the address of a gateway to which traffic should be sent.</para> + <para> + When a host's interface is configured by <systemitem class="protocol">DHCP</systemitem>, an address of a gateway that leads to an upstream network or the Internet is usually assigned. This gateway is usually referred to as the default gateway as it is the gateway to use if no better route is known to the system (and present in the routing table). Network administrators often use the first or last host <systemitem class="protocol">IP</systemitem> address in the network as the gateway address; for example, <systemitem class="ipaddress">192.168.10.1</systemitem> or <systemitem class="ipaddress">192.168.10.254</systemitem>. Not to be confused by the address which represents the network itself; in this example, <systemitem class="ipaddress">192.168.10.0</systemitem>, or the subnet's broadcast address; in this example <systemitem class="ipaddress">192.168.10.255</systemitem>. + </para> + <bridgehead id="Configuring_Static_Routes">Configuring Static Routes</bridgehead> + <para> + To set a static route, open the <guimenu>IPv4</guimenu> or <guimenu>IPv6</guimenu> settings window for the connection you want to configure. See <xref linkend="sec-Connecting_to_a_Network_Using_a_GUI" /> for instructions on how to do that. + </para> + <variablelist> + <varlistentry> + <term> + <guilabel>Routes</guilabel> + </term> + <listitem> + <para> + <guimenuitem>Address</guimenuitem> — Enter the <systemitem class="protocol">IP</systemitem> address of a remote network, sub-net, or host.</para> + <para> + <guimenuitem>Netmask</guimenuitem> — The netmask or prefix length of the <systemitem class="protocol">IP</systemitem> address entered above.</para> + <para> + <guimenuitem>Gateway</guimenuitem> — The <systemitem class="protocol">IP</systemitem> address of the gateway leading to the remote network, sub-net, or host entered above.</para> + <para> + <guimenuitem>Metric</guimenuitem> — A network cost, a preference value to give to this route. Lower values will be preferred over higher values.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guibutton>Automatic</guibutton> + </term> + <listitem> + <para>When Automatic is <guilabel>ON</guilabel>, routes from <systemitem class="protocol">RA</systemitem> or <systemitem class="protocol">DHCP</systemitem> are used, but you can also add additional static routes. When <guilabel>OFF</guilabel>, only static routes you define are used.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <guilabel>Use this connection only for resources on its network</guilabel> + </term> + <listitem> + <para>Select this check box to prevent the connection from becoming the default route. Typical examples are where a connection is a VPN tunnel or a leased line to a head office and you do not want any Internet-bound traffic to pass over the connection. Selecting this option means that only traffic specifically destined for routes learned automatically over the connection or entered here manually will be routed over the connection.</para> + </listitem> + </varlistentry> + </variablelist> + </section> + </section> + +</section> +<section id="sec-Using_the_Command_Line_Interface"> + <title>Using the Command Line Interface (CLI)</title> +<section id="sec-Configuring_a_Network_Interface_Using_ifcg_Files"> +<title>Configuring a Network Interface Using ifcfg Files</title> + <para> + Interface configuration files control the software interfaces for individual network devices. As the system boots, it uses these files to determine what interfaces to bring up and how to configure them. These files are usually named <filename>ifcfg-<replaceable>name</replaceable></filename>, where the suffix <replaceable>name</replaceable> refers to the name of the device that the configuration file controls. By convention, the <filename>ifcfg</filename> file's suffix is the same as the string given by the <command>DEVICE</command> directive in the configuration file itself. + </para> +<bridgehead id="bh-Static_Network_Settings">Static Network Settings</bridgehead> +<para> + To configure an interface with static network settings using <filename>ifcfg</filename> files, for an interface with the name <interface>eth0</interface>, create a file with name <filename>ifcfg-eth0</filename> in the <filename class="directory">/etc/sysconfig/network-scripts/</filename> directory as follows: + <programlisting>DEVICE=eth0 +BOOTPROTO=none +ONBOOT=yes +PREFIX=24 +IPADDR=10.0.1.27 +</programlisting> +Optionally specify the hardware or MAC address using the <command>HWADDR</command> directive. Note that this may influence the device naming procedure as explained in <xref linkend="ch-Consistent_Network_Device_Naming" />. You do not need to specify the network or broadcast address as this is calculated automatically by <application>ipcalc</application>. To enable a normal user to set the interface up or down, add <command>USERCTL=yes</command>. + +</para> + +<bridgehead id="bh-Dynamic_Network_Settings">Dynamic Network Settings</bridgehead> +<para> + To configure an interface with dynamic network settings using <filename>ifcfg</filename> files, for an interface with name <interface>em1</interface>, create a file with name <filename>ifcfg-em1</filename> in the <filename class="directory">/etc/sysconfig/network-scripts/</filename> directory as follows: + <programlisting>DEVICE=em1 +BOOTPROTO=dhcp +ONBOOT=yes +</programlisting> +Optionally specify the hardware or MAC address using the <command>HWADDR</command> directive. Note that this may influence the device naming procedure as explained in <xref linkend="ch-Consistent_Network_Device_Naming" />. You do not need to specify the network or broadcast address as this is calculated automatically by <application>ipcalc</application>. +</para> +<para> + To configure an interface to send a different host name to the <systemitem class="protocol">DHCP</systemitem> server, add the following line to the <filename>ifcfg</filename> file. + <synopsis>DHCP_HOSTNAME=<replaceable>hostname</replaceable></synopsis> +</para> +<para> + To configure an interface to ignore routes sent by a <systemitem class="protocol">DHCP</systemitem> server, add the following line to the <filename>ifcfg</filename> file. + <synopsis>PEERDNS=no</synopsis> + This will prevent network service from updating <filename>/etc/resolv.conf</filename> with the <systemitem class="protocol">DNS</systemitem> servers received from a <systemitem class="protocol">DHCP</systemitem> server. +</para> +<para> + To configure an interface to use particular <systemitem class="protocol">DNS</systemitem> servers, set <command>PEERDNS=no</command> as described above and add lines as follows to the <filename>ifcfg</filename> file: + <programlisting>DNS1=<replaceable>ip-address</replaceable> +DNS2=<replaceable>ip-address</replaceable></programlisting> + where <replaceable>ip-address</replaceable> is the address of a <systemitem class="protocol">DNS</systemitem> server. This will cause the network service to update <filename>/etc/resolv.conf</filename> with the <systemitem class="protocol">DNS</systemitem> servers specified. +</para> + <para> + <application>NetworkManager</application> will by default call the <systemitem class="protocol">DHCP</systemitem> client, <application>dhclient</application>, when a profile has been set to obtain addresses automatically, or when an interface configuration file has BOOTPROTO set to <literal>dhcp</literal>. Where <systemitem class="protocol">DHCP</systemitem> is required, an instance of <systemitem class="service">dhclient</systemitem> is started for every Internet protocol, <systemitem class="protocol">IPv4</systemitem> and <systemitem class="protocol">IPv6</systemitem>, on an interface. Where <application>NetworkManager</application> is not running, or not managing an interface, then the legacy network service will call instances of <systemitem class="service">dhclient</systemitem> as required. + </para> + + + <!--<para> + For a listing of the configurable parameters in an Ethernet interface configuration file see the <citetitle pubwork="book">&MAJOROSVER; System Administrator's Reference Guide</citetitle>. + </para>--> + </section> + + <section id="sec-Configuring_a_Network_Interface_Using_ip_commands"> +<title>Configuring a Network Interface Using ip Commands</title> +<para> + The <application>ip</application> utility can be used to assign <systemitem class="protocol">IP</systemitem> addresses to an interface. The command takes the following form: +<synopsis>ip addr <optional> add | del </optional> <replaceable>address</replaceable> dev <replaceable>ifname</replaceable></synopsis></para> + + <bridgehead id="bh-Assigning_a_Static_Address_Using_ip_Commands"> + Assigning a Static Address Using ip Commands + </bridgehead> + <para> +To assign an <systemitem class="protocol">IP</systemitem> address to an interface, issue a command as <systemitem class="username">root</systemitem> as follows: +<screen>~]# <command>ip address add 10.0.0.3/24 dev eth0</command> +The address assignment of a specific device can be viewed as follows: +~]# <command>ip addr show dev eth0</command> +2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP qlen 1000 + link/ether f0:de:f1:7b:6e:5f brd ff:ff:ff:ff:ff:ff + inet 10.0.0.3/24 brd 10.0.0.255 scope global global eth0 + valid_lft 58682sec preferred_lft 58682sec + inet6 fe80::f2de:f1ff:fe7b:6e5f/64 scope link + valid_lft forever preferred_lft forever</screen> + Further examples and command options can be found in the <filename>ip-address(8)</filename> manual page. +</para> + + <bridgehead id="bh-Configuring_Multiple_Addresses_Using_ip_Commands"> + Configuring Multiple Addresses Using ip Commands + </bridgehead> + <para> + As the <application>ip</application> utility supports assigning multiple addresses to the same interface it is no longer necessary to use the alias interface method of binding multiple addresses to the same interface. The <application>ip</application> command to assign an address can be repeated multiple times in order to assign multiple address. For example: + <screen>~]# <command>ip address add 192.168.2.223/24 dev eth1</command> +~]# <command>ip address add 192.168.4.223/24 dev eth1</command> +~]# <command>ip addr</command> +3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP qlen 1000 + link/ether 52:54:00:fb:77:9e brd ff:ff:ff:ff:ff:ff + inet 192.168.<emphasis role="bold">2</emphasis>.223/24 scope global eth1 + inet 192.168.<emphasis role="bold">4</emphasis>.223/24 scope global eth1</screen> + </para> + <para>The commands for the <application>ip</application> utility are documented in the <filename>ip(8)</filename> manual page.</para> + <note> + <para> + Note that <application>ip</application> commands given on the command line will not persist after a system restart. + </para> + </note> + + </section> + +<section id="sec-Static-Routes_and_the_Default_Gateway"> + <title>Static Routes and the Default Gateway</title> + <para> + Static routes are for traffic that must not, or should not, go through the default gateway. Routing is often handled by devices on the network dedicated to routing (although any device can be configured to perform routing). Therefore, it is often not necessary to configure static routes on Fedora servers or clients. Exceptions include traffic that must pass through an encrypted VPN tunnel or traffic that should take a specific route for reasons of cost or security. The default gateway is for any and all traffic which is not destined for the local network and for which no preferred route is specified in the routing table. The default gateway is traditionally a dedicated network router. + </para> + <bridgehead id="bh-networkscripts-static-routes"> + Configuring Static Routes Using the Command Line + </bridgehead> + <indexterm> + <primary>static route</primary> + </indexterm> + <para> + If static routes are required, they can be added to the routing table by means of the <command>ip route add</command> command and removed using the <command>ip route del</command> command. The more frequently used <command>ip route</command> commands take the following form: +<synopsis>ip route <optional> add | del | change | append | replace </optional> <replaceable>destination-address</replaceable></synopsis> +See the <filename>ip-route(8)</filename> man page for more details on the options and formats.</para> +<para> +Use the <command>ip route</command> command without options to display the <systemitem class="protocol">IP</systemitem> routing table. For example: +<screen>~]$ ip route +default via 192.168.122.1 dev eth1 proto static metric 1024 +192.168.122.0/24 dev eth1 proto kernel scope link src 192.168.122.107 +192.168.122.0/24 dev eth0 proto kernel scope link src 192.168.122.126</screen> +</para> + + + <para>To add a static route to a host address, in other words to a single <systemitem class="protocol">IP</systemitem> address, issue a command as <systemitem class="username">root</systemitem>: + <screen>ip route add <replaceable>192.0.2.1</replaceable> via <replaceable>10.0.0.1</replaceable> <optional><option>dev</option> <replaceable>ifname</replaceable></optional></screen> + Where <replaceable>192.0.2.1</replaceable> is the <systemitem class="protocol">IP</systemitem> address of the host in dotted decimal notation, <replaceable>10.0.0.1</replaceable> is the next hop address and <replaceable>ifname</replaceable> is the exit interface leading to the next hop.</para> + <para>To add a static route to a network, in other words to an <systemitem class="protocol">IP</systemitem> address representing a range of <systemitem class="protocol">IP</systemitem> addresses, issue the following command as <systemitem class="username">root</systemitem>: + <screen>ip route add <replaceable>192.0.2.0/24</replaceable> via <replaceable>10.0.0.1</replaceable> <optional><option>dev</option> <replaceable>ifname</replaceable></optional></screen> where <replaceable>192.0.2.0</replaceable> is the <systemitem class="protocol">IP</systemitem> address of the destination network in dotted decimal notation and <replaceable>/24</replaceable> is the network prefix. The network prefix is the number of enabled bits in the subnet mask. This format of network address slash network prefix length is sometimes referred to as <firstterm>classless inter-domain routing</firstterm> (<acronym>CIDR</acronym>) notation. + </para> + + <para> + Static route configuration can be stored per-interface in a <filename>/etc/sysconfig/network-scripts/route-<replaceable>interface</replaceable></filename> file. For example, static routes for the <interface>eth0</interface> interface would be stored in the <filename>/etc/sysconfig/network-scripts/route-eth0</filename> file. The <filename>route-<replaceable>interface</replaceable></filename> file has two formats: <application>ip</application> command arguments and network/netmask directives. These are described below. + </para> + + <para> + See the <filename>ip-route(8)</filename> man page for more information on the <command>ip route</command> command. + </para> + + <bridgehead id="bh-networkscripts-default-gateway"> + Configuring The Default Gateway + </bridgehead> + <indexterm> + <primary>default gateway</primary></indexterm> + <para> + The default gateway is determined by the network scripts which parse the <filename>/etc/sysconfig/network</filename> file first and then the network interface <literal>ifcfg</literal> files for interfaces that are <quote>up</quote>. The <literal>ifcfg</literal> files are parsed in numerically ascending order, and the last GATEWAY directive to be read is used to compose a default route in the routing table.</para> + <para> + The default route can thus be indicated by means of the GATEWAY directive, either globally or in interface-specific configuration files. However, in &MAJOROS; the use of the global <filename>/etc/sysconfig/network</filename> file is deprecated, and specifying the gateway should now only be done in per-interface configuration files. + </para> + <para> + In dynamic network environments, where mobile hosts are managed by <application>NetworkManager</application>, gateway information is likely to be interface specific and is best left to be assigned by <systemitem class="protocol">DHCP</systemitem>. In special cases where it is necessary to influence <application>NetworkManager</application>'s selection of the exit interface to be used to reach a gateway, make use of the <command>DEFROUTE=no</command> command in the <literal>ifcfg</literal> files for those interfaces which do not lead to the default gateway. + </para> + </section> + +<section id="sec-Configuring_Static_Routes_in_ifcfg_files"> +<title>Configuring Static Routes in ifcfg files</title> +<para> +Static routes set using <application>ip</application> commands on the command line will be lost if the system is shutdown or restarted. To configure static routes to be persistent after a system restart, they must be placed in per-interface configuration files in the <filename class="directory">/etc/sysconfig/network-scripts/</filename> directory. The file name should be of the format <filename>route-<replaceable>ifname</replaceable></filename>. There are two types of commands to use in the configuration files; <application>ip</application> commands as explained in <xref linkend="sec-networkscripts-static-routes-ip-command" /> and the <firstterm>Network/Netmask</firstterm> format as explained in <xref linkend="sec-networkscripts-static-routes-network-netmask-directives" />. +</para> + +<section id="sec-networkscripts-static-routes-ip-command"> + <title>Static Routes Using the IP Command Arguments Format</title> + <para> + If required in a per-interface configuration file, for example <filename>/etc/sysconfig/network-scripts/route-eth0</filename>, define a route to a default gateway on the first line. This is only required if the gateway is not set via <systemitem class="protocol">DHCP</systemitem> and is not set globally in the <filename>/etc/sysconfig/network</filename> file: + </para> + <synopsis>default via <replaceable>192.168.1.1</replaceable> <option>dev</option> <replaceable>interface</replaceable></synopsis> + <para> + where <replaceable>192.168.1.1</replaceable> is the <systemitem class="protocol">IP</systemitem> address of the default gateway. The <replaceable>interface</replaceable> is the interface that is connected to, or can reach, the default gateway. The <option>dev</option> option can be omitted, it is optional. Note that this setting takes precedence over a setting in the <filename>/etc/sysconfig/network</filename> file. + </para> + <para> + If a route to a remote network is required, a static route can be specified as follows. Each line is parsed as an individual route: + </para> + <synopsis><replaceable>10.10.10.0/24</replaceable> via <replaceable>192.168.1.1</replaceable> <optional><option>dev</option> <replaceable>interface</replaceable></optional></synopsis> + <para> + where <replaceable>10.10.10.0/24</replaceable> is the network address and prefix length of the remote or destination network. The address <replaceable>192.168.1.1</replaceable> is the <systemitem class="protocol">IP</systemitem> address leading to the remote network. It is preferably the <firstterm>next hop address</firstterm> but the address of the exit interface will work. The <quote>next hop</quote> means the remote end of a link, for example a gateway or router. The <option>dev</option> option can be used to specify the exit interface <replaceable>interface</replaceable> but it is not required. Add as many static routes as required. + </para> + <para> + The following is an example of a <filename>route-<replaceable>interface</replaceable></filename> file using the <application>ip</application> command arguments format. The default gateway is <systemitem class="ipaddress">192.168.0.1</systemitem>, interface <interface>eth0</interface> and a leased line or WAN connection is available at <systemitem class="ipaddress">192.168.0.10</systemitem>. The two static routes are for reaching the <systemitem class="ipaddress">10.10.10.0/24</systemitem> network and the <systemitem class="ipaddress">172.16.1.10/32</systemitem> host: + </para> + <screen>default via 192.168.0.1 dev eth0 +10.10.10.0/24 via 192.168.0.10 dev eth0 +172.16.1.10/32 via 192.168.0.10 dev eth0</screen> + <para> + In the above example, packets going to the local <systemitem class="ipaddress">192.168.0.0/24</systemitem> network will be directed out the interface attached to that network. Packets going to the <systemitem class="ipaddress">10.10.10.0/24</systemitem> network and <systemitem class="ipaddress">172.16.1.10/32</systemitem> host will be directed to <systemitem class="ipaddress">192.168.0.10</systemitem>. Packets to unknown, remote, networks will use the default gateway therefore static routes should only be configured for remote networks or hosts if the default route is not suitable. Remote in this context means any networks or hosts that are not directly attached to the system.</para> + <!-- Adding in this comment as per [Bug 446997] Static routes and default gateway are interface -specific ? --> + <para> + Specifying an exit interface is optional. It can be useful if you want to force traffic out of a specific interface. For example, in the case of a VPN, you can force traffic to a remote network to pass through a <interface>tun0</interface> interface even when the interface is in a different subnet to the destination network. + </para> + <important> + <title>Duplicate default gateways</title> + <para> + If the default gateway is already assigned by <systemitem class="protocol">DHCP</systemitem> and if the same gateway with the same metric is specified in a configuration file, an error during start-up, or when bringing up an interface, will occur. The follow error message may be shown: "RTNETLINK answers: File exists". This error may be ignored.</para> + </important> + </section> + <section id="sec-networkscripts-static-routes-network-netmask-directives"> + <title>Network/Netmask Directives Format</title> + <para> + You can also use the network/netmask directives format for <filename>route-<replaceable>interface</replaceable></filename> files. The following is a template for the network/netmask format, with instructions following afterwards: + </para> + <synopsis> + ADDRESS0=<replaceable>10.10.10.0</replaceable> + NETMASK0=<replaceable>255.255.255.0</replaceable> + GATEWAY0=<replaceable>192.168.1.1</replaceable> + </synopsis> + <itemizedlist> + <listitem> + <para> + <computeroutput>ADDRESS0=<replaceable>10.10.10.0</replaceable></computeroutput> is the network address of the remote network or host to be reached. + </para> + </listitem> + <listitem> + <para> + <computeroutput>NETMASK0=<replaceable>255.255.255.0</replaceable></computeroutput> is the netmask for the network address defined with <computeroutput>ADDRESS0=<replaceable>10.10.10.0</replaceable></computeroutput>. + </para> + </listitem> + <listitem> + <para> + <computeroutput>GATEWAY0=<replaceable>192.168.1.1</replaceable></computeroutput> is the default gateway, or an <systemitem class="protocol">IP</systemitem> address that can be used to reach <computeroutput>ADDRESS0=<replaceable>10.10.10.0</replaceable></computeroutput> + </para> + </listitem> + </itemizedlist> + <para> + The following is an example of a <filename>route-<replaceable>interface</replaceable></filename> file using the network/netmask directives format. The default gateway is <systemitem class="ipaddress">192.168.0.1</systemitem> but a leased line or WAN connection is available at <systemitem class="ipaddress">192.168.0.10</systemitem>. The two static routes are for reaching the <systemitem class="ipaddress">10.10.10.0/24</systemitem> and <systemitem class="ipaddress">172.16.1.0/24</systemitem> networks: + </para> + <programlisting>ADDRESS0=10.10.10.0 +NETMASK0=255.255.255.0 +GATEWAY0=192.168.0.10 +ADDRESS1=172.16.1.10 +NETMASK1=255.255.255.0 +GATEWAY1=192.168.0.10</programlisting> + <para> + Subsequent static routes must be numbered sequentially, and must not skip any values. For example, <computeroutput>ADDRESS0</computeroutput>, <computeroutput>ADDRESS1</computeroutput>, <computeroutput>ADDRESS2</computeroutput>, and so on. + </para> + </section> + </section> + + + + <section id="sec-Configuring_IPv6_Tokenized_Interface_Identifiers"> + <title>Configuring IPv6 Tokenized Interface Identifiers</title> + <para> + In a network, servers are generally given static addresses and these are usually configured manually to avoid relying on a <systemitem class="protocol">DHCP</systemitem> server which may fail or run out of addresses. The <systemitem class="protocol">IPv6</systemitem> protocol introduced <firstterm>Stateless Address Autoconfiguration</firstterm> (<acronym>SLAAC</acronym>) which enables clients to assign themselves an address without relying on a <systemitem class="protocol">DHCPv6</systemitem> server. SLAAC derives the <systemitem class="protocol">IPv6</systemitem> address based on the interface hardware, therefore it should not be used for servers in case the hardware is changed and the associated SLAAC generated address changes with it. In an <systemitem class="protocol">IPv6</systemitem> environment, if the network prefix is changed, or the system is moved to a new location, any manually configured static addresses would have to be edited due to the changed prefix. +</para> +<para> +To address these problems, the IETF draft <ulink url="https://tools.ietf.org/id/draft-chown-6man-tokenised-ipv6-identifiers-02.txt"><citetitle pubwork="webpage">Tokenised IPv6 Identifiers</citetitle></ulink> has been implemented in the kernel together with corresponding additions to the <command>ip</command> utility. This enables the lower 64 bit interface identifier part of the <systemitem class="protocol">IPv6</systemitem> address to be based on a token, supplied by the administrator, leaving the network prefix, the higher 64 bits, to be obtained from <firstterm>router advertisements</firstterm> (<acronym>RA</acronym>). This means that if the network interface hardware is changed, the lower 64 bits of the address will not change, and if the system is moved to another network, the network prefix will be obtained from router advertisements automatically, thus no manual editing is required.</para> + <para> + To configure an interface to use a tokenized <systemitem class="protocol">IPv6</systemitem> identifier, issue a command in the following format as <systemitem class="username">root</systemitem> user: + <screen>~]# <command>ip token set ::1a:2b:3c:4d/64 dev eth4</command></screen> + Where <literal>::1a:2b:3c:4d/64</literal> is the token to be used. This setting is not persistent. To make it persistent, add the command to an init script. See <xref linkend="sec-Network_Configuration_Using_sysconfig_Files" /> for information on network scripts.</para> + <para> + Using a memorable token is possible, but is limited to the range of valid hexadecimal digits. For example, for a <systemitem class="protocol">DNS</systemitem> server, which traditionally uses port <literal>53</literal>, a token of <literal>::53/64</literal> could be used. + </para> + <para> + To view all the configured <systemitem class="protocol">IPv6</systemitem> tokens, issue the following command: + <screen>~]$ <command>ip token</command> + token :: dev eth0 + token :: dev eth1 + token :: dev eth2 + token :: dev eth3 + token ::1a:2b:3c:4d dev eth4</screen> + </para> + <para> + To view the configured <systemitem class="protocol">IPv6</systemitem> token for a specific interface, issue the following command: + <screen>~]$ <command>ip token get dev eth4</command> + token ::1a:2b:3c:4d dev eth4</screen> + </para> + <para> + Note that adding a token to an interface will replace a previously allocated token, and in turn invalidate the address derived from it. Supplying a new token causes a new address to be generated and applied, but this process will leave any other addresses unchanged. In other words, a new tokenized identifier only replaces a previously existing tokenized identifier, not any other <systemitem class="protocol">IP</systemitem> address.</para> + <note> + <para> +Take care not to add the same token to more than one system or interface. The duplicate address detection (<acronym>DAD</acronym>) mechanism will remove the duplicate address from the interface but it cannot change the configuration. Once a token is set, it cannot be cleared or reset, except by rebooting the machine. + </para> + </note> +</section> + +</section> + <section id="sec-Using_the_NetworkManager_Command_Line_Tool_nmcli"> + <title>Using the NetworkManager Command Line Tool, nmcli</title> + <para> + The command‐line tool <application>nmcli</application> can be used by both users and scripts for controlling <application>NetworkManager</application>. The basic format of a command is as follows: + <synopsis>nmcli <option>OPTIONS</option> OBJECT { <command>COMMAND</command> | help }</synopsis> + where OBJECT can be one of <literal>general</literal>, <literal>networking</literal>, <literal>radio</literal>, <literal>connection</literal>, or <literal>device</literal>. The most used options are: <option>-t, --terse</option> for use in scripts, the <option>-p, --pretty</option> option for users, and the <option>-h, --help</option> option. Command completion has been implemented for <application>nmcli</application>, so remember to press <keycap>Tab</keycap> whenever you are unsure of the command options available. See the <filename>nmcli(1)</filename> man page for a complete list of the options and commands. + </para> + <para> + The <application>nmcli</application> tool has some built-in context-sensitive help. For example, issue the following two commands and notice the difference: + <screen>~]$ <command>nmcli help</command> +Usage: nmcli [OPTIONS] OBJECT { COMMAND | help } + +OPTIONS + -t[erse] terse output + -p[retty] pretty output + -m[ode] tabular|multiline output mode + -f[ields] <field1,field2,...>|all|common specify fields to output + -e[scape] yes|no escape columns separators in values + -n[ocheck] don't check nmcli and NetworkManager versions + -a[sk] ask for missing parameters + -w[ait] <seconds> set timeout waiting for finishing operations + -v[ersion] show program version + -h[elp] print this help + +OBJECT + g[eneral] NetworkManager's general status and operations + n[etworking] overall networking control + r[adio] NetworkManager radio switches + c[onnection] NetworkManager's connections + d[evice] devices managed by NetworkManager</screen> +<screen>~]$ <command>nmcli general help</command> +Usage: nmcli general { COMMAND | help } + + COMMAND := { status | hostname | permissions | logging } + + status + + hostname [<hostname>] + + permissions + + logging [level <log level>] [domains <log domains>]</screen> +In the second example above the help is related to the object <literal>general</literal>. + </para> + + <para> + The <filename>nmcli-examples(5)</filename> man page has many useful examples. A brief selection is shown here: + </para> + <para> + To show the overall status of <application>NetworkManager</application>: + <synopsis>nmcli general status</synopsis> + To control <application>NetworkManager</application> logging: + <synopsis>nmcli general logging</synopsis> + To show all connections: + <synopsis>nmcli connection show</synopsis> + To show only currently active connections, add the <option>-a, --active</option> option as follows: + <synopsis>nmcli connection show --active</synopsis> + To show devices recognized by <application>NetworkManager</application> and their state: + <synopsis>nmcli device status</synopsis> + </para> + <para> + Commands can be shortened and some options omitted. For example the command: + <synopsis>nmcli connection modify id '<replaceable>MyCafe</replaceable>' 802-11-wireless.mtu 1350</synopsis> + Can be reduced to the following command: + <synopsis>nmcli con mod <replaceable>MyCafe</replaceable> 802-11-wireless.mtu 1350</synopsis> + The <option>id</option> option can be omitted because the connection ID (name) is unambiguous for <application>nmcli</application> in this case. + As you become familiar with the commands, further abbreviations can be made. For example: + <synopsis>nmcli connection add type ethernet</synopsis> + can be reduced to: + <synopsis>nmcli c a type eth</synopsis> + <note> + <para> + Remember to use tab completion when in doubt. + </para> + </note> +</para> +<bridgehead id="bh-Starting_and_Stopping_an_Interface_Using_nmcli">Starting and Stopping an Interface Using nmcli</bridgehead> +<para> + The <application>nmcli</application> tool can be used to start and stop any network interface, including masters. For example: + <screen>nmcli con up id bond0 +nmcli con up id port0 +nmcli dev disconnect iface bond0 +nmcli dev disconnect iface eth0</screen> +</para> +<note><para> +It is recommended to use <command>nmcli dev disconnect iface <replaceable>iface-name</replaceable></command> rather than <command>nmcli con down id <replaceable>id-string</replaceable></command> because disconnection places the interface into a <quote>manual</quote> mode, in which no automatic connection will be started until the user tells <application>NetworkManager</application> to start a connection or until an external event like a carrier change, hibernate, or sleep, occurs.</para></note> +<bridgehead id="bh-The_nmcli_Interactive_Connection_Editor">The nmcli Interactive Connection Editor</bridgehead> + <para> + The <application>nmcli</application> tool has an interactive connection editor. To use it, enter the following command: + <screen>~]$ <command>nmcli con edit</command></screen> +You will be prompted to enter a valid connection type from the list displayed. After entering a connection type you will be placed at the <application>nmcli</application> prompt. If you are familiar with the connection types you can add a valid connection <option>type</option> option to the <command>nmcli con edit</command> command and be taken straight to the <application>nmcli</application> prompt. The format is as follows for editing an existing connection profile: +<synopsis>nmcli con edit [id | uuid | path] <replaceable>ID</replaceable></synopsis> +For adding and editing a new connection profile, the following format applies: +<synopsis>nmcli con edit [type <replaceable>new-connection-type</replaceable>] [con-name <replaceable>new-connection-name</replaceable>]</synopsis> +</para> +<para>Type <command>help</command> at the <application>nmcli</application> prompt to see a list of valid commands. Use the <command>describe</command> command to get a description of settings and their properties. The format is as follows: + <synopsis>describe <replaceable>setting.property</replaceable></synopsis> +For example: +<screen>nmcli> <command>describe team.config</command></screen> + </para> + +<section id="sec-Understanding_the_nmcli_Options"> + <title>Understanding the nmcli Options</title> + <para> + Many of the <application>nmcli</application> commands are self-explanatory, however a few command options are worth a moments study: + </para> + + <variablelist> + <varlistentry> + <term><option>type</option> — The connection type.</term> + <listitem> + <para> + Allowed values are: <literal>adsl</literal>, <literal>bond</literal>, <literal>bond-slave</literal>, <literal>bridge</literal>, <literal>bridge-slave</literal>, <literal>bluetooth</literal>, <literal>cdma</literal>, <literal>ethernet</literal>, <literal>generic</literal>, <literal>gsm</literal>, <literal>infiniband</literal>, <literal>olpc-mesh</literal>, <literal>pppoe</literal>, <literal>team</literal>, <literal>team-slave</literal>, <literal>vlan</literal>, <literal>vpn</literal>, <literal>wifi</literal>, <literal>wimax</literal>. + </para> + + <para> + Each connection type has type-specific command options. Press <keycap>Tab</keycap> to see a list of them or see the <literal>TYPE_SPECIFIC_OPTIONS</literal> list in the <filename>nmcli(1)</filename> man page. The <option>type</option> option is applicable after the following: <command>nmcli connection add</command> and <command>nmcli connection edit</command>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>con-name</option> — The name assigned to a connection profile.</term> + <listitem> + <para> + If you do not specify a connection name, one will be generated as follows: + <synopsis> <literal>type</literal>-ifname[-number]</synopsis> + </para> + <para> + The connection name is the name of a <firstterm>connection profile</firstterm> and should not be confused with the interface name that denotes a device (<interface>wlan0</interface>, <interface>eth0</interface>, <interface>em1</interface>, and so on). Users can however name the connections after interfaces, but they are not the same thing. There can be multiple connection profiles available for a device. This is particularly useful for mobile devices or when switching a network cable back and forth between different devices. Rather than edit the configuration, create different profiles and apply them to the interface as needed. The <option>id</option> option also refers to the connection profile name. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>id</option> — An identification string assigned by the user to a connection profile.</term> + <listitem> + <para> + The ID can be used in <command>nmcli connection</command> commands to identify a connection. The NAME field in the output always denotes the connection ID (name). It refers to the same connection profile name that the <command>con-name</command> does. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>uuid</option> — A unique identification string assigned by the system to a connection profile.</term> + <listitem> + <para> + The UUID can be used in <command>nmcli connection</command> commands to identify a connection. + </para> + </listitem> + </varlistentry> +</variablelist> +</section> + +<section id="sec-Connecting_to_a_Network_Using_nmcli"> + <title>Connecting to a Network Using nmcli</title> + <para> + To list the currently available network connections, issue a command as follows: + <screen>~]$ <command>nmcli con show</command> +NAME UUID TYPE DEVICE +eth0 96a5deb0-5eb0-41e1-a7ed-38fea413f9c8 802-3-ethernet eth0 +MyWiFi 91451385-4eb8-4080-8b82 802-11-wireless wlan0</screen> +Note that the NAME field in the output always denotes the connection ID (name). It is not the interface name even though it might look the same. In the example above <literal>eth0</literal> is the connection ID given by the user to the profile applied to the interface <interface>eth0</interface>. In the second line the user has assigned the connection ID <literal>MyWiFi</literal> to the interface <literal>wlan0</literal>. +</para> + <para> + Adding an Ethernet connection means creating a configuration profile which is then assigned to a device. Before creating a new profile, review the available devices + as follows: +<screen>~]$ <command>nmcli dev status</command> +DEVICE TYPE STATE CONNECTION +wlan0 wifi connected my-ssid +eth0 ethernet unavailable -- +lo loopback unmanaged --</screen> + </para> + + <bridgehead id="Adding_a_Dynamic_Ethernet_Connection">Adding a Dynamic Ethernet Connection</bridgehead> + <para> + To add an Ethernet configuration profile with dynamic <systemitem class="protocol">IP</systemitem> configuration, allowing <systemitem class="protocol">DHCP</systemitem> to assign the network configuration, a command in the following format can be used: + <synopsis>nmcli connection add type ethernet con-name <replaceable>connection-name</replaceable> ifname <replaceable>interface-name</replaceable></synopsis></para> + <para> + For example, to create a dynamic connection profile named <replaceable>my-office</replaceable>, issue a command as follows: + <screen>~]$ <command>nmcli con add type ethernet con-name <replaceable>my-office</replaceable> ifname <replaceable>eth0</replaceable></command> +Connection 'my-office' (0a053110-5361-412c-a4fb-6ff20877e9e4) successfully added.</screen> + <application>NetworkManager</application> will set its internal parameter <option>connection.autoconnect</option> to <literal>yes</literal>. <application>NetworkManager</application> will also write out settings to <filename>/etc/sysconfig/network-scripts/ifcfg-my-office</filename> where the ONBOOT directive will be set to <literal>yes</literal>.</para> + <para> + Note that manual changes to the ifcfg file will not be noticed by <application>NetworkManager</application> until the interface is next brought up. See <xref linkend="sec-Network_Configuration_Using_sysconfig_Files" /> for more information on using configuration files.</para> + <para> + To bring up the Ethernet connection, issue a command as follows: + <screen>~]$ <command>nmcli con up <replaceable>my-office</replaceable></command> +Connection successfully activated (D-Bus active path: /org/freedesktop/NetworkManager/ActiveConnection/1)</screen> +Review the status of the devices and connections: +<screen>~]$ <command>nmcli device status</command> +DEVICE TYPE STATE CONNECTION +eth0 ethernet connected my-office +lo loopback unmanaged --</screen> + </para> + +<para> + To change the host name sent by a host to a <systemitem class="protocol">DHCP</systemitem> server, modify the <option>dhcp-hostname</option> property as follows: + <screen>~]$ <command>nmcli con modify my-office <replaceable>my-office</replaceable> ipv4.dhcp-hostname <replaceable>host-name</replaceable> ipv6.dhcp-hostname <replaceable>host-name</replaceable></command></screen> +</para> + +<para> + To change the <systemitem class="protocol">IPv4</systemitem> client ID sent by a host to a <systemitem class="protocol">DHCP</systemitem> server, modify the <option>dhcp-client-id</option> property as follows: + <screen>~]$ <command>nmcli con modify my-office <replaceable>my-office</replaceable> ipv4.dhcp-client-id <replaceable>client-ID-string</replaceable></command></screen> + There is no <option>dhcp-client-id</option> property for <systemitem class="protocol">IPv6</systemitem>, <application>dhclient</application> creates an identifier for <systemitem class="protocol">IPv6</systemitem>. See the <filename>dhclient(8)</filename> man page for details. +</para> + + +<para> + To ignore the <systemitem class="protocol">DNS</systemitem> servers sent to a host by a <systemitem class="protocol">DHCP</systemitem> server, modify the <option>ignore-auto-dns</option> property as follows: + <screen>~]$ <command>nmcli con modify my-office <replaceable>my-office</replaceable> ipv4.ignore-auto-dns <replaceable>yes</replaceable> ipv6.ignore-auto-dns <replaceable>yes</replaceable></command></screen> +</para> + +<para> + See the <filename>nm-settings(5)</filename> man page for more information on properties and their settings. +</para> + +<example id="ex-Configuring_a_Dynamic_Ethernet_Connection_Using_the_Interactive_Editor"> +<title>Configuring a Dynamic Ethernet Connection Using the Interactive Editor</title> + +<para> + To configure a dynamic Ethernet connection using the interactive editor, issue commands as follows: + <screen>~]$ <command>nmcli con edit type ethernet con-name <replaceable>eth0</replaceable></command> + +===| nmcli interactive connection editor |=== + +Adding a new '802-3-ethernet' connection + +Type 'help' or '?' for available commands. +Type 'describe [<setting>.<prop>]' for detailed property description. + +You may edit the following settings: connection, 802-3-ethernet (ethernet), 802-1x, ipv4, ipv6, dcb +nmcli> describe ipv4.method + +=== [method] === +[NM property description] +IPv4 configuration method. If 'auto' is specified then the appropriate automatic method (DHCP, PPP, etc) is used for the interface and most other properties can be left unset. If 'link-local' is specified, then a link-local address in the 169.254/16 range will be assigned to the interface. If 'manual' is specified, static IP addressing is used and at least one IP address must be given in the 'addresses' property. If 'shared' is specified (indicating that this connection will provide network access to other computers) then the interface is assigned an address in the 10.42.x.1/24 range and a DHCP and forwarding DNS server are started, and the interface is NAT-ed to the current default network connection. 'disabled' means IPv4 will not be used on this connection. This property must be set. + +nmcli> set ipv4.method auto +nmcli> save +Saving the connection with 'autoconnect=yes'. That might result in an immediate activation of the connection. +Do you still want to save? [yes] yes +Connection 'eth0' (090b61f7-540f-4dd6-bf1f-a905831fc287) successfully saved. +nmcli> quit +~]$</screen> +The default action is to save the connection profile as persistent. If required, the profile can be held in memory only, until the next restart, by means of the <command>save temporary</command> command. +</para> + +</example> + + <bridgehead id="Adding_a_Static_Ethernet_Connection">Adding a Static Ethernet Connection</bridgehead> + <para> + To add an Ethernet connection with static <systemitem class="protocol">IPv4</systemitem> configuration, a command in the following format can be used: + <synopsis>nmcli connection add type ethernet con-name <replaceable>connection-name</replaceable> ifname <replaceable>interface-name</replaceable> ip4 <replaceable>address</replaceable> gw4 <replaceable>address</replaceable></synopsis> + <systemitem class="protocol">IPv6</systemitem> address and gateway information can be added using the <option>ip6</option> and <option>gw6</option> options.</para> + <para> + For example, a command to create a static Ethernet connection with only <systemitem class="protocol">IPv4</systemitem> address and gateway is as follows: + <screen>~]$ <command>nmcli con add type ethernet con-name <replaceable>test-lab</replaceable> ifname <replaceable>eth1</replaceable> ip4 10.10.10.10/24 \</command> +<command>gw4 10.10.10.254</command></screen> + Optionally, at the same time specify <systemitem class="protocol">IPv6</systemitem> address and gateway for the device as follows: + <screen>~]$ <command>nmcli con add type ethernet con-name <replaceable>test-lab</replaceable> ifname <replaceable>eth1</replaceable> ip4 10.10.10.10/24 \</command> +<command>gw4 10.10.10.254 ip6 abbe::cafe gw6 2001:db8::1</command> +Connection 'test-lab' (05abfd5e-324e-4461-844e-8501ba704773) successfully added.</screen> + <application>NetworkManager</application> will set its internal parameter <option>ipv4.method</option> to <literal>manual</literal> and <option>connection.autoconnect</option> to <literal>yes</literal>. <application>NetworkManager</application> will also write out settings to <filename>/etc/sysconfig/network-scripts/ifcfg-my-office</filename> where the corresponding BOOTPROTO will be set to <literal>none</literal> and ONBOOT will be set to <literal>yes</literal>.</para> + <para> + Note that manual changes to the ifcfg file will not be noticed by <application>NetworkManager</application> until the interface is next brought up. See <xref linkend="sec-Network_Configuration_Using_sysconfig_Files" /> for more information on using configuration files.</para> +<para> + To set two <systemitem class="protocol">IPv4</systemitem> <systemitem class="protocol">DNS</systemitem> server addresses: + <screen>~]$ <command>nmcli con mod <replaceable>test-lab</replaceable> ipv4.dns "8.8.8.8 8.8.4.4"</command></screen> + Note that this will replace any previously set <systemitem class="protocol">DNS</systemitem> servers.</para> + <para> + To set two <systemitem class="protocol">IPv6</systemitem> <systemitem class="protocol">DNS</systemitem> server addresses: + <screen>~]$ <command>nmcli con mod <replaceable>test-lab</replaceable> ipv6.dns "2001:4860:4860::8888 2001:4860:4860::8844"</command></screen> + Note that this will replace any previously set <systemitem class="protocol">DNS</systemitem> servers.</para> + <para> +Alternatively, to add additional <systemitem class="protocol">DNS</systemitem> servers to any previously set, use the <literal>+</literal> prefix as follows: + <screen>~]$ <command>nmcli con mod <replaceable>test-lab</replaceable> +ipv4.dns "8.8.8.8 8.8.4.4"</command></screen> + <screen>~]$ <command>nmcli con mod <replaceable>test-lab</replaceable> +ipv6.dns "2001:4860:4860::8888 2001:4860:4860::8844"</command></screen> +</para> + <para> + To bring up the new Ethernet connection, issue a command as follows: + <screen>~]$ <command>nmcli con up <replaceable>test-lab</replaceable> ifname <replaceable>eth1</replaceable></command> +Connection successfully activated (D-Bus active path: /org/freedesktop/NetworkManager/ActiveConnection/2</screen> +Review the status of the devices and connections: +<screen>~]$ <command>nmcli device status</command> +DEVICE TYPE STATE CONNECTION +eth0 ethernet connected my-office +eth1 ethernet connected test-lab +lo loopback unmanaged -- </screen></para> +<para> + To view detailed information about the newly configured connection, issue a command as follows: + <screen>~]$ <command>nmcli -p con show <replaceable>test-lab</replaceable></command> +=============================================================================== + Connection profile details (test-lab) +=============================================================================== +connection.id: test-lab +connection.uuid: 05abfd5e-324e-4461-844e-8501ba704773 +connection.interface-name: eth1 +connection.type: 802-3-ethernet +connection.autoconnect: yes +connection.timestamp: 1410428968 +connection.read-only: no +connection.permissions: +connection.zone: -- +connection.master: -- +connection.slave-type: -- +connection.secondaries: +connection.gateway-ping-timeout: 0 +<lineannotation>[output truncated]</lineannotation></screen> +The use of the <option>-p, --pretty</option> option adds a title banner and section breaks to the output.</para> + + <bridgehead id="Modifying_a_Static_Ethernet_Connection">Modifying a Static Ethernet Connection</bridgehead> + +<para> + To replace existing <systemitem class="protocol">IP</systemitem> addresses, enter a command as follows: + <screen>~]$ <command>nmcli con mod <replaceable>test-lab</replaceable> ipv4.addresses "192.168.112.112"</command></screen></para> + <para> + To add additional <systemitem class="protocol">IP</systemitem> addresses, use the <literal>+</literal> prefix as follows: + <screen>~]$ <command>nmcli con mod <replaceable>test-lab</replaceable> +ipv4.addresses "192.168.114.114"</command></screen></para> + +<example id="ex-Configuring_a_Static_Ethernet_Connection_Using_the_Interactive_Editor"> +<title>Configuring a Static Ethernet Connection Using the Interactive Editor</title> + +<para> + To configure a static Ethernet connection using the interactive editor, issue commands as follows: + <screen>~]$ <command>nmcli con edit type ethernet con-name <replaceable>eth0</replaceable></command> + +===| nmcli interactive connection editor |=== + +Adding a new '802-3-ethernet' connection + +Type 'help' or '?' for available commands. +Type 'describe [<setting>.<prop>]' for detailed property description. + +You may edit the following settings: connection, 802-3-ethernet (ethernet), 802-1x, ipv4, ipv6, dcb +nmcli> set ipv4.addresses 192.168.122.88/24 +Do you also want to set 'ipv4.method' to 'manual'? [yes]: yes +nmcli> +nmcli> save temporary +Saving the connection with 'autoconnect=yes'. That might result in an immediate activation of the connection. +Do you still want to save? [yes] no +nmcli> save +Saving the connection with 'autoconnect=yes'. That might result in an immediate activation of the connection. +Do you still want to save? [yes] yes +Connection 'eth0' (704a5666-8cbd-4d89-b5f9-fa65a3dbc916) successfully saved. +nmcli> quit +~]$</screen> +The default action is to save the connection profile as persistent. If required, the profile can be held in memory only, until the next restart, by means of the <command>save temporary</command> command. +</para> + +</example> + +<bridgehead id="Locking_a_Profile_to_a_Specific_Device">Locking a Profile to a Specific Device</bridgehead> + <para> + To lock a profile to a specific interface device, the commands used in the examples above include the interface name. For example: + <synopsis>nmcli connection add type ethernet con-name <replaceable>connection-name</replaceable> ifname <replaceable>interface-name</replaceable></synopsis> + +To make a profile usable for all compatible Ethernet interfaces, issue a command as follows: +<synopsis>nmcli connection add type ethernet con-name <replaceable>connection-name</replaceable> ifname "*"</synopsis> +Note that you have to use the <option>ifname</option> argument even if you do not want to set a specific interface. Use the wildcard character <literal>*</literal> to specify that the profile can be used with any compatible device.</para> + <para>To lock a profile to a specific MAC address, use a command in the following format: + <synopsis>nmcli connection add type ethernet con-name "<replaceable>connection-name</replaceable>" ifname "*" mac 00:00:5E:00:53:00</synopsis> + <!-- http://www.rfc-editor.org/internet-drafts/draft-eastlake-rfc5342bis-05.txt --> + </para> + + <bridgehead id="Adding_a_Wi-Fi_Connection">Adding a Wi-Fi Connection</bridgehead> + <para> + To view the available Wi-Fi access points, issue a command as follows: + <screen>~]$ <command>nmcli dev wifi list</command> + SSID MODE CHAN RATE SIGNAL BARS SECURITY + FedoraTest Infra 11 54 MB/s 98 ▂▄▆█ WPA1 + Red Hat Guest Infra 6 54 MB/s 97 ▂▄▆█ WPA2 + Red Hat Infra 6 54 MB/s 77 ▂▄▆_ WPA2 802.1X +* Red Hat Infra 40 54 MB/s 66 ▂▄▆_ WPA2 802.1X + VoIP Infra 1 54 MB/s 32 ▂▄__ WEP + MyCafe Infra 11 54 MB/s 39 ▂▄__ WPA2</screen> +</para> + <para> + To create a Wi-Fi connection profile with static <systemitem class="protocol">IP</systemitem> configuration, but allowing automatic <systemitem class="protocol">DNS</systemitem> address assignment, issue a command as follows: + <screen>~]$ <command>nmcli con add con-name <replaceable>MyCafe</replaceable> ifname wlan0 type wifi ssid MyCafe \</command> +<command>ip4 192.168.100.101/24 gw4 192.168.100.1</command></screen> + To set a WPA2 password, for example <quote>caffeine</quote>, issue commands as follows: +<screen>~]$ <command>nmcli con modify <replaceable>MyCafe</replaceable> wifi-sec.key-mgmt wpa-psk</command> +~]$ <command>nmcli con modify <replaceable>MyCafe</replaceable> wifi-sec.psk caffeine</command></screen> + </para> + <para> + To change Wi-Fi state, issue a command in the following format: + <screen>~]$ <command>nmcli radio wifi <optional>on | off </optional></command></screen> + </para> + + <bridgehead id="Changing_a_Specific_Property">Changing a Specific Property</bridgehead> + <para> + To check a specific property, for example <literal>mtu</literal>, issue a command as follows: + <screen>~]$ <command>nmcli connection show id '<replaceable>MyCafe</replaceable>' | grep mtu</command> +802-11-wireless.mtu: auto</screen> + To change the property of a setting, issue a command as follows: + <screen>~]$ <command>nmcli connection modify id '<replaceable>MyCafe</replaceable>' 802-11-wireless.mtu 1350</command></screen> + To verify the change, issue a command as follows: + <screen>~]$ <command>nmcli connection show id '<replaceable>MyCafe</replaceable>' | grep mtu</command> +802-11-wireless.mtu: 1350</screen> + </para> + <para> + Note that <application>NetworkManager</application> refers to parameters such as <literal>802-3-ethernet</literal> and <literal>802-11-wireless</literal> as the setting, and <literal>mtu</literal> as a property of the setting. See the <filename>nm-settings(5)</filename> man page for more information on properties and their settings. + </para> +</section> + +<section id="sec-Configuring_Static_Routes_Using_nmcli"> +<title>Configuring Static Routes Using nmcli</title> +<para> + Static routes can only be set per-interface, not globally, using the <application>nmcli</application> tool. The command line or the interactive editor mode can be be used. +</para> + +<example id="ex-Configuring_Static_Routes_Using_nmcli"> +<title>Configuring Static Routes Using nmcli</title> + +<para> +To configure a static route for an existing Ethernet connection using the command line, enter a command as follows: +<screen>~]# <command>nmcli connection modify eth0 +ipv4.routes 192.168.122.0/24 ipv4.gateway 10.10.10.1</command></screen> + This will direct traffic for the <systemitem class="ipaddress">192.168.122.0/24</systemitem> subnet to the gateway at <systemitem class="ipaddress">10.10.10.1</systemitem> +</para> + +</example> + +<example id="ex-Configuring_Static_Routes_Using_nmcli_Editor"> +<title>Configuring Static Routes Using nmcli Editor</title> + +<para> +To configure a static route for an Ethernet connection using the interactive editor, issue commands as follows: + <screen>~]$ <command>nmcli con edit type ethernet con-name <replaceable>eth0</replaceable></command> + +===| nmcli interactive connection editor |=== + +Adding a new '802-3-ethernet' connection + +Type 'help' or '?' for available commands. +Type 'describe [<setting>.<prop>]' for detailed property description. + +You may edit the following settings: connection, 802-3-ethernet (ethernet), 802-1x, ipv4, ipv6, dcb +nmcli> set ipv4.routes 192.168.122.0/24 10.10.10.1 +nmcli> +nmcli> save persistent +Saving the connection with 'autoconnect=yes'. That might result in an immediate activation of the connection. +Do you still want to save? [yes] yes +Connection 'eth0' (704a5666-8cbd-4d89-b5f9-fa65a3dbc916) successfully saved. +nmcli> quit +~]$</screen> +</para> + +</example> + + +</section> + + + +</section> + +<!--Topics, Reference--> + <section id="sec-Configure_Networking-additional_resources"> + +<title>Additional Resources</title> +<para> + The following sources of information provide additional resources relevant to this chapter. + </para> + <section id="sec-Configure_Networking-docs-inst"> + <title>Installed Documentation</title> + <itemizedlist> + <listitem> + <para> + <filename>ip(8)</filename> man page — Describes the <application>ip</application> utility's command syntax. + </para> + </listitem> + + <listitem> + <para> + <filename>nmcli(1)</filename> man page — Describes <application>NetworkManager</application>'s command‐line tool. + </para> + </listitem> + <listitem> + <para> + <filename>nmcli-examples(5)</filename> man page — Gives examples of <application>nmcli</application> commands. + </para> + </listitem> + <listitem> + <para> + <filename>nm-settings(5)</filename> man page — Describes <application>NetworkManager</application> properties and their settings. + </para> + </listitem> + +</itemizedlist> +</section> + +<section id="sec-Configure_Networking_Online_Documentation"> + <title>Online Documentation</title> + <para> +<variablelist> + + <varlistentry> +<term><ulink url="http://www.rfc-editor.org/info/rfc1518"><citetitle pubwork="webpage">RFC 1518</citetitle></ulink> — Classless Inter-Domain Routing (CIDR)</term> +<listitem> +<para> + Describes the CIDR Address Assignment and Aggregation Strategy, including variable-length subnetting. +</para> +</listitem> +</varlistentry> + <varlistentry> +<term><ulink url="http://www.rfc-editor.org/info/rfc1918"><citetitle pubwork="webpage">RFC 1918</citetitle></ulink> — Address Allocation for Private Internets</term> +<listitem> +<para> + Describes the range of <systemitem class="protocol">IPv4</systemitem> addresses reserved for private use. +</para> +</listitem> +</varlistentry> + + <varlistentry> +<term><ulink url="http://www.rfc-editor.org/info/rfc3330"><citetitle pubwork="webpage">RFC 3330</citetitle></ulink> — Special-Use IPv4 Addresses</term> +<listitem> +<para> + Describes the global and other specialized <systemitem class="protocol">IPv4</systemitem> address blocks that have been assigned by the Internet Assigned Numbers Authority (IANA). +</para> +</listitem> +</varlistentry> + +</variablelist> +</para> +</section> +</section> + + + </chapter> diff --git a/docs/guide/Consistent_Network_Device_Naming.xml b/docs/guide/Consistent_Network_Device_Naming.xml new file mode 100644 index 000000000..4fe6e6f8d --- /dev/null +++ b/docs/guide/Consistent_Network_Device_Naming.xml @@ -0,0 +1,528 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "Networking_Guide.ent"> +%BOOK_ENTITIES; +]> + <!-- First we have the "Topics, Concepts" section --> +<chapter id="ch-Consistent_Network_Device_Naming"> + <title>Consistent Network Device Naming</title> + <para> + &MAJOROSVER; provides methods for consistent and predictable network device naming for network interfaces. These features change the name of network interfaces on a system in order to make locating and differentiating the interfaces easier. + </para> + <para> + Traditionally, network interfaces in Linux are enumerated as <interfacename>eth[0123…]</interfacename>, but these names do not necessarily correspond to actual labels on the chassis. Modern server platforms with multiple network adapters can encounter non-deterministic and counter-intuitive naming of these interfaces. This affects both network adapters embedded on the motherboard (<firstterm>Lan-on-Motherboard</firstterm>, or <firstterm><acronym>LOM</acronym></firstterm>) and add-in (single and multiport) adapters. + </para> + <para> + In &MAJOROSVER;, <application>udev</application> supports a number of different naming schemes. The default is to assign fixed names based on firmware, topology, and location information. This has the advantage that the names are fully automatic, fully predictable, that they stay fixed even if hardware is added or removed (no re-enumeration takes place), and that broken hardware can be replaced seamlessly. The disadvantage is that they are sometimes harder to read than the <interface>eth0</interface> or <interface>wlan0</interface> names traditionally used. For example: <interface>enp5s0</interface>. + </para> + +<section id="sec-Naming_Schemes_Hierarchy"> +<title>Naming Schemes Hierarchy</title> + + <para> + By default, <systemitem class="daemon">systemd</systemitem> will name interfaces using the following policy to apply the supported naming schemes: +<itemizedlist> + <listitem> + <para> + <emphasis role="bold">Scheme 1:</emphasis> Names incorporating Firmware or BIOS provided index numbers for on-board devices (example: <literal>eno1</literal>), are applied if that information from the firmware or BIOS is applicable and available, else falling back to scheme 2. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">Scheme 2:</emphasis> Names incorporating Firmware or BIOS provided PCI Express hotplug slot index numbers (example: <literal>ens1</literal>) are applied if that information from the firmware or BIOS is applicable and available, else falling back to scheme 3. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">Scheme 3:</emphasis> Names incorporating physical location of the connector of the hardware (example: <literal>enp2s0</literal>), are applied if applicable, else falling directly back to scheme 5 in all other cases. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">Scheme 4:</emphasis> Names incorporating interface's MAC address (example: <literal>enx78e7d1ea46da</literal>), is not used by default, but is available if the user chooses. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">Scheme 5:</emphasis> The traditional unpredictable kernel naming scheme, is used if all other methods fail (example: <literal>eth0</literal>). + </para> + </listitem> +</itemizedlist> +</para> + + + <para> + This policy, the procedure outlined above, is the default. If the system has <application>biosdevname</application> enabled, it will be used. Note that enabling <application>biosdevname</application> requires passing <command>biosdevname=1</command> as a command-line parameter except in the case of a Dell system, where <application>biosdevname</application> will be used by default as long as it is installed. If the user has added <application>udev</application> rules which change the name of the kernel devices, those rules will take precedence. + </para> + + </section> + + <section id="sec-Understanding_the_Device_Renaming_Procedure"> + <title>Understanding the Device Renaming Procedure</title> +<para> + The device name procedure in detail is as follows: +</para> +<procedure> + <step> + <para> + A rule in <filename>/usr/lib/udev/rules.d/60-net.rules</filename> instructs the <application>udev</application> helper utility, <application>/lib/udev/rename_device</application>, to look into all <filename>/etc/sysconfig/network-scripts/ifcfg-<replaceable>suffix</replaceable></filename> files. If it finds an <filename>ifcfg</filename> file with a <command>HWADDR</command> entry matching the MAC address of an interface it renames the interface to the name given in the <filename>ifcfg</filename> file by the <command>DEVICE</command> directive. + </para> + </step> + <step> + <para> + A rule in <filename>/usr/lib/udev/rules.d/71-biosdevname.rules</filename> instructs <application>biosdevname</application> to rename the interface according to its naming policy, provided that it was not renamed in a previous step, <application>biosdevname</application> is installed, and <command>biosdevname=0</command> was not given as a kernel command on the boot command line. + </para> + </step> + <step> + <para> + A rule in <filename>/lib/udev/rules.d/75-net-description.rules</filename> instructs <application>udev</application> to fill in the internal <application>udev</application> device property values ID_NET_NAME_ONBOARD, ID_NET_NAME_SLOT, ID_NET_NAME_PATH, ID_NET_NAME_MAC by examining the network interface device. Note, that some device properties might be undefined. + </para> + </step> + <step> + <para> + A rule in <filename>/usr/lib/udev/rules.d/80-net-name-slot.rules</filename> instructs <application>udev</application> to rename the interface, provided that it was not renamed in step 1 or 2, and the kernel parameter <command>net.ifnames=0</command> was not given, according to the following priority: ID_NET_NAME_ONBOARD, ID_NET_NAME_SLOT, ID_NET_NAME_PATH. It falls through to the next in the list, if one is unset. If none of these are set, then the interface will not be renamed. + </para> + </step> +</procedure> + <para> + Steps 3 and 4 are implementing the naming schemes 1, 2, 3, and optionally 4, described in <xref linkend="sec-Naming_Schemes_Hierarchy" />. Step 2 is explained in more detail in <xref linkend="sec-Consistent_Network_Device_Naming_Using_biosdevname" />. + </para> + </section> + + <section id="sec-Understanding_the_Predictable_Network_Interface_Device_Names"> + <title>Understanding the Predictable Network Interface Device Names</title> + <para> + The names have two character prefixes based on the type of interface: + <orderedlist> + <listitem> + <para> + <literal>en</literal> for Ethernet, + </para> + </listitem> + <listitem> + <para> + <literal>wl</literal> for wireless LAN (WLAN), + </para> + </listitem> + <listitem> + <para> + <literal>ww</literal> for wireless wide area network (WWAN). + </para> + </listitem> + </orderedlist> + </para> + <para> + + The names have the following types: + <table id="Device_Name_Types"> + <title>Device Name Types</title> + <tgroup cols="2"> + <colspec colname="Format" colnum="1" colwidth="50*" /> + <colspec colname="Description" colnum="2" colwidth="30*" /> + <thead> + <row> + <entry>Format</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>o<<replaceable>index</replaceable>></entry> + <entry>on-board device index number</entry> + </row> + <row> + <entry>s<<replaceable>slot></replaceable>[f<<replaceable>function></replaceable>][d<<replaceable>dev_id</replaceable>>]</entry> + <entry>hotplug slot index number</entry> + </row> + <row> + <entry>x<<replaceable>MAC</replaceable>></entry> + <entry>MAC address</entry> + </row> + <row> + <entry>p<<replaceable>bus</replaceable>>s<<replaceable>slot</replaceable>>[f<<replaceable>function</replaceable>>][d<<replaceable>dev_id</replaceable>>]</entry> + <entry>PCI geographical location</entry> + </row> + <row> + <entry>p<<replaceable>bus</replaceable>>s<<replaceable>slot</replaceable>>[f<<replaceable>function</replaceable>>][u<<replaceable>port</replaceable>>][..][c<<replaceable>config</replaceable>>][i<<replaceable>interface</replaceable>>]</entry> + <entry>USB port number chain</entry> + </row> + </tbody> + </tgroup> + </table> + + <itemizedlist> + <listitem> + <para> + All multi-function PCI devices will carry the [f<<replaceable>function</replaceable>>] number in the device name, including the function 0 device. + </para> + </listitem> + <listitem> + <para> + For USB devices the full chain of port numbers of hubs is composed. If the name gets longer than the maximum number of 15 characters, the name is not exported. + </para> + </listitem> + <listitem> + <para> + The USB configuration descriptors == 1 and USB interface descriptors == 0 values are suppressed (configuration == 1 and interface == 0 are the default values if only one USB configuration or interface exists). + </para> + </listitem> + </itemizedlist> + </para> + + </section> + + <section id="sec-Naming_Scheme_for_Network_Devices_Available_for_Linux_on_System_z"> + <title>Naming Scheme for Network Devices Available for Linux on System z</title> + <para> + Use the bus-ID to create predictable device names for network interfaces in Linux on System z instances. The bus-ID identifies a device in the s390 channel subsystem. A bus ID identifies the device within the scope of a Linux instance. For a CCW device, the bus ID is the device's device number with a leading <literal>0.n</literal>, where <literal>n</literal> is the subchannel set ID. For example, <literal>0.1.0ab1</literal>. + </para> + <para> + Network interfaces of device type Ethernet are named as follows: + <synopsis>enccw<replaceable>0</replaceable>.<replaceable>0</replaceable>.<replaceable>1234</replaceable></synopsis> + </para> + <para> + CTC network devices of device type SLIP are named as follows: + <synopsis>slccw<replaceable>0</replaceable>.<replaceable>0</replaceable>.<replaceable>1234</replaceable></synopsis></para> + <para> +Use the <command>znetconf -c</command> command or the <command>lscss -a</command> command to display available network devices and their bus-IDs. + </para> + <table id="Device_Name_Types_for_Linux_on_System_z"> + <title>Device Name Types for Linux on System z</title> + <tgroup cols="2"> + <colspec colname="Format" colnum="1" colwidth="50*" /> + <colspec colname="Description" colnum="2" colwidth="30*" /> + <thead> + <row> + <entry>Format</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>enccw<replaceable>bus-ID</replaceable></entry> + <entry>device type Ethernet</entry> + </row> + <row> + <entry>slccw<replaceable>bus-ID</replaceable></entry> + <entry>CTC network devices of device type SLIP</entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section id="sec-Naming_Scheme_for_VLAN_Interfaces"> + <title>Naming Scheme for VLAN Interfaces</title> + <para> + Traditionally, VLAN interface names in the format: <replaceable>interface-name</replaceable>.<replaceable>VLAN-ID</replaceable> are used. The <literal>VLAN-ID</literal> ranges from <literal>0</literal> to <literal>4096</literal>, which is a maximum of four characters and the total interface name has a limit of 15 characters. The maximum interface name length is defined by the kernel headers and is a global limit, affecting all applications. + </para> + + <para> + In Fedora, four naming conventions for VLAN interface names are supported: + </para> +<variablelist> + + <varlistentry> + <term>VLAN plus VLAN ID <!--vlan=VLAN_PLUS_VID--></term> + <listitem> + <para> + The word <literal>vlan</literal> plus the VLAN ID. For example: vlan0005 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>VLAN plus VLAN ID without padding<!--vlan=VLAN_PLUS_VID_NO_PAD--></term> + <listitem> + <para> +The word <literal>vlan</literal> plus the VLAN ID without padding by means of additional leading zeros. For example: vlan5 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Device name plus VLAN ID<!--vlan=DEV_PLUS_VID--></term> + <listitem> + <para> +The name of the parent interface plus the VLAN ID. For example: eth0.0005 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Device name plus VLAN ID without padding<!--vlan=DEV_PLUS_VID_NO_PAD--></term> + <listitem> + <para> +The name of the parent interface plus the VLAN ID without padding by means of additional leading zeros. For example: eth0.5 + </para> + </listitem> + </varlistentry> +</variablelist> + + + </section> + + <section id="sec-Consistent_Network_Device_Naming_Using_biosdevname"> + <title>Consistent Network Device Naming Using biosdevname</title> + <para> + This feature, implemented via the <application>biosdevname</application> <application>udev</application> helper utility, will change the name of all embedded network interfaces, PCI card network interfaces, and virtual function network interfaces from the existing <interfacename>eth[0123…]</interfacename> to the new naming convention as shown in <xref linkend="tabl-Consistent_Network_Device_Naming_biosdevname" />. Note that unless the system is a Dell system, or <application>biosdevname</application> is explicitly enabled as described in <xref linkend="sec-Consistent_Network_Device_Naming-Enabling_and_Disabling" />, the <systemitem class="daemon">systemd</systemitem> naming scheme will take precedence. + </para> + <table id="tabl-Consistent_Network_Device_Naming_biosdevname"> + <title>The biosdevname Naming Convention</title> + <tgroup cols="3"> + <colspec colname="device" colnum="1" colwidth="35*" /> + <colspec colname="old" colnum="2" colwidth="15*" /> + <colspec colname="new" colnum="3" colwidth="50*" /> + <thead> + <row> + <entry> + Device + </entry> + <entry> + Old Name + </entry> + <entry> + New Name + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + Embedded network interface (LOM) + </entry> + <entry> + <interfacename>eth[0123…]</interfacename> + </entry> + <entry> + <interfacename>em[1234…]</interfacename><footnote><para>New enumeration starts at <literal>1</literal>.</para></footnote> + </entry> + </row> + <row> + <entry> + PCI card network interface + </entry> + <entry> + <interfacename>eth[0123…]</interfacename> + </entry> + <entry> + <interfacename>p<<replaceable>slot</replaceable>>p<<replaceable>ethernet port</replaceable>></interfacename><footnote><para>For example: <interfacename>p3p4</interfacename></para></footnote> + </entry> + </row> + <row> + <entry> + Virtual function + </entry> + <entry> + <interfacename>eth[0123…]</interfacename> + </entry> + <entry> + <interfacename>p<<replaceable>slot</replaceable>>p<<replaceable>ethernet port</replaceable>>_<<replaceable>virtual interface</replaceable>></interfacename><footnote><para>For example: <interfacename>p3p4_1</interfacename></para></footnote> + </entry> + </row> + </tbody> + </tgroup> + </table> + + + <section id="sec-Consistent_Network_Device_Naming-System_Requirements"> + <title>System Requirements</title> + <para> + The <application>biosdevname</application> program uses information from the system's BIOS, specifically the <emphasis>type 9</emphasis> (System Slot) and <emphasis>type 41</emphasis> (Onboard Devices Extended Information) fields contained within the SMBIOS. If the system's BIOS does not have SMBIOS version 2.6 or higher and this data, the new naming convention will not be used. Most older hardware does not support this feature because of a lack of BIOSes with the correct SMBIOS version and field information. For BIOS or SMBIOS version information, contact your hardware vendor. + </para> + <para> + For this feature to take effect, the <package>biosdevname</package> package must also be installed. To install it, issue the following command as <systemitem class="username">root</systemitem>: + <screen>~]# <command>dnf install biosdevname</command></screen> + </para> + </section> + <section id="sec-Consistent_Network_Device_Naming-Enabling_and_Disabling"> + <title>Enabling and Disabling the Feature</title> + <para> + To disable this feature, pass the following option on the boot command line, both during and after installation: + </para> + <screen><option>biosdevname=0</option></screen> + <para> + To enable this feature, pass the following option on the boot command line, both during and after installation: + </para> + <screen><option>biosdevname=1</option></screen> + <para> + Unless the system meets the minimum requirements, this option will be ignored and the system will use the <systemitem class="daemon">systemd</systemitem> naming scheme as described in the beginning of the chapter. + </para> + <para> + If the <option>biosdevname</option> install option is specified, it must remain as a boot option for the lifetime of the system. + </para> + </section> + +</section> + + <section id="sec-Consistent_Network_Device_Naming-Notes"> + <title>Notes for Administrators</title> + <para> + Many system customization files can include network interface names, and thus will require updates if moving a system from the old convention to the new convention. If you use the new naming convention, you will also need to update network interface names in areas such as custom <application>iptables</application> rules, scripts altering <systemitem class="daemon">irqbalance</systemitem>, and other similar configuration files. Also, enabling this change for installation will require modification to existing <application>kickstart</application> files that use device names via the <option>ksdevice</option> parameter; these <application>kickstart</application> files will need to be updated to use the network device's MAC address or the network device's new name. + </para> + <note> + <para> + The maximum interface name length is defined by the kernel headers and is a global limit, affecting all applications. + </para> + </note> + </section> + + + + <section id="sec-Controlling_the_Selection_of_Network_Device_Names"> + <title>Controlling the Selection of Network Device Names</title> + <para> + Device naming can be controlled in the following manner:</para> +<variablelist> +<varlistentry> +<term>By identifying the network interface device</term> +<listitem> + <para> + Setting the MAC address in an <filename>ifcfg</filename> file using the <command>HWADDR</command> directive enables it to be identified by <application>udev</application>. The name will be taken from the string given by the <command>DEVICE</command> directive, which by convention is the same as the <filename>ifcfg</filename> suffix. For example, <filename>ifcfg</filename>-<replaceable>eth0</replaceable>. + </para> +</listitem> +</varlistentry> +<varlistentry> +<term>By turning on or off <application>biosdevname</application></term> +<listitem> + <para> +The name provided by <application>biosdevname</application> will be used (if <application>biosdevname</application> can determine one). + </para> +</listitem> +</varlistentry> +<varlistentry> +<term>By turning on or off the <systemitem class="daemon">systemd-udev</systemitem> naming scheme</term> +<listitem> + <para> +The name provided by <systemitem class="daemon">systemd-udev</systemitem> will be used (if <systemitem class="daemon">systemd-udev</systemitem> can determine one).</para> +</listitem> +</varlistentry> +</variablelist> + </section> + + + +<!-- "Topics, Tasks" section --> + <section id="sec-Disabling_Consistent_Network_Device_Naming"> + <title>Disabling Consistent Network Device Naming</title> + + <para> + To disable consistent network device naming, choose from one of the following: + <itemizedlist> + <listitem> + <para> + Disable the assignment of fixed names, so that the unpredictable kernel names are used again, by masking <application>udev</application>'s rule file for the default policy. This <quote>masking</quote> can be done by making a symbolic link to <filename>/dev/null</filename>. As <systemitem class="username">root</systemitem>, issue a command as follows: + <screen>~]# <command>ln -s /dev/null /etc/udev/rules.d/80-net-name-slot.rules</command></screen> + </para> + </listitem> + <listitem> + <para> + Create your own manual naming scheme, for example by naming your interfaces <quote>internet0</quote>, <quote>dmz0</quote> or <quote>lan0</quote>. To do that create your own <application>udev</application> rules file and set the NAME property for the devices. Make sure to order it before the default policy file, for example by naming it <filename>/etc/udev/rules.d/70-my-net-names.rules</filename>. + </para> + </listitem> + <listitem> + <para> + Alter the default policy file to pick a different naming scheme, for example to name all interfaces after their MAC address by default. As <systemitem class="username">root</systemitem> copy the default policy file as follows: + <screen>~]# <command>cp /usr/lib/udev/rules.d/80-net-name-slot.rules /etc/udev/rules.d/80-net-name-slot.rules</command></screen> + Edit the file in the <filename class="directory">/etc/udev/rules.d/</filename> directory and change the lines as necessary. + </para> + </listitem> + <listitem> + <para> + Append the following directive to the kernel command line in the GRUB 2 menu: + <synopsis>net.ifnames=0</synopsis> + To update all the GRUB 2 kernel menu entries, enter a command as <systemitem class="username">root</systemitem> as follows: + <screen>~]# <command>grubby --update-kernel=ALL --args=net.ifnames=0</command></screen> + For more information about working with GRUB 2 see the <citetitle pubwork="book">&MAJOROSVER; System Administrator's Guide</citetitle>. + </para> + </listitem> + </itemizedlist> +</para> + + </section> + + <section id="sec_Troubleshooting_Network_Device_Naming"> + <title>Troubleshooting Network Device Naming</title> + + <para> + Predictable interface names will be assigned for each interface, if applicable, as per the procedure described in <xref linkend="sec-Understanding_the_Device_Renaming_Procedure" />. To view the list of possible names <application>udev</application> will use, issue a command in the following form as <systemitem class="username">root</systemitem>: + <screen>~]# <command>udevadm info /sys/class/net/<replaceable>ifname</replaceable> | grep ID_NET_NAME</command></screen> + where <replaceable>ifname</replaceable> is one of the interfaces listed by the following command: + <screen>~]$ <command>ls /sys/class/net/</command></screen> + </para> + <para> + One of the possible names will be applied by <application>udev</application> according to the rules as described in <xref linkend="sec-Understanding_the_Device_Renaming_Procedure" />, and summarized here: + <itemizedlist> + <listitem> + <para> + <filename>/usr/lib/udev/rules.d/60-net.rules</filename> - from initscripts, + </para> + </listitem> + <listitem> + <para> + <filename>/usr/lib/udev/rules.d/71-biosdevname.rules</filename> - from <application>biosdevname</application>, + </para> + </listitem> + <listitem> + <para> + <filename>/usr/lib/udev/rules.d/80-net-name-slot.rules</filename> - from <systemitem class="daemon">systemd</systemitem> + </para> + </listitem> + </itemizedlist> + </para> + <para> + From the above list of rule files it can be seen that if interface naming is done via initscripts or <application>biosdevname</application> it always takes precedence over <application>udev</application> native naming. However if initscripts renaming is not taking place and <application>biosdevname</application> is disabled, then to alter the interface names copy the <filename>80-net-name-slot.rules</filename> from <filename class="directory">/usr/</filename> to <filename class="directory">/etc/</filename> and edit the file appropriately. In other words, comment out or arrange schemes to be used in a certain order. + </para> + + <example id="ex-Some_interfaces_have_names_from_the_kernel_namespace_while_others_are_successfully_renamed_by_udev"> + <title>Some interfaces have names from the kernel namespace (eth[0,1,2...]) while others are successfully renamed by udev</title> + <para> + Mixed up schemes most likely means that either for some hardware there is no usable information provided by the kernel to <application>udev</application>, thus it could not figure out any names, or the information provided to <application>udev</application> is not suitable, for example non-unique device IDs. The latter is more common and the solution is to use a custom naming scheme in ifcfg files or alter which <application>udev</application> scheme is in use by editing 80-net-name-slot.rules. + </para> + + </example> + + <example id="ex-In_var-log-messages_or_the_systemd_journal_renaming_is_seen_to_be_done_twice_for_each_interface"> + <title>In /var/log/messages or the systemd journal, renaming is seen to be done twice for each interface</title> + <para> + Systems with the naming scheme encoded in ifcfg files but which do not have a regenerated <systemitem class="filesystem">initrd</systemitem> image are likely to encounter this issue. The interface name is initially assigned (via <application>biosdevname</application> or <application>udev</application> or dracut parameters on the kernel command line) during early-boot while still in <systemitem class="filesystem">initrd</systemitem>. Then after switching to real <systemitem class="filesystem">rootfs</systemitem>, renaming is done a second time and a new interface name is determined by the <filename>/usr/lib/udev/rename_device</filename> binary spawned by <application>udev</application> because of processing 60-net.rules. You can safely ignore such messages. + </para> + </example> + + <example id="ex-Using_naming_scheme_in_ifcfg_files_with_ethX_names_does_not_work"> + <title>Using naming scheme in ifcfg files with ethX names does not work</title> + <para> + Use of interface names from kernel namespace is discouraged. To get predictable and stable interface names please use some other prefix than "eth". + </para> + </example> + </section> + + <!--Topics, Reference--> + <section id="sec-Consistent_Network_Device_Naming-additional_resources"> + +<title>Additional Resources</title> +<para> + The following sources of information provide additional resources regarding Network Teaming. + </para> + <section id="sec-Consistent_Network_Device_Naming-docs-inst"> + <title>Installed Documentation</title> + <itemizedlist> + <listitem> + <para> + <filename>udev(7)</filename> man page — Describes the Linux dynamic device management daemon, <systemitem class="daemon">udevd</systemitem>. + </para> + </listitem> + <listitem> + <para> + <filename>systemd(1)</filename> man page — Describes <systemitem class="daemon">systemd</systemitem> system and service manager. + </para> + </listitem> + <listitem> + <para> + <filename>biosdevname(1)</filename> man page — Describes the utility for obtaining the BIOS-given name of a device. + </para> + </listitem> +</itemizedlist> +</section> + + +</section> + +</chapter> diff --git a/docs/guide/DHCP_Servers.xml b/docs/guide/DHCP_Servers.xml new file mode 100644 index 000000000..e01a3ec61 --- /dev/null +++ b/docs/guide/DHCP_Servers.xml @@ -0,0 +1,605 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "Networking_Guide.ent"> +%BOOK_ENTITIES; +]> +<chapter id="ch-DHCP_Servers"> + <title>DHCP Servers</title> + <indexterm> + <primary>DHCP</primary> + </indexterm> + <indexterm> + <primary>Dynamic Host Configuration Protocol</primary> + <see>DHCP</see> + </indexterm> + <para>Dynamic Host Configuration Protocol (<acronym>DHCP</acronym>) is a network protocol that automatically assigns TCP/IP information to client machines. Each <systemitem class="protocol">DHCP</systemitem> client connects to the centrally located <systemitem class="protocol">DHCP</systemitem> server, which returns the network configuration (including the <systemitem class="protocol">IP</systemitem> address, gateway, and <systemitem class="protocol">DNS</systemitem> servers) of that client.</para> + <section + id="sec-dhcp-why"> + <title>Why Use DHCP?</title> + <indexterm> + <primary>DHCP</primary> + <secondary>reasons for using</secondary> + </indexterm> + <para><systemitem class="protocol">DHCP</systemitem> is useful for automatic configuration of client network interfaces. When configuring the client system, you can choose <systemitem class="protocol">DHCP</systemitem> instead of specifying an <systemitem class="protocol">IP</systemitem> address, netmask, gateway, or <systemitem class="protocol">DNS</systemitem> servers. The client retrieves this information from the <systemitem class="protocol">DHCP</systemitem> server. <systemitem class="protocol">DHCP</systemitem> is also useful if you want to change the <systemitem class="protocol">IP</systemitem> addresses of a large number of systems. Instead of reconfiguring all the systems, you can just edit one configuration file on the server for the new set of <systemitem class="protocol">IP</systemitem> addresses. If the <systemitem class="protocol">DNS</systemitem> servers for an organization changes, the changes happen on the <systemitem class="protocol">DHCP</systemitem> server, not on the <systemitem class="protocol">DHCP</systemitem> clients. When you restart the network or reboot the clients, the changes go into effect.</para> + <para>If an organization has a functional <systemitem class="protocol">DHCP</systemitem> server correctly connected to a network, laptops and other mobile computer users can move these devices from office to office.</para> + <para> + Note that administrators of <systemitem class="protocol">DNS</systemitem> and <systemitem class="protocol">DHCP</systemitem> servers, as well as any provisioning applications, should agree on the host name format used in an organization. See <xref linkend="sec-Recommended_Naming_Practices" /> for more information on the format of host names. +</para> + + </section> + <section + id="sec-dhcp-configuring-server"> + <title>Configuring a DHCP Server</title> + <indexterm> + <primary>DHCP</primary> + <secondary>server configuration</secondary> + </indexterm> + + <para>The <package>dhcp</package> package contains an <firstterm>Internet Systems Consortium</firstterm> (<acronym>ISC</acronym>) <systemitem class="protocol">DHCP</systemitem> server. Install the package as <systemitem class="username">root</systemitem>:</para> + <screen>~]# <command>dnf install dhcp</command> + </screen> + <para>Installing the <package>dhcp</package> package creates a file, <filename>/etc/dhcp/dhcpd.conf</filename>, which is merely an empty configuration file. As <systemitem class="username">root</systemitem>, issue the following command:</para> + <programlisting>~]# <command>cat /etc/dhcp/dhcpd.conf</command> +# +# DHCP Server Configuration file. +# see /usr/share/doc/dhcp/dhcpd.conf.example +# see dhcpd.conf(5) man page +#</programlisting> + <para>The example configuration file can be found at <filename>/usr/share/doc/dhcp/dhcpd.conf.example</filename>. You should use this file to help you configure <filename>/etc/dhcp/dhcpd.conf</filename>, which is explained in detail below.</para> + <para><systemitem class="protocol">DHCP</systemitem> also uses the file <filename>/var/lib/dhcpd/dhcpd.leases</filename> to store the client lease database. Refer to <xref + linkend="lease-database"/> for more information.</para> + <section + id="config-file"> + <title>Configuration File</title> + <indexterm> + <primary>DHCP</primary> + <secondary>dhcpd.conf</secondary> + </indexterm> + <indexterm> + <primary>dhcpd.conf</primary> + </indexterm> + <para>The first step in configuring a <systemitem class="protocol">DHCP</systemitem> server is to create the configuration file that stores the network information for the clients. Use this file to declare options for client systems.</para> + <para>The configuration file can contain extra tabs or blank lines for easier formatting. Keywords are case-insensitive and lines beginning with a hash sign (<literal>#</literal>) are considered comments.</para> + <para>There are two types of statements in the configuration file:</para> + <itemizedlist> + <listitem> + <para>Parameters — State how to perform a task, whether to perform a task, or what network configuration options to send to the client.</para> + </listitem> + <listitem> + <para>Declarations — Describe the topology of the network, describe the clients, provide addresses for the clients, or apply a group of parameters to a group of declarations.</para> + </listitem> + </itemizedlist> + <indexterm> + <primary>DHCP</primary> + <secondary>options</secondary> + </indexterm> + <para>The parameters that start with the keyword option are referred to as <firstterm>options</firstterm>. These options control <systemitem class="protocol">DHCP</systemitem> options; whereas, parameters configure values that are not optional or control how the <systemitem class="protocol">DHCP</systemitem> server behaves.</para> + <indexterm> + <primary>DHCP</primary> + <secondary>global parameters</secondary> + </indexterm> + <para>Parameters (including options) declared before a section enclosed in curly brackets (<literal>{ }</literal>) are considered global parameters. Global parameters apply to all the sections below it.</para> + <important> + <title>Restart the DHCP Daemon for the Changes to Take Effect</title> + <para>If the configuration file is changed, the changes do not take effect until the <systemitem class="protocol">DHCP</systemitem> daemon is restarted with the command <command>systemctl restart dhcpd</command>.</para> + </important> + <note> + <title>Use the omshell Command</title> + <para>Instead of changing a <systemitem class="protocol">DHCP</systemitem> configuration file and restarting the service each time, using the <command>omshell</command> command provides an interactive way to connect to, query, and change the configuration of a <systemitem class="protocol">DHCP</systemitem> server. By using <command>omshell</command>, all changes can be made while the server is running. For more information on <command>omshell</command>, see the <command>omshell</command> man page.</para> + </note> + <para>In <xref + linkend="subnet"/>, the <command>routers</command>, <command>subnet-mask</command>, <command>domain-search</command>, <command>domain-name-servers</command>, and <command>time-offset</command> options are used for any <command>host</command> statements declared below it.</para> + <indexterm> + <primary>DHCP</primary> + <secondary>subnet</secondary> + </indexterm> + <para>For every subnet which will be served, and for every subnet to which the <systemitem class="protocol">DHCP</systemitem> server is connected, there must be one <command>subnet</command> declaration, which tells the <systemitem class="protocol">DHCP</systemitem> daemon how to recognize that an address is on that subnet. A <command>subnet</command> declaration is required for each subnet even if no addresses will be dynamically allocated to that subnet.</para> + <para>In this example, there are global options for every <systemitem class="protocol">DHCP</systemitem> client in the subnet and a <command>range</command> declared. Clients are assigned an <systemitem class="protocol">IP</systemitem> address within the <command>range</command>.</para> + <example + id="subnet"> + <title>Subnet Declaration</title> + <programlisting>subnet 192.168.1.0 netmask 255.255.255.0 { + option routers 192.168.1.254; + option subnet-mask 255.255.255.0; + option domain-search "example.com"; + option domain-name-servers 192.168.1.1; + option time-offset -18000; # Eastern Standard Time + range 192.168.1.10 192.168.1.100; +}</programlisting> + </example> + <para>To configure a <systemitem class="protocol">DHCP</systemitem> server that leases a dynamic <systemitem class="protocol">IP</systemitem> address to a system within a subnet, modify the example values from <xref linkend="dynamic-ip"/>. It declares a default lease time, maximum lease time, and network configuration values for the clients. This example assigns <systemitem class="protocol">IP</systemitem> addresses in the <command>range</command> <systemitem class="ipaddress">192.168.1.10</systemitem> and <systemitem class="ipaddress">192.168.1.100</systemitem> to client systems.</para> + <example + id="dynamic-ip"> + <title>Range Parameter</title> + <programlisting>default-lease-time 600; +max-lease-time 7200; +option subnet-mask 255.255.255.0; +option broadcast-address 192.168.1.255; +option routers 192.168.1.254; +option domain-name-servers 192.168.1.1, 192.168.1.2; +option domain-search "example.com"; +subnet 192.168.1.0 netmask 255.255.255.0 { + range 192.168.1.10 192.168.1.100; +}</programlisting> + </example> + <para>To assign an <systemitem class="protocol">IP</systemitem> address to a client based on the MAC address of the network interface card, use the <command>hardware ethernet</command> parameter within a <command>host</command> declaration. As demonstrated in <xref + linkend="static-ip"/>, the <command>host apex</command> declaration specifies that the network interface card with the MAC address <systemitem class="etheraddress">00:A0:78:8E:9E:AA</systemitem> always receives the <systemitem class="protocol">IP</systemitem> address <systemitem class="ipaddress">192.168.1.4</systemitem>.</para> + <para>Note that you can also use the optional parameter <option>host-name</option> to assign a host name to the client.</para> + <example + id="static-ip"> + <title>Static IP Address Using DHCP</title> + <programlisting>host apex { + option host-name "apex.example.com"; + hardware ethernet 00:A0:78:8E:9E:AA; + fixed-address 192.168.1.4; +}</programlisting> + </example> + <indexterm> + <primary>DHCP</primary> + <secondary><command>shared-network</command></secondary> + </indexterm> + <para>All subnets that share the same physical network should be declared within a <command>shared-network</command> declaration as shown in <xref + linkend="shared-network"/>. Parameters within the <command>shared-network</command>, but outside the enclosed subnet declarations, are considered to be global parameters. The name assigned to <command>shared-network</command> must be a descriptive title for the network, such as using the title <quote>test-lab</quote> to describe all the subnets in a test lab environment.</para> + <example + id="shared-network"> + <title>Shared-network Declaration</title> + <programlisting>shared-network name { + option domain-search "test.redhat.com"; + option domain-name-servers ns1.redhat.com, ns2.redhat.com; + option routers 192.168.0.254; + #more parameters for EXAMPLE shared-network + subnet 192.168.1.0 netmask 255.255.252.0 { + #parameters for subnet + range 192.168.1.1 192.168.1.254; + } + subnet 192.168.2.0 netmask 255.255.252.0 { + #parameters for subnet + range 192.168.2.1 192.168.2.254; + } +}</programlisting> + </example> + <indexterm> + <primary>DHCP</primary> + <secondary>group</secondary> + </indexterm> + <para>As demonstrated in <xref + linkend="group"/>, the <command>group</command> declaration is used to apply global parameters to a group of declarations. For example, shared networks, subnets, and hosts can be grouped.</para> + <example + id="group"> + <title>Group Declaration</title> + <programlisting>group { + option routers 192.168.1.254; + option subnet-mask 255.255.255.0; + option domain-search "example.com"; + option domain-name-servers 192.168.1.1; + option time-offset -18000; # Eastern Standard Time + host apex { + option host-name "apex.example.com"; + hardware ethernet 00:A0:78:8E:9E:AA; + fixed-address 192.168.1.4; + } + host raleigh { + option host-name "raleigh.example.com"; + hardware ethernet 00:A1:DD:74:C3:F2; + fixed-address 192.168.1.6; + } +}</programlisting> + </example> + <note> + <title>Using the Example Configuration File</title> + <para>You can use the provided example configuration file as a starting point and add custom configuration options to it. To copy this file to the proper location, use the following command as <systemitem class="username">root</systemitem>:</para> + <screen>~]# <command>cp /usr/share/doc/dhcp-<replaceable>version_number</replaceable>/dhcpd.conf.example /etc/dhcp/dhcpd.conf</command></screen> + <para>... where <replaceable>version_number</replaceable> is the <systemitem class="protocol">DHCP</systemitem> version number.</para> + </note> + <para>For a complete list of option statements and what they do, see the <filename>dhcp-options(5)</filename> man page.</para> + </section> + <section + id="lease-database"> + <title>Lease Database</title> + <para>On the <systemitem class="protocol">DHCP</systemitem> server, the file <filename>/var/lib/dhcpd/dhcpd.leases</filename> stores the <systemitem class="protocol">DHCP</systemitem> client lease database. Do not change this file. <systemitem class="protocol">DHCP</systemitem> lease information for each recently assigned <systemitem class="protocol">IP</systemitem> address is automatically stored in the lease database. The information includes the length of the lease, to whom the <systemitem class="protocol">IP</systemitem> address has been assigned, the start and end dates for the lease, and the MAC address of the network interface card that was used to retrieve the lease.</para> + <para>All times in the lease database are in Coordinated Universal Time (UTC), not local time.</para> + <para>The lease database is recreated from time to time so that it is not too large. First, all known leases are saved in a temporary lease database. The <filename>dhcpd.leases</filename> file is renamed <filename>dhcpd.leases~</filename> and the temporary lease database is written to <filename>dhcpd.leases</filename>.</para> + <para>The <systemitem class="protocol">DHCP</systemitem> daemon could be killed or the system could crash after the lease database has been renamed to the backup file but before the new file has been written. If this happens, the <filename>dhcpd.leases</filename> file does not exist, but it is required to start the service. Do not create a new lease file. If you do, all old leases are lost which causes many problems. The correct solution is to rename the <filename>dhcpd.leases~</filename> backup file to <filename>dhcpd.leases</filename> and then start the daemon.</para> + </section> + <section> + <title>Starting and Stopping the Server</title> + <indexterm> + <primary>DHCP</primary> + <secondary>starting the server</secondary> + </indexterm> + <indexterm> + <primary>DHCP</primary> + <secondary>stopping the server</secondary> + </indexterm> + <indexterm> + <primary>DHCP</primary> + <secondary><filename>dhcpd.leases</filename></secondary> + </indexterm> + <indexterm> + <primary>dhcpd.leases</primary> + </indexterm> + <important> + <title>Starting the DHCP Server for the First Time</title> + <para>When the <systemitem class="protocol">DHCP</systemitem> server is started for the first time, it fails unless the <filename>dhcpd.leases</filename> file exists. You can use the command <command>touch /var/lib/dhcpd/dhcpd.leases</command> to create the file if it does not exist. If the same server is also running BIND as a <systemitem class="protocol">DNS</systemitem> server, this step is not necessary, as starting the <command>named</command> service automatically checks for a <filename>dhcpd.leases</filename> file.</para> + <para> + Do not create a new lease file on a system that was previously running. If you do, all old leases are lost which causes many problems. The correct solution is to rename the <filename>dhcpd.leases~</filename> backup file to <filename>dhcpd.leases</filename> and then start the daemon. + </para> + </important> + <para>To start the <systemitem class="protocol">DHCP</systemitem> service, use the following command:</para> + <screen><command>systemctl start dhcpd.service</command></screen> + <para>To stop the <systemitem class="protocol">DHCP</systemitem> server, type:</para> + <screen><command>systemctl stop dhcpd.service</command></screen> + <para>By default, the <systemitem class="protocol">DHCP</systemitem> service does not start at boot time. To configure the daemon to start automatically at boot time, run:</para> + <screen><command>systemctl enable dhcpd.service</command></screen> + <para> + <!-- Refer to <xref linkend="ch-Services_and_Daemons" /> for more information on how to configure services in &MAJOROS;.--> + </para> + <indexterm> + <primary> + <filename>/etc/sysconfig/dhcpd</filename> + </primary> + </indexterm> + <indexterm> + <primary>DHCP</primary> + <secondary>command-line options</secondary> + </indexterm> + <para>If more than one network interface is attached to the system, but the <systemitem class="protocol">DHCP</systemitem> server should only listen for <systemitem class="protocol">DHCP</systemitem> requests on one of the interfaces, configure the <systemitem class="protocol">DHCP</systemitem> server to listen only on that device. The <systemitem class="protocol">DHCP</systemitem> daemon will only listen on interfaces for which it finds a subnet declaration in the <filename>/etc/dhcp/dhcpd.conf</filename> file.</para> + <para>This is useful for a firewall machine with two network cards. One network card can be configured as a <systemitem class="protocol">DHCP</systemitem> client to retrieve an <systemitem class="protocol">IP</systemitem> address to the Internet. The other network card can be used as a <systemitem class="protocol">DHCP</systemitem> server for the internal network behind the firewall. Specifying only the network card connected to the internal network makes the system more secure because users can not connect to the daemon via the Internet.</para> + <para> + To specify command-line options, copy and then edit the <filename>dhcpd.service</filename> file as the <systemitem class="username">root</systemitem> user. For example, as follows: + <screen>~]# <command>cp /usr/lib/systemd/system/dhcpd.service /etc/systemd/system/</command> +~]# <command>vi /etc/systemd/system/dhcpd.service</command></screen> +Edit the line under section [Service]: +<synopsis>ExecStart=/usr/sbin/dhcpd -f -cf /etc/dhcp/dhcpd.conf -user dhcpd -group dhcpd --no-pid <replaceable>your_interface_name(s)</replaceable></synopsis> +Then, as the <systemitem class="username">root</systemitem> user, restart the service: +<screen>~]# <command>systemctl --system daemon-reload</command> +~]# <command>systemctl restart dhcpd</command></screen> + </para> + <para>Command line options can be appended to <command>ExecStart=/usr/sbin/dhcpd</command> in the <filename>/etc/systemd/system/dhcpd.service</filename> unit file under section [Service]. They include:</para> + <itemizedlist> + <listitem> + <para> + <command>-p <replaceable>portnum</replaceable></command> — Specifies the UDP port number on which <command>dhcpd</command> should listen. The default is port 67. The <systemitem class="protocol">DHCP</systemitem> server transmits responses to the <systemitem class="protocol">DHCP</systemitem> clients at a port number one greater than the UDP port specified. For example, if the default port 67 is used, the server listens on port 67 for requests and responds to the client on port 68. If a port is specified here and the <systemitem class="protocol">DHCP</systemitem> relay agent is used, the same port on which the <systemitem class="protocol">DHCP</systemitem> relay agent should listen must be specified. See <xref linkend="dhcp-relay-agent" /> for details.</para> + </listitem> + <listitem> + <para> + <command>-f</command> — Runs the daemon as a foreground process. This is mostly used for debugging.</para> + </listitem> + <listitem> + <para> + <command>-d</command> — Logs the <systemitem class="protocol">DHCP</systemitem> server daemon to the standard error descriptor. This is mostly used for debugging. If this is not specified, the log is written to <filename>/var/log/messages</filename>.</para> + </listitem> + <listitem> + <para> + <command>-cf <replaceable>filename</replaceable> + </command> — Specifies the location of the configuration file. The default location is <filename>/etc/dhcp/dhcpd.conf</filename>.</para> + </listitem> + <listitem> + <para> + <command>-lf <replaceable>filename</replaceable> + </command> — Specifies the location of the lease database file. If a lease database file already exists, it is very important that the same file be used every time the <systemitem class="protocol">DHCP</systemitem> server is started. It is strongly recommended that this option only be used for debugging purposes on non-production machines. The default location is <filename>/var/lib/dhcpd/dhcpd.leases</filename>.</para> + </listitem> + <listitem> + <para> + <command>-q</command> — Do not print the entire copyright message when starting the daemon.</para> + </listitem> + </itemizedlist> + </section> + </section> + <section + id="dhcp-relay-agent"> + <title>DHCP Relay Agent</title> + <indexterm> + <primary>DHCP</primary> + <secondary>Relay Agent</secondary> + </indexterm> + <indexterm> + <primary>DHCP</primary> + <secondary>dhcrelay</secondary> + </indexterm> + <indexterm> + <primary>dhcrelay</primary> + </indexterm> + <para> + The DHCP Relay Agent (<application>dhcrelay</application>) enables the relay of <systemitem class="protocol">DHCP</systemitem> and <systemitem class="protocol">BOOTP</systemitem> requests from a subnet with no <systemitem class="protocol">DHCP</systemitem> server on it to one or more <systemitem class="protocol">DHCP</systemitem> servers on other subnets. + </para> + + <para> + When a <systemitem class="protocol">DHCP</systemitem> client requests information, the DHCP Relay Agent forwards the request to the list of <systemitem class="protocol">DHCP</systemitem> servers specified when the DHCP Relay Agent is started. When a <systemitem class="protocol">DHCP</systemitem> server returns a reply, the reply is broadcast or unicast on the network that sent the original request. + </para> + + <para>The DHCP Relay Agent for <systemitem class="protocol">IPv4</systemitem>, <application>dhcrelay</application>, listens for <systemitem class="protocol">DHCPv4</systemitem> and <systemitem class="protocol">BOOTP</systemitem> requests on all interfaces unless the interfaces are specified in <filename>/etc/sysconfig/dhcrelay</filename> with the <computeroutput>INTERFACES</computeroutput> directive. See <xref linkend="sec-Configure_dhcrelay_as_a_DHCPv4_and_BOOTP_relay_agent" />. The DHCP Relay Agent for <systemitem class="protocol">IPv6</systemitem>, <application>dhcrelay6</application>, does not have this default behavior and interfaces to listen for <systemitem class="protocol">DHCPv6</systemitem> requests must be specified. See <xref linkend="sec-Configure_dhcrelay_as_a_DHCPv6_relay_agent" />.</para> + + <para> + <application>dhcrelay</application> can either be run as a <systemitem class="protocol">DHCPv4</systemitem> and <systemitem class="protocol">BOOTP</systemitem> relay agent (by default) or as a <systemitem class="protocol">DHCPv6</systemitem> relay agent (with <option>-6</option> argument). To see the usage message, issue the command <command>dhcrelay -h</command>. + </para> + +<section id="sec-Configure_dhcrelay_as_a_DHCPv4_and_BOOTP_relay_agent"> + <title>Configure dhcrelay as a DHCPv4 and BOOTP relay agent</title> +<para> + To run <application>dhcrelay</application> in <systemitem class="protocol">DHCPv4</systemitem> and <systemitem class="protocol">BOOTP</systemitem> mode specify the servers to which the requests should be forwarded to. +Copy and then edit the <filename>dhcrelay.service</filename> file as the <systemitem class="username">root</systemitem> user: +<screen>~]# <command>cp /lib/systemd/system/dhcrelay.service /etc/systemd/system/</command> +~]# <command>vi /etc/systemd/system/dhcrelay.service</command></screen> +</para> +<para> +Edit the <option>ExecStart</option> option under section [Service] and add one or more server <systemitem class="protocol">IPv4</systemitem> addresses to the end of the line, for example: +<synopsis>ExecStart=/usr/sbin/dhcrelay -d --no-pid 192.168.1.1</synopsis> +</para> +<para> +If you also want to specify interfaces where the DHCP Relay Agent listens for <systemitem class="protocol">DHCP</systemitem> requests, add them to the <option>ExecStart</option> option with <option>-i</option> argument (otherwise it will listen on all interfaces), for example: +<synopsis>ExecStart=/usr/sbin/dhcrelay -d --no-pid 192.168.1.1 -i em1</synopsis> +For other options see the <filename>dhcrelay(8)</filename> man page. +</para> + <para> +To activate the changes made, as the <systemitem class="username">root</systemitem> user, restart the service: +<screen>~]# <command>systemctl --system daemon-reload</command> +~]# <command>systemctl restart dhcrelay</command></screen> +</para> + </section> + <section id="sec-Configure_dhcrelay_as_a_DHCPv6_relay_agent"> + <title>Configure dhcrelay as a DHCPv6 relay agent</title> +<para> + To run <application>dhcrelay</application> in <systemitem class="protocol">DHCPv6</systemitem> mode add the <option>-6</option> argument and specify the <quote>lower interface</quote> (on which queries will be received from clients or from other relay agents) and the <quote>upper interface</quote> (to which queries from clients and other relay agents should be forwarded). + +Copy <filename>dhcrelay.service</filename> to <filename>dhcrelay6.service</filename> and edit it as the <systemitem class="username">root</systemitem> user: +<screen>~]# <command>cp /lib/systemd/system/dhcrelay.service /etc/systemd/system/dhcrelay6.service</command> +~]# <command>vi /etc/systemd/system/dhcrelay6.service</command></screen> +</para> +<para> +Edit the <option>ExecStart</option> option under section [Service] add <option>-6</option> argument and add the <quote>lower interface</quote> and <quote>upper interface</quote> interface, for example: +<synopsis>ExecStart=/usr/sbin/dhcrelay -d --no-pid -6 -l em1 -u em2</synopsis> +For other options see the <filename>dhcrelay(8)</filename> man page. +</para> + <para> +To activate the changes made, as the <systemitem class="username">root</systemitem> user, restart the service: +<screen>~]# <command>systemctl --system daemon-reload</command> +~]# <command>systemctl restart dhcrelay6</command></screen> +</para> + </section> + </section> + + <section + id="sec-Configuring_a_Multihomed_DHCP_Server"> + <title>Configuring a Multihomed DHCP Server</title> + <indexterm> + <primary>Multihomed DHCP</primary> + <secondary>server configuration</secondary> + </indexterm> + <para>A multihomed <systemitem class="protocol">DHCP</systemitem> server serves multiple networks, that is, multiple subnets. The examples in these sections detail how to configure a <systemitem class="protocol">DHCP</systemitem> server to serve multiple networks, select which network interfaces to listen on, and how to define network settings for systems that move networks.</para> + <para>Before making any changes, back up the existing <filename>/etc/dhcp/dhcpd.conf</filename> file.</para> + <para>The <systemitem class="protocol">DHCP</systemitem> daemon will only listen on interfaces for which it finds a subnet declaration in the <filename>/etc/dhcp/dhcpd.conf</filename> file.</para> + <para>The following is a basic <filename>/etc/dhcp/dhcpd.conf</filename> file, for a server that has two network interfaces, <interface>eth0</interface> in a <systemitem class="ipaddress">10.0.0.0/24</systemitem> network, and <interface>eth1</interface> in a <systemitem class="ipaddress">172.16.0.0/24</systemitem> network. Multiple <computeroutput>subnet</computeroutput> declarations allow you to define different settings for multiple networks:</para> + + + <programlisting>default-lease-time <replaceable>600</replaceable>; +max-lease-time <replaceable>7200</replaceable>; +subnet 10.0.0.0 netmask 255.255.255.0 { + option subnet-mask 255.255.255.0; + option routers 10.0.0.1; + range 10.0.0.5 10.0.0.15; +} +subnet 172.16.0.0 netmask 255.255.255.0 { + option subnet-mask 255.255.255.0; + option routers 172.16.0.1; + range 172.16.0.5 172.16.0.15; +}</programlisting> + <variablelist> + <varlistentry> + <term> + <computeroutput>subnet <replaceable>10.0.0.0</replaceable> netmask <replaceable>255.255.255.0</replaceable>;</computeroutput> + </term> + <listitem> + <para>A <computeroutput>subnet</computeroutput> declaration is required for every network your <systemitem class="protocol">DHCP</systemitem> server is serving. Multiple subnets require multiple <computeroutput>subnet</computeroutput> declarations. If the <systemitem class="protocol">DHCP</systemitem> server does not have a network interface in a range of a <computeroutput>subnet</computeroutput> declaration, the <systemitem class="protocol">DHCP</systemitem> server does not serve that network.</para> + <para>If there is only one <computeroutput>subnet</computeroutput> declaration, and no network interfaces are in the range of that subnet, the <systemitem class="protocol">DHCP</systemitem> daemon fails to start, and an error such as the following is logged to <filename>/var/log/messages</filename>:</para> + <programlisting>dhcpd: No subnet declaration for eth0 (0.0.0.0). +dhcpd: ** Ignoring requests on eth0. If this is not what +dhcpd: you want, please write a subnet declaration +dhcpd: in your dhcpd.conf file for the network segment +dhcpd: to which interface eth1 is attached. ** +dhcpd: +dhcpd: +dhcpd: Not configured to listen on any interfaces!</programlisting> + </listitem> + </varlistentry> + <varlistentry> + <term> + <computeroutput>option subnet-mask <replaceable>255.255.255.0</replaceable>;</computeroutput> + </term> + <listitem> + <para>The <computeroutput>option subnet-mask</computeroutput> option defines a subnet mask, and overrides the <computeroutput>netmask</computeroutput> value in the <computeroutput>subnet</computeroutput> declaration. In simple cases, the subnet and netmask values are the same.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <computeroutput>option routers <replaceable>10.0.0.1</replaceable>;</computeroutput> + </term> + <listitem> + <para>The <computeroutput>option routers</computeroutput> option defines the default gateway for the subnet. This is required for systems to reach internal networks on a different subnet, as well as external networks.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <computeroutput>range <replaceable>10.0.0.5</replaceable> <replaceable>10.0.0.15</replaceable>;</computeroutput> + </term> + <listitem> + <para>The <computeroutput>range</computeroutput> option specifies the pool of available <systemitem class="protocol">IP</systemitem> addresses. Systems are assigned an address from the range of specified <systemitem class="protocol">IP</systemitem> addresses.</para> + </listitem> + </varlistentry> + </variablelist> + <para>For further information, see the <filename>dhcpd.conf(5)</filename> man page.</para> + + <section + id="sec-dns_Host_Configuration"> + <title>Host Configuration</title> + <indexterm> + <primary>Multihomed DHCP</primary> + <secondary>host configuration</secondary> + </indexterm> + <para>Before making any changes, back up the existing <filename>/etc/sysconfig/dhcpd</filename> and <filename>/etc/dhcp/dhcpd.conf</filename> files.</para> + <formalpara> + <title>Configuring a Single System for Multiple Networks</title> + <para>The following <filename>/etc/dhcp/dhcpd.conf</filename> example creates two subnets, and configures an <systemitem class="protocol">IP</systemitem> address for the same system, depending on which network it connects to:</para> + </formalpara> + <programlisting>default-lease-time <replaceable>600</replaceable>; +max-lease-time <replaceable>7200</replaceable>; +subnet 10.0.0.0 netmask 255.255.255.0 { + option subnet-mask 255.255.255.0; + option routers 10.0.0.1; + range 10.0.0.5 10.0.0.15; +} +subnet 172.16.0.0 netmask 255.255.255.0 { + option subnet-mask 255.255.255.0; + option routers 172.16.0.1; + range 172.16.0.5 172.16.0.15; +} +host example0 { + hardware ethernet 00:1A:6B:6A:2E:0B; + fixed-address 10.0.0.20; +} +host example1 { + hardware ethernet 00:1A:6B:6A:2E:0B; + fixed-address 172.16.0.20; +}</programlisting> + <variablelist> + <varlistentry> + <term> + <computeroutput>host <replaceable>example0</replaceable> + </computeroutput> + </term> + <listitem> + <para>The <computeroutput>host</computeroutput> declaration defines specific parameters for a single system, such as an <systemitem class="protocol">IP</systemitem> address. To configure specific parameters for multiple hosts, use multiple <computeroutput>host</computeroutput> declarations.</para> + <para>Most <systemitem class="protocol">DHCP</systemitem> clients ignore the name in <computeroutput>host</computeroutput> declarations, and as such, this name can be anything, as long as it is unique to other <computeroutput>host</computeroutput> declarations. To configure the same system for multiple networks, use a different name for each <computeroutput>host</computeroutput> declaration, otherwise the <systemitem class="protocol">DHCP</systemitem> daemon fails to start. Systems are identified by the <computeroutput>hardware ethernet</computeroutput> option, not the name in the <computeroutput>host</computeroutput> declaration.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <computeroutput>hardware ethernet <replaceable>00:1A:6B:6A:2E:0B</replaceable>;</computeroutput> + </term> + <listitem> + <para>The <computeroutput>hardware ethernet</computeroutput> option identifies the system. To find this address, run the <command>ip link</command> command.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <computeroutput>fixed-address <replaceable>10.0.0.20</replaceable>;</computeroutput> + </term> + <listitem> + <para>The <computeroutput>fixed-address</computeroutput> option assigns a valid <systemitem class="protocol">IP</systemitem> address to the system specified by the <computeroutput>hardware ethernet</computeroutput> option. This address must be outside the <systemitem class="protocol">IP</systemitem> address pool specified with the <computeroutput>range</computeroutput> option.</para> + </listitem> + </varlistentry> + </variablelist> + <para>If <computeroutput>option</computeroutput> statements do not end with a semicolon, the <systemitem class="protocol">DHCP</systemitem> daemon fails to start, and an error such as the following is logged to <filename>/var/log/messages</filename>:</para> + <programlisting>/etc/dhcp/dhcpd.conf line 20: semicolon expected. +dhcpd: } +dhcpd: ^ +dhcpd: /etc/dhcp/dhcpd.conf line 38: unexpected end of file +dhcpd: +dhcpd: ^ +dhcpd: Configuration file errors encountered -- exiting</programlisting> + <formalpara> + <title>Configuring Systems with Multiple Network Interfaces</title> + <para>The following <computeroutput>host</computeroutput> declarations configure a single system, which has multiple network interfaces, so that each interface receives the same <systemitem class="protocol">IP</systemitem> address. This configuration will not work if both network interfaces are connected to the same network at the same time:</para> + </formalpara> + <programlisting>host interface0 { + hardware ethernet 00:1a:6b:6a:2e:0b; + fixed-address 10.0.0.18; +} +host interface1 { + hardware ethernet 00:1A:6B:6A:27:3A; + fixed-address 10.0.0.18; +}</programlisting> + <para>For this example, <computeroutput>interface0</computeroutput> is the first network interface, and <computeroutput>interface1</computeroutput> is the second interface. The different <computeroutput>hardware ethernet</computeroutput> options identify each interface.</para> + <para>If such a system connects to another network, add more <computeroutput>host</computeroutput> declarations, remembering to:</para> + <itemizedlist> + <listitem> + <para>assign a valid <computeroutput>fixed-address</computeroutput> for the network the host is connecting to.</para> + </listitem> + <listitem> + <para>make the name in the <computeroutput>host</computeroutput> declaration unique.</para> + </listitem> + </itemizedlist> + <para>When a name given in a <computeroutput>host</computeroutput> declaration is not unique, the <systemitem class="protocol">DHCP</systemitem> daemon fails to start, and an error such as the following is logged to <filename>/var/log/messages</filename>:</para> + <programlisting>dhcpd: /etc/dhcp/dhcpd.conf line 31: host interface0: already exists +dhcpd: } +dhcpd: ^ +dhcpd: Configuration file errors encountered -- exiting</programlisting> + <para>This error was caused by having multiple <computeroutput>host interface0</computeroutput> declarations defined in <filename>/etc/dhcp/dhcpd.conf</filename>.</para> + </section> + </section> + <section id="sec-dhcp_for_ipv6_dhcpv6"> + <title>DHCP for IPv6 (DHCPv6)</title> + <indexterm> + <primary>DHCP</primary> + <secondary>DHCPv6</secondary> + </indexterm> + <indexterm> + <primary>DHCP</primary> + <secondary>dhcpd6.conf</secondary> + </indexterm> + <para> + The ISC <systemitem class="protocol">DHCP</systemitem> includes support for <systemitem class="protocol">IPv6</systemitem> (<systemitem class="protocol">DHCPv6</systemitem>) since the 4.x release with a <systemitem class="protocol">DHCPv6</systemitem> server, client, and relay agent functionality. The agents support both <systemitem class="protocol">IPv4</systemitem> and <systemitem class="protocol">IPv6</systemitem>, however the agents can only manage one protocol at a time; for dual support they must be started separately for <systemitem class="protocol">IPv4</systemitem> and <systemitem class="protocol">IPv6</systemitem>. For example, configure both <systemitem class="protocol">DHCPv4</systemitem> and <systemitem class="protocol">DHCPv6</systemitem> by editing their respective configuration files <filename>/etc/dhcp/dhcpd.conf</filename> and <filename>/etc/dhcp/dhcpd6.conf</filename> and then issue the following commands: + <screen>~]# <command>systemctl start dhcpd</command> +~]# <command>systemctl start dhcpd6</command></screen> + </para> + <para> + The <systemitem class="protocol">DHCPv6</systemitem> server configuration file can be found at <filename>/etc/dhcp/dhcpd6.conf</filename>. + </para> + <para> + The example server configuration file can be found at <filename>/usr/share/doc/dhcp/dhcpd6.conf.example</filename>. + </para> + + <para> + A simple <systemitem class="protocol">DHCPv6</systemitem> server configuration file can look like this: + </para> + <programlisting>subnet6 2001:db8:0:1::/64 { + range6 2001:db8:0:1::129 2001:db8:0:1::254; + option dhcp6.name-servers fec0:0:0:1::1; + option dhcp6.domain-search "domain.example"; +}</programlisting> + </section> + <section + id="sec-dhcp-additional-resources"> + <title>Additional Resources</title> + <indexterm> + <primary>DHCP</primary> + <secondary>additional resources</secondary> + </indexterm> + <para>For additional information, see <citetitle>The DHCP Handbook; Ralph Droms and Ted Lemon; 2003</citetitle> or the following resources.</para> + <section + id="sec-dhcp-installed-docs"> + <title>Installed Documentation</title> + <itemizedlist> + <listitem> + <para> + <filename>dhcpd(8)</filename> man page — Describes how the <systemitem class="protocol">DHCP</systemitem> daemon works.</para> + </listitem> + <listitem> + <para> + <filename>dhcpd.conf(5)</filename> man page — Explains how to configure the <systemitem class="protocol">DHCP</systemitem> configuration file; includes some examples.</para> + </listitem> + <listitem> + <para> + <filename>dhcpd.leases(5)</filename> man page — Describes a persistent database of leases.</para> + </listitem> + <listitem> + <para> + <filename>dhcp-options(5)</filename> man page — Explains the syntax for declaring <systemitem class="protocol">DHCP</systemitem> options in <filename>dhcpd.conf</filename>; includes some examples.</para> + </listitem> + <listitem> + <para> + <filename>dhcrelay(8)</filename> man page — Explains the <systemitem class="protocol">DHCP</systemitem> Relay Agent and its configuration options.</para> + </listitem> + <listitem> + <para> + <filename>/usr/share/doc/dhcp/</filename> — Contains example configuration files. + </para> + </listitem> + <listitem> + <para> + <filename>/usr/share/doc/dhcp-common/</filename> — Contains README files, and release notes for current versions of the <systemitem class="protocol">DHCP</systemitem> service.</para> + </listitem> + </itemizedlist> + </section> + </section> +</chapter> diff --git a/docs/guide/DNS_Servers.xml b/docs/guide/DNS_Servers.xml new file mode 100644 index 000000000..d304d67d5 --- /dev/null +++ b/docs/guide/DNS_Servers.xml @@ -0,0 +1,175 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "Networking_Guide.ent"> +%BOOK_ENTITIES; +]> +<chapter id="ch-DNS_Servers"> + <title>DNS Servers</title> + <indexterm> + <primary>DNS</primary> + <secondary>definition</secondary> + <seealso>BIND</seealso> + </indexterm> + <indexterm> + <primary>nameserver</primary> + <see>DNS</see> + </indexterm> + <para> + <systemitem class="protocol">DNS</systemitem> (Domain Name System), is a distributed database system that is used to associate host names with their respective <systemitem class="protocol">IP</systemitem> addresses. For users, this has the advantage that they can refer to machines on the network by names that are usually easier to remember than the numerical network addresses. For system administrators, using a <systemitem class="protocol">DNS</systemitem> server, also known as a <firstterm>nameserver</firstterm>, enables changing the <systemitem class="protocol">IP</systemitem> address for a host without ever affecting the name-based queries. The use of the <systemitem class="protocol">DNS</systemitem> databases is not only for resolving <systemitem class="protocol">IP</systemitem> addresses to domain names and their use is becoming broader and broader as DNSSEC is deployed. + </para> + <section id="sec-Introduction_to_DNS"> + <title>Introduction to DNS</title> + <indexterm> + <primary>root nameserver</primary> + <see>BIND</see> + </indexterm> + <para> + <systemitem class="protocol">DNS</systemitem> is usually implemented using one or more centralized servers that are authoritative for certain domains. When a client host requests information from a nameserver, it usually connects to port 53. The nameserver then attempts to resolve the name requested. If the nameserver is configured to be a recursive name servers and it does not have an authoritative answer, or does not already have the answer cached from an earlier query, it queries other nameservers, called <firstterm>root nameservers</firstterm>, to determine which nameservers are authoritative for the name in question, and then queries them to get the requested name. Nameservers configured as purely authoritative, with recursion disabled, will not do lookups on behalf of clients. + </para> + <section id="sec-dns-introduction-zones"> + <title>Nameserver Zones</title> + <indexterm> + <primary>BIND</primary> + <secondary>resource record</secondary> + </indexterm> + <indexterm> + <primary>resource record</primary> + <see>BIND</see> + </indexterm> + <para> + In a <systemitem class="protocol">DNS</systemitem> server, all information is stored in basic data elements called <firstterm>resource records</firstterm> (<acronym>RR</acronym>). Resource records are defined in <ulink url="http://www.rfc-editor.org/rfc/rfc1034.txt">RFC 1034</ulink>. The domain names are organized into a tree structure. Each level of the hierarchy is divided by a period (<literal>.</literal>). For example: The root domain, denoted by <literal>.</literal>, is the root of the <systemitem class="protocol">DNS</systemitem> tree, which is at level zero. The domain name <systemitem class="domainname">com</systemitem>, referred to as the <firstterm>top-level domain</firstterm> (<acronym>TLD</acronym>) is a child of the root domain (<literal>.</literal>) so it is the first level of the hierarchy. The domain name <systemitem class="domainname">example.com</systemitem> is at the second level of the hierarchy. + </para> + <example id="example-dns-introduction-zones-rr"> + <title>A Simple Resource Record</title> + <para> + An example of a simple <firstterm>resource record</firstterm> (<acronym>RR</acronym>):</para> + <screen>example.com. 86400 IN A 192.0.2.1</screen> + <para> + The domain name, <systemitem class="domainname">example.com</systemitem>, is the <firstterm>owner</firstterm> for the RR. The value <literal>86400</literal> is the <firstterm>time to live</firstterm> (<acronym>TTL</acronym>). The letters <literal>IN</literal>, meaning <quote>the Internet system</quote>, indicate the <firstterm>class</firstterm> of the RR. The letter <literal>A</literal> indicates the <firstterm>type</firstterm> of RR (in this example, a host address). The host address <systemitem class="ipaddress">192.0.2.1</systemitem> is the data contained in the final section of this RR. This one line example is a RR. A set of RRs with the same type, owner, and class is called a <firstterm>resource record set</firstterm> (<acronym>RRSet</acronym>).</para> + </example> + <indexterm> + <primary>BIND</primary> + <secondary>zones</secondary> + <tertiary>description</tertiary> + </indexterm> + <indexterm> + <primary>BIND</primary> + <secondary>types</secondary> + <tertiary>primary (master) nameserver</tertiary> + </indexterm> + <indexterm> + <primary>BIND</primary> + <secondary>types</secondary> + <tertiary>secondary (slave) nameserver</tertiary> + </indexterm> + <para> + Zones are defined on authoritative nameservers through the use of <firstterm>zone files</firstterm>, which contain definitions of the resource records in each zone. Zone files are stored on <firstterm>primary nameservers</firstterm> (also called <firstterm>master nameservers</firstterm>), where changes are made to the files, and <firstterm>secondary nameservers</firstterm> (also called <firstterm>slave nameservers</firstterm>), which receive zone definitions from the primary nameservers. Both primary and secondary nameservers are authoritative for the zone and look the same to clients. Depending on the configuration, any nameserver can also serve as a primary or secondary server for multiple zones at the same time. + </para> + +<para> + Note that administrators of <systemitem class="protocol">DNS</systemitem> and <systemitem class="protocol">DHCP</systemitem> servers, as well as any provisioning applications, should agree on the host name format used in an organization. See <xref linkend="sec-Recommended_Naming_Practices" /> for more information on the format of host names. +</para> + </section> + <section id="sec-dns-introduction-nameservers"> + <title>Nameserver Types</title> + <para> + There are two nameserver configuration types: + </para> + <variablelist> + <varlistentry> + <term> + <indexterm> + <primary>BIND</primary> + <secondary>types</secondary> + <tertiary>authoritative nameserver</tertiary> + </indexterm> + <indexterm> + <primary>authoritative nameserver</primary> + <see>BIND</see> + </indexterm> + <indexterm> + <primary>BIND</primary> + <secondary>types</secondary> + <tertiary>primary (master) nameserver</tertiary> + </indexterm> + <indexterm> + <primary>primary nameserver</primary> + <see>BIND</see> + </indexterm> + <indexterm> + <primary>BIND</primary> + <secondary>types</secondary> + <tertiary>secondary (slave) nameserver</tertiary> + </indexterm> + <indexterm> + <primary>secondary nameserver</primary> + <see>BIND</see> + </indexterm> + authoritative + </term> + <listitem> + <para> + Authoritative nameservers answer to resource records that are part of their zones only. This category includes both primary (master) and secondary (slave) nameservers. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <indexterm> + <primary>BIND</primary> + <secondary>types</secondary> + <tertiary>recursive nameserver</tertiary> + </indexterm> + <indexterm> + <primary>recursive nameserver</primary> + <see>BIND</see> + </indexterm> + recursive + </term> + <listitem> + <para> + Recursive nameservers offer resolution services, but they are not authoritative for any zone. Answers for all resolutions are cached in a memory for a fixed period of time, which is specified by the retrieved resource record. + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + Although a nameserver can be both authoritative and recursive at the same time, it is recommended not to combine the configuration types. To be able to perform their work, authoritative servers should be available to all clients all the time. On the other hand, since the recursive lookup takes far more time than authoritative responses, recursive servers should be available to a restricted number of clients only, otherwise they are prone to distributed denial of service (DDoS) attacks. + </para> + </section> + <section id="sec-dns-introduction-bind"> + <title>BIND as a Nameserver</title> + <indexterm> + <primary>BIND</primary> + <secondary>utilities</secondary> + <tertiary><systemitem class="service">named</systemitem></tertiary> + </indexterm> + <indexterm> + <primary>BIND</primary> + <secondary>utilities</secondary> + <tertiary><command>rndc</command></tertiary> + </indexterm> + <indexterm> + <primary>BIND</primary> + <secondary>utilities</secondary> + <tertiary><command>dig</command></tertiary> + </indexterm> + <indexterm> + <primary><systemitem class="service">named</systemitem></primary> + <see>BIND</see> + </indexterm> + <indexterm> + <primary><command>rndc</command></primary> + <see>BIND</see> + </indexterm> + <indexterm> + <primary><command>dig</command></primary> + <see>BIND</see> + </indexterm> + <para> + BIND consists of a set of DNS-related programs. It contains a nameserver called <systemitem class="service">named</systemitem>, an administration utility called <command>rndc</command>, and a debugging tool called <command>dig</command>. See <citetitle pubwork="book">&MAJOROSVER; System Administrator's Guide</citetitle> for more information on how to run a service in &MAJOROS;. + </para> + </section> + </section> + <xi:include href="BIND.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> +</chapter> diff --git a/docs/guide/Editing-Bridge-Connection-1_Gnome3.png b/docs/guide/Editing-Bridge-Connection-1_Gnome3.png Binary files differnew file mode 100644 index 000000000..efd025f78 --- /dev/null +++ b/docs/guide/Editing-Bridge-Connection-1_Gnome3.png diff --git a/docs/guide/Feedback.xml b/docs/guide/Feedback.xml new file mode 100644 index 000000000..080ff2bac --- /dev/null +++ b/docs/guide/Feedback.xml @@ -0,0 +1,32 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ +]> + +<section id="sec-Preface-Feedback"> + <title>Feedback</title> + <indexterm> + <primary>feedback</primary> + <secondary>contact information for this manual</secondary> + </indexterm> + <para> + If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in <ulink url="http://bugzilla.redhat.com/">Bugzilla</ulink> against the product <application>&PRODUCT;</application>. + </para> + <para> + When submitting a bug report, be sure to provide the following information: + </para> + <itemizedlist> + <listitem> + <para> + Manual's identifier: <literal>&BOOKID;</literal> + </para> + </listitem> + <listitem> + <para> + Version number: <literal>&PRODVER;</literal> + </para> + </listitem> + </itemizedlist> + <para> + If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily. + </para> +</section> diff --git a/docs/guide/Introduction_to_Fedora_Networking.xml b/docs/guide/Introduction_to_Fedora_Networking.xml new file mode 100644 index 000000000..54114e073 --- /dev/null +++ b/docs/guide/Introduction_to_Fedora_Networking.xml @@ -0,0 +1,324 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "Networking_Guide.ent"> +%BOOK_ENTITIES; +]> +<!--TOPIC: CONCEPTS--> +<chapter id="ch-Introduction_to_Fedora_Networking"> +<title>Introduction to Fedora Networking</title> +<section id="sec-How_this_Book_is_Structured"> + <title>How this Book is Structured</title> +<para> + All new material in this book has been written and arranged in such a way as to clearly separate introductory material, such as explanations of concepts and use cases, from configuration tasks. The authors hope that you can quickly find configuration instructions you need, while still providing some relevant explanations and conceptual material to help you understand and decide on the appropriate tasks relevant to your needs. Where material has been reused from the <ulink url="https://access.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Deployment_Guide/index.html" ><citetitle pubwork="book">Red Hat Enterprise Linux 6 Deployment Guide</citetitle></ulink>, it has been reviewed and changed, where possible, to fit this idea of separating concepts from tasks. +</para> +<para> + The material is grouped according to the goal rather than the method. Instructions on how to achieve a specific task using different methods are grouped together. This is intended to make it easier for you to find the information on how to achieve a particular task or goal, and at the same time allow you to quickly see the different methods available.</para> + <para> + In each chapter, the configuration methods will be presented in the following order: + A graphical user interface (GUI) method, such as the use of <application>nm-connection-editor</application> or <application>control-network</application> to direct <systemitem class="service">NetworkManager</systemitem>, then <application>NetworkManager</application>'s command-line tool <application>nmcli</application>, and then finally methods using the command line and configuration files. The command line can be used to issue commands and to compose or edit configuration files, therefore the use of the <application>ip</application> commands and configuration files will be documented together. +</para> + + +</section> + +<section id="sec-Introduction_to_NetworkManager"> + <title>Introduction to NetworkManager</title> + +<para> + As of Fedora 20, the default networking service is provided by <systemitem class="service">NetworkManager</systemitem>, which is a dynamic network control and configuration daemon that attempts to keep network devices and connections up and active when they are available. The traditional <filename>ifcfg</filename> type configuration files are still supported. See <xref linkend="sec-NetworkManager_and_the_Network_Scripts" /> for more information.</para> +<table id="tb-A_Summary_of_Networking_Tools_and_Applications" frame='all'> +<title>A Summary of Networking Tools and Applications</title> +<tgroup cols='2' align='left' colsep='1' rowsep='1'> +<colspec colname='c1' colwidth="20*" /> +<colspec colname='c2' colwidth="50*" /> +<thead> +<row> + <entry>Application or Tool</entry> + <entry>Description</entry> +</row> +</thead> +<tbody> +<row> + <entry><application>NetworkManager</application></entry> + <entry>The default networking daemon</entry> +</row> +<row> + <entry><application>nmtui</application></entry> + <entry>A simple curses-based text user interface (TUI) for <application>NetworkManager</application></entry> +</row> +<row> + <entry><application>nmcli</application></entry> + <entry>A command-line tool provided to allow users and scripts to interact with <application>NetworkManager</application></entry> +</row> +<row> + <entry><application>control-center</application></entry> + <entry>A graphical user interface tool provided by the GNOME Shell</entry> +</row> + <row> + <entry><application>nm-connection-editor</application></entry> + <entry>A GTK+ 3 application available for certain tasks not yet handled by <application>control-center</application></entry> +</row> +</tbody> +</tgroup> +</table> + + + <para> + <systemitem class="service">NetworkManager</systemitem> can be used with the following types of connections: Ethernet, VLANs, Bridges, Bonds, Teams, Wi-Fi, mobile broadband (such as cellular 3G), and IP-over-InfiniBand. For these connection types, <systemitem class="service">NetworkManager</systemitem> can configure network aliases, <systemitem class="protocol">IP</systemitem> addresses, static routes, <systemitem class="protocol">DNS</systemitem> information, and VPN connections, as well as many connection-specific parameters. Finally, <systemitem class="service">NetworkManager</systemitem> provides an API via D-Bus which allows applications to query and control network configuration and state. +</para> +</section> + +<!-- TOPIC: TASKS --> +<section id="sec-Installing_NetworkManager"> + <title>Installing NetworkManager</title> + <para> + <application>NetworkManager</application> is installed by default on &MAJOROS;. If necessary, to ensure that it is, run the following command as the <systemitem class="username">root</systemitem> user:</para> + <screen>~]# <command>dnf install NetworkManager</command></screen> + <para>For information on user privileges and gaining privileges, see the <citetitle pubwork="book">&MAJOROSVER; System Administrator's Guide</citetitle>.</para> + <section + id="sec-The_NetworkManager_Daemon"> + <title>The NetworkManager Daemon</title> + <para>The <application>NetworkManager</application> daemon runs with root privileges and is, by default, configured to start up at boot time. You can determine whether the <application>NetworkManager</application> daemon is running by entering this command:</para> + <screen>~]$ <command>systemctl status NetworkManager</command> +NetworkManager.service - Network Manager + Loaded: loaded (/lib/systemd/system/NetworkManager.service; enabled) + Active: active (running) since Fri, 08 Mar 2013 12:50:04 +0100; 3 days ago</screen> + <para>The <command>systemctl status</command> command will report <application>NetworkManager</application> as <computeroutput>Active: inactive (dead)</computeroutput> if the <application>NetworkManager</application> service is not running. To start it for the current session run the following command as the root user:</para> + <screen>~]# <command>systemctl start NetworkManager</command></screen> + <para>Run the <command>systemctl enable</command> command to ensure that <application>NetworkManager</application> starts up every time the system boots:</para> + <screen>~]# <command>systemctl enable NetworkManager</command></screen> + <para>For more information on starting, stopping and managing services, see the <citetitle pubwork="book">&MAJOROSVER; System Administrator's Guide</citetitle>.</para> + </section> + <section + id="sec-Interacting_with_NetworkManager"> + <title>Interacting with NetworkManager</title> + <para>Users do not interact with the <application>NetworkManager</application> system service directly. Instead, users perform network configuration tasks via graphical and command-line user interface tools. The following tools are available in Fedora:</para> + <para> + <orderedlist> + <listitem> + <para> + A graphical user interface tool called <application>control-center</application>, provided by GNOME, is available for desktop users. It incorporates a <application>Network</application> settings tool. It start it, press the <keycap>Super</keycap> key to enter the Activities Overview, type <command>control network</command> and then press <keycap>Enter</keycap>. + </para> + </listitem> + + <listitem> + <para> + A command-line tool, <application>nmcli</application>, is provided to allow users and scripts to interact with <application>NetworkManager</application>. Note that <application>nmcli</application> can be used on GUI-less systems like servers to control all aspects of <application>NetworkManager</application>. It is on an equal footing with the GUI tools. + </para> + </listitem> + <listitem> + <para> + The GNOME Shell also provides a network icon in its Notification Area representing network connection states as reported by <application>NetworkManager</application>. The icon has multiple states that serve as visual indicators for the type of connection you are currently using. + </para> + </listitem> + <listitem> + <para> + A graphical user interface tool called <application>control-center</application>, provided by the GNOME Shell, is available for desktop users. It incorporates a <application>Network</application> settings tool. To start it, press the <keycap>Super</keycap> key to enter the Activities Overview, type <command>control network</command> and then press <keycap>Enter</keycap>. The <keycap>Super</keycap> key appears in a variety of guises, depending on the keyboard and other hardware, but often as either the Windows or Command key, and typically to the left of the Spacebar. + </para> + </listitem> + <listitem> + <para> + A graphical user interface tool, <application>nm-connection-editor</application>, is available for certain tasks not yet handled by <application>control-center</application>. To start it, press the <keycap>Super</keycap> key to enter the Activities Overview, type <command>network connections</command> or <command>nm-connection-editor</command> and then press <keycap>Enter</keycap>. + </para> + </listitem> + + </orderedlist> + </para> + + </section> +</section> +<section id="sec-Network_Config_Using_CLI"> + <title>Network Configuration Using the Command Line Interface (CLI)</title> +<para> +</para> +<para>The commands for the <application>ip</application> utility, sometimes referred to as <package>iproute2</package> after the upstream package name, are documented in the <filename>man ip(8)</filename> page. The package name in Fedora is <package>iproute</package>. If necessary, you can check that the <application>ip</application> utility is installed by checking its version number as follows:</para> + <screen>~]$ <command>ip -V</command> +ip utility, iproute2-ss130716</screen> +<para> + The <application>ip</application> commands can be used to add and remove addresses and routes to interfaces in parallel with <application>NetworkManager</application>, which will preserve them and recognize them in <application>nmcli</application>, <application>nmtui</application>, <application>control-center</application>, and the D-Bus API. +</para> + <note> + <para> + Note that <application>ip</application> commands given on the command line will not persist after a system restart. + </para> + </note> + <para> + Examples of using the command line and configuration files for each task are included after explaining the use of one of the graphical user interfaces to <application>NetworkManager</application>, namely, <application>control-center</application> and <application>nm-connection-editor</application>. + </para> +</section> +<section id="sec-Network_Config_Using_nmcli"> +<title>Network Configuration Using NetworkManager's CLI (nmcli)</title> +<para> +</para> + <para> + The <application>NetworkManager</application> command-line tool, <application>nmcli</application>, provides a command line way to configure networking by controlling <application>NetworkManager</application>. It is installed, along with <application>NetworkManager</application>, by default. If required, for details on how to verify that <application>NetworkManager</application> is running, see <xref linkend="sec-The_NetworkManager_Daemon" />.</para> +<para> + Examples of using the <application>nmcli</application> tool for each task will be included where possible, after explaining the use of graphical user interfaces and other command line methods. See <xref linkend="sec-Using_the_NetworkManager_Command_Line_Tool_nmcli" /> for an introduction to <application>nmcli</application>. + </para> +</section> + +<section id="sec-NetworkManager_and_the_Network_Scripts"> +<title>NetworkManager and the Network Scripts</title> +<para> +In previous Red Hat Enterprise Linux releases, the default way to configure networking was using <firstterm>network scripts</firstterm>. The term <firstterm>network scripts</firstterm> is commonly used for the script <filename class="directory">/etc/init.d/network</filename> and any other installed scripts it calls. The user supplied files are typically viewed as configuration, but can also be interpreted as an amendment to the scripts.</para> + <para> + Although <application>NetworkManager</application> provides the default networking service, Red Hat developers have worked hard to ensure that scripts and <application>NetworkManager</application> cooperate with each other. Administrators who are used to the scripts can certainly continue to use them. We expect both systems to be able to run in parallel and work well together. It is expected that most user shell scripts from previous releases will still work. Red Hat recommends that you test them first. +</para> + <bridgehead id="bh-Running_Network_Script">Running Network Script</bridgehead> + <para> +Run the script <emphasis role="bold">only</emphasis> with the <application>systemctl</application> utility which will clear any existing environment variables and ensure clean execution. The command takes the following form: +<synopsis><command>systemctl <option>start|stop|restart|status</option> network</command></synopsis></para> +<para><emphasis role="bold">Do not run</emphasis> any service by calling <command>/etc/init.d/<replaceable>servicename</replaceable> <option>start|stop|restart|status</option></command> directly. +</para> +<para> + Note that in Red Hat Enterprise Linux 7, <application>NetworkManager</application> is started first, and <filename>/etc/init.d/network</filename> checks with <application>NetworkManager</application> to avoid tampering with <application>NetworkManager</application>'s connections. <application>NetworkManager</application> is intended to be the primary application using sysconfig configuration files and <filename>/etc/init.d/network</filename> is intended to be secondary, playing a fallback role. +</para> +<para> +The <filename>/etc/init.d/network</filename> script is not event-driven, it runs either: +<orderedlist> + <listitem> + <para> + manually (by one of the <command>systemctl</command> commands <command><option>start|stop|restart</option> network</command>), + </para> + </listitem> + <listitem> + <para> + on boot and shutdown if the network service is enabled (as a result of the command <command>systemctl enable network</command>). + </para> + </listitem> +</orderedlist> + It is a manual process and does not react to events that happen after boot. Users can also call the scripts <filename>ifup</filename> and <filename>ifdown</filename> manually. + </para> + <para> + <!--<remark>SJW: Adding new material from: https://bugzilla.redhat.com/show_bug.cgi?id=1056090#c22</remark>--> + </para> + <bridgehead id="bh-Custom_Commands_and_the_Network_Scripts">Custom Commands and the Network Scripts</bridgehead> + <para> + Custom commands in the scripts <filename>/sbin/ifup-local</filename>, <filename>ifdown-pre-local</filename>, and <filename>ifdown-local</filename> are only executed when those devices are controlled by the <systemitem class="daemon">/etc/init.d/network</systemitem> service. If you modified the initscripts themselves (for example, <filename>/etc/sysconfig/network-scripts/ifup-eth</filename>) then those changes would be overwritten by an <package>initscripts</package> package update. Therefore it is recommend that you avoid modifying the initscripts directly and make use of the <filename>/sbin/if*local</filename> scripts, so that your custom changes will survive package updates. The initscripts just check for the presence of the relevant <filename>/sbin/if*local</filename> and run them if they exit. The initscripts do not place anything in the <filename>/sbin/if*local</filename> scripts, nor does the <package>initscripts</package> RPM (or any package) own or modify those files. + </para> + <para> +There are ways to perform custom tasks when network connections go up and down, both with the old network scripts and with <application>NetworkManager</application>. When <application>NetworkManager</application> is enabled, the <filename>ifup</filename> and <filename>ifdown</filename> script will ask <application>NetworkManager</application> whether <application>NetworkManager</application> manages the interface in question, which is found from the <quote>DEVICE=</quote> line in the <filename>ifcfg</filename> file. If <application>NetworkManager</application> does manage that device, and the device is not already connected, then <filename>ifup</filename> will ask <application>NetworkManager</application> to start the connection. +<itemizedlist> + <listitem> + <para> +If the device is managed by <application>NetworkManager</application> and it <emphasis role="bold">is</emphasis> already connected, nothing is done. + </para> + </listitem> + <listitem> + <para> +If the device is not managed by <application>NetworkManager</application>, then the scripts will start the connection using the older, non-<application>NetworkManager</application> mechanisms that they have used since the time before <application>NetworkManager</application> existed. + </para> + </listitem> +</itemizedlist> +</para> +<para> +If you are calling "<filename>ifdown</filename>" and the device is managed by <application>NetworkManager</application>, then <filename>ifdown</filename> will ask <application>NetworkManager</application> to terminate the connection. + </para> + <para> + The scripts dynamically check <application>NetworkManager</application>, so if <application>NetworkManager</application> is not running, the scripts will fall back to the old, pre-<application>NetworkManager</application> script-based mechanisms. + </para> +</section> + +<section id="sec-Network_Configuration_Using_sysconfig_Files"> +<title>Network Configuration Using sysconfig Files</title> +<para> +The <filename class="directory">/etc/sysconfig/</filename> directory is a location for configuration files and scripts. Most network configuration information is stored there, with the exception of VPN, mobile broadband and PPPoE configuration, which are stored in <filename class="directory">/etc/NetworkManager/</filename> subdirectories. Interface specific information for example, is stored in <filename>ifcfg</filename> files in the <filename class="directory">/etc/sysconfig/network-scripts/</filename> directory.</para> +<para> +The file <filename>/etc/sysconfig/network</filename> is for global settings. Information for VPNs, mobile broadband and PPPoE connections is stored in <filename class="directory">/etc/NetworkManager/system-connections/</filename>. +</para> + + <para> + In Fedora, when you edit an <filename>ifcfg</filename> file, <application>NetworkManager</application> is not automatically aware of the change and has to be prompted to notice the change. If you use one of the tools to update <application>NetworkManager</application> profile settings, then <application>NetworkManager</application> does not implement those changes until you reconnect using that profile. For example, if configuration files have been changed using an editor, <application>NetworkManager</application> must be told to read the configuration files again. To do that, issue the following command as <systemitem class="username">root</systemitem>: + <screen>~]# <command>nmcli connection reload</command></screen> + The above command reads all connection profiles. Alternatively, to reload only one changed file, <filename>ifcfg-<replaceable>ifname</replaceable></filename>, issue a command as follows: + <screen>~]# <command>nmcli con load /etc/sysconfig/network-scripts/ifcfg-<replaceable>ifname</replaceable></command></screen> + The command accepts multiple file names. These commands require <systemitem class="username">root</systemitem> privileges. For more information on user privileges and gaining privileges, see the <citetitle pubwork="book">&MAJOROSVER; System Administrator's Guide</citetitle> and the <filename>su(1)</filename> and <filename>sudo(8)</filename> man pages.</para> + <para> + Changes made using tools such as <application>nmcli</application> do not require a reload but do require the associated interface to be put down and then up again. That can be done by using commands in the following format: + <synopsis>nmcli dev disconnect <replaceable>interface-name</replaceable></synopsis> + Followed by: + <synopsis>nmcli con up <replaceable>interface-name</replaceable></synopsis> + </para> + <para> + <application>NetworkManager</application> does not trigger any of the network scripts, though the network scripts will try to trigger <application>NetworkManager</application> if it is running when <filename>ifup</filename> commands are used. See <xref linkend="sec-NetworkManager_and_the_Network_Scripts" /> for an explanation of the network scripts. + </para> + <para> + The <filename>ifup</filename> script is a generic script which does a few things and then calls interface-specific scripts like <filename>ifup-ethX</filename>, <filename>ifup-wireless</filename>, <filename>ifup-ppp</filename>, and so on. When a user runs <command>ifup eth0</command> manually, the following occurs: + <orderedlist> + <listitem> + <para> + <filename>ifup</filename> looks for a file called <filename>/etc/sysconfig/network-scripts/ifcfg-eth0</filename>; + </para> + </listitem> + <listitem> + <para> + if the <filename>ifcfg</filename> file exists, <filename>ifup</filename> looks for the <option>TYPE</option> key in that file to determine which type-specific script to call; + </para> + </listitem> + <listitem> + <para> + <filename>ifup</filename> calls <filename>ifup-wireless</filename> or <filename>ifup-eth</filename> or <filename>ifup-XXX</filename> based on <option>TYPE</option>; + </para> + </listitem> + <listitem> + <para> + the type-specific scripts do type-specific setup; + </para> + </listitem> + <listitem> + <para> + and then the type-specific scripts let common functions perform <systemitem class="protocol">IP</systemitem>-related tasks like <systemitem class="protocol">DHCP</systemitem> or static setup. + </para> + </listitem> + </orderedlist> + </para> + <para> + On bootup, <filename>/etc/init.d/network</filename> reads through all the <filename>ifcfg</filename> files and for each one that has <command>ONBOOT=yes</command>, it checks whether <application>NetworkManager</application> is already starting the DEVICE from that <filename>ifcfg</filename> file. If <application>NetworkManager</application> is starting that device or has already started it, nothing more is done for that file, and the next <command>ONBOOT=yes</command> file is checked. If <application>NetworkManager</application> is not yet starting that device, the initscripts will continue with their traditional behavior and call <filename>ifup</filename> for that <filename>ifcfg</filename> file. + </para> + <para> + The end result is that any <filename>ifcfg</filename> file that has <command>ONBOOT=yes</command> is expected to be started on system bootup, either by <application>NetworkManager</application> or by the initscripts. This ensures that some legacy network types which <application>NetworkManager</application> does not handle (such as ISDN or analog dialup modems) as well as any new application not yet supported by <application>NetworkManager</application> are still correctly started by the initscripts even though <application>NetworkManager</application> is unable to handle them. + </para> + <note> + <para> + It is recommended not to store backup <filename>ifcfg</filename> files in the same location as the live ones. The script literally does <command>ifcfg-*</command> with an exclude only for these extensions: + <filename>.old</filename>, <filename>.orig</filename>, <filename>.rpmnew</filename>, <filename>.rpmorig</filename>, and <filename>.rpmsave</filename>. The best way is not to store backup files anywhere within the <filename class="directory">/etc/</filename> directory. + </para> + </note> +</section> + + <!--Topics, Reference--> + <section id="sec-Introduction_to_Fedora_Networking-additional_resources"> + +<title>Additional Resources</title> +<para> + The following sources of information provide additional resources regarding networking for Fedora. + </para> + <section id="sec-Introduction_to_Fedora_Networking-docs-inst"> + <title>Installed Documentation</title> + <itemizedlist> + <listitem> + <para> + <filename>man(1)</filename> man page — Describes man pages and how to find them. + </para> + </listitem> + <listitem> + <para> + <filename>NetworkManager(8)</filename> man page — Describes the network management daemon. + </para> + </listitem> + <listitem> + <para> + <filename>NetworkManager.conf(5)</filename> man page — Describes the <systemitem class="daemon">NetworkManager</systemitem> configuration file. + </para> + </listitem> + + <listitem> + <para> + <filename>/usr/share/doc/initscripts-<replaceable>version</replaceable>/sysconfig.txt</filename> — Describes configuration files and their directives. + </para> + </listitem> + </itemizedlist> +</section> +</section> + +</chapter> diff --git a/docs/guide/Makefile.am b/docs/guide/Makefile.am new file mode 100644 index 000000000..995e91d60 --- /dev/null +++ b/docs/guide/Makefile.am @@ -0,0 +1,37 @@ +AUTOMAKE_OPTIONS = 1.7 + +DOC_MODULE=guide + +DOC_MAIN_SGML_FILE=Networking_Guide.xml + +DOC_SOURCE_DIR=$(srcdir) + +content_files = \ + Author_Group.xml \ + Book_Info.xml \ + BIND.xml \ + Configure_802_1Q_VLAN_Tagging.xml \ + Configure_Host_Names.xml \ + Configure_Network_Bonding.xml \ + Configure_Network_Bridging.xml \ + Configure_Networking.xml \ + Configure_Network_Teaming.xml \ + Consistent_Network_Device_Naming.xml \ + DHCP_Servers.xml \ + DNS_Servers.xml \ + Feedback.xml \ + Introduction_to_Fedora_Networking.xml \ + Networking_Guide.xml \ + Preface.xml \ + Revision_History.xml \ + $(NULL) + +HTML_IMAGES = \ + Editing-Bridge-Connection-1_Gnome3.png \ + Network-Wired_Gnome3.png \ + Network-Details-Wired_Gnome3.png \ + $(NULL) + +include $(top_srcdir)/gtk-doc.make + +CLEANFILES += html/* tmpl/* xml/* diff --git a/docs/guide/Network-Details-Wired_Gnome3.png b/docs/guide/Network-Details-Wired_Gnome3.png Binary files differnew file mode 100644 index 000000000..ba58a959e --- /dev/null +++ b/docs/guide/Network-Details-Wired_Gnome3.png diff --git a/docs/guide/Network-Wired_Gnome3.png b/docs/guide/Network-Wired_Gnome3.png Binary files differnew file mode 100644 index 000000000..56fca9c74 --- /dev/null +++ b/docs/guide/Network-Wired_Gnome3.png diff --git a/docs/guide/Networking_Guide.ent b/docs/guide/Networking_Guide.ent new file mode 100644 index 000000000..bae6f57d0 --- /dev/null +++ b/docs/guide/Networking_Guide.ent @@ -0,0 +1,13 @@ +<!-- Obligatory Entities: --> +<!ENTITY PRODUCT "Fedora Documentation"> +<!ENTITY BOOKID "networking-guide"> +<!ENTITY YEAR "2016"> +<!ENTITY HOLDER "Red Hat, Inc. and others"> +<!ENTITY BUGZILLA '<ulink url="https://bugzilla.redhat.com/enter_bug.cgi?product=&PRODUCT;&component=&BOOKID;" />'> +<!ENTITY BZURL 'https://bugzilla.redhat.com/enter_bug.cgi?product=&PRODUCT;&component=&BOOKID;'> +<!-- Additional Entities: --> +<!ENTITY MAJOROS "Fedora"> +<!ENTITY MAJOROSVER "Fedora 24"> +<!ENTITY OSORG "The Fedora Project"> +<!ENTITY PKGOS "fc24"> +<!ENTITY PRODVER "24"> diff --git a/docs/guide/Networking_Guide.xml b/docs/guide/Networking_Guide.xml new file mode 100644 index 000000000..dfa3edc0f --- /dev/null +++ b/docs/guide/Networking_Guide.xml @@ -0,0 +1,48 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "Networking_Guide.ent"> +%BOOK_ENTITIES; +]> +<book status="draft"> + <!-- TITLE PAGE --> + <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <!-- FRONT MATTER --> + <xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <!-- MAIN CONTENT --> + + +<part id="part-Networking"> + <title>Networking</title> + <partintro> + <para> + This part describes how to configure the network on &MAJOROS;. + </para> + </partintro> + <xi:include href="Introduction_to_Fedora_Networking.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Configure_Networking.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Configure_Host_Names.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Configure_Network_Bonding.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Configure_Network_Teaming.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Configure_Network_Bridging.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Configure_802_1Q_VLAN_Tagging.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <!--<xi:include href="Configure_IPoIB.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />--> + <xi:include href="Consistent_Network_Device_Naming.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + </part> +<part id="part-Servers"> + <title>Servers</title> + <partintro> + <para> + This part discusses how to set up servers normally required for networking. + </para> + </partintro> + <xi:include href="DHCP_Servers.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="DNS_Servers.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + </part> + + + + <!-- APPENDIXES --> + <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <!-- INDEX --> + <index /> +</book> diff --git a/docs/guide/Preface.xml b/docs/guide/Preface.xml new file mode 100644 index 000000000..9d6009268 --- /dev/null +++ b/docs/guide/Preface.xml @@ -0,0 +1,131 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "Networking_Guide.ent"> +%BOOK_ENTITIES; +]> +<preface> + <title>Preface</title> + <para> + The <citetitle pubwork="book">Networking Guide</citetitle> contains information on how to use the networking related features of &MAJOROSVER;. + </para> + <para> + This manual discusses many intermediate topics such as the following: + </para> + <itemizedlist> + + <listitem> + <para> + Setting up a network (from establishing an Ethernet connection using <application>NetworkManager</application> to configuring channel bonding interfaces). + </para> + </listitem> + <listitem> + <para> + Configuring <systemitem class="protocol">DHCP</systemitem>, <application>BIND</application>, and <systemitem class="protocol">DNS</systemitem>. + </para> + </listitem> + + </itemizedlist> + + <section id="sec-Preface-Target_Audience"> + <title>Target Audience</title> + <para> + The <citetitle pubwork="book">Networking Guide</citetitle> assumes you have a basic understanding of the &MAJOROS; operating system. If you need help with the installation of this system, see the <citetitle pubwork="book">&MAJOROSVER; Installation Guide</citetitle>. + </para> + <para> + This guide is not aimed exclusively at experienced Linux system administrators. The authors of this book have attempted to cater for a wider audience as more and more organizations and users become subscribers to Red Hat, Inc. At the same time we are aware of the need not to allow seemingly trivial information to get in the way of the tasks. Your feedback on how well we have met this goal is welcome. + </para> + </section> + + <section id="sec-Preface-About_this_book"> + <title>About This Book</title> + <para> + The <citetitle pubwork="book">Networking Guide</citetitle> is based on the networking material in the <ulink url="https://access.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Deployment_Guide/index.html" ><citetitle pubwork="book">Red Hat Enterprise Linux 6 Deployment Guide</citetitle></ulink>. It also retains the information on <systemitem class="protocol">DHCP</systemitem> and <systemitem class="protocol">DNS</systemitem> servers from the <xref linkend="part-Servers" /> section. Most of the non-networking related material from the <citetitle pubwork="book">Red Hat Enterprise Linux 6 Deployment Guide</citetitle> guide can now be found in the <citetitle pubwork="book">&MAJOROSVER; System Administrator's Guide</citetitle> except for reference material, such as that found in the appendices of the Deployment Guide.<!--Reference material is now in a separate guide, the <citetitle pubwork="book">&MAJOROSVER; System Administrator's Reference Guide</citetitle>.--> + </para> + </section> + + + <section id="sec-Preface-Book_Organization"> + <title>How to Read this Book</title> + <para> + This manual is divided into the following main categories: + </para> + <variablelist> + + <varlistentry> + <term><xref linkend="part-Networking" /> </term> + <listitem> + <para> + This part describes how to configure the network on &MAJOROS;. + </para> + <para> + <xref linkend="ch-Introduction_to_Fedora_Networking" /> explains the default networking service, <application>NetworkManager</application>, and the various graphical and command-line tools that can be used to interact with <application>NetworkManager</application>. These include, an associated command-line configuration tool, <application>nmcli</application>, and two graphical user interface tools, <application>control-center</application> and <application>nm-connection-editor</application>. Read this chapter to learn more about the many ways the <application>NetworkManager</application> daemon can be used. + </para> + <para> + <xref linkend="ch-Configure_Networking" /> covers static and dynamic interface settings, selecting network configuration methods, using <application>NetworkManager</application> with graphical and command-line user interfaces. Read this chapter to learn about configuring network connections. + </para> + <para> + <xref linkend="ch-Configure_Host_Names" /> covers static, pretty, and transient host names and their configuration using <application>hostnamectl</application>. Read this chapter to learn more about configuring host names on local and remote systems. + </para> + <para> + <xref linkend="ch-Configure_Network_Bonding" /> covers the configuring and use of bonded network connections. Read this chapter to learn about the configuring of network bonds using graphical and command-line user interfaces. + </para> + <para> + <xref linkend="ch-Configure_Network_Teaming" /> covers the configuring and use of teamed network connections. Read this chapter to learn about the configuring of network teams using graphical and command-line user interfaces. + </para> + + <para> + <xref linkend="ch-Configure_Network_Bridging" /> covers the configuring and use of network bridges. Read this chapter to learn about the configuring of network bridges using graphical and command-line user interfaces. + </para> + + <para> + <xref linkend="ch-Configure_802_1Q_VLAN_Tagging" /> covers the configuring and use of virtual private networks, VLANs, according to the 802.1Q standard. Read this chapter to learn about the configuring of VLANs using graphical and command-line user interfaces. + </para> + <!--<para> + <xref linkend="ch-Configure_IPoIB" /> covers the configuring and use of IP over InfiniBand network connections. Read this chapter to learn about the configuring of IPoIB connections using graphical and command-line user interfaces. + </para>--> + <para> + <xref linkend="ch-Consistent_Network_Device_Naming" /> covers consistent network device naming for network interfaces, a feature that changes the name of network interfaces on a system in order to make locating and differentiating the interfaces easier. Read this chapter to learn about this feature and how to enable or disable it. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><xref linkend="part-Servers" /></term> + <listitem> + <para> + This part discusses how to set up servers normally required for networking. + </para> + <para> + <xref linkend="ch-DHCP_Servers" /> covers the installation of a Dynamic Host Configuration Protocol (<systemitem class="protocol">DHCP</systemitem>) server and client. Read this chapter if you need to configure <systemitem class="protocol">DHCP</systemitem> on your system. + </para> + <para> + <xref linkend="ch-DNS_Servers" /> covers the Domain Name System (<systemitem class="protocol">DNS</systemitem>), explains how to install, configure, run, and administer the <application>BIND</application> <systemitem class="protocol">DNS</systemitem> server. Read this chapter if you need to configure a <systemitem class="protocol">DNS</systemitem> server on your system. + </para> + + </listitem> + </varlistentry> + + </variablelist> + <para> + For topics related to network configuration but not listed above, such as configuring GRUB to enable serial links and the use of virtual console terminals, see the <citetitle pubwork="book">&MAJOROSVER; System Administrator's Guide</citetitle>. + </para> + <para> + For topics related to servers but not listed above, such as configuring Network Time Protocol (<systemitem class="protocol">NTP</systemitem>) and Precision Time Protocol (<systemitem class="protocol">PTP</systemitem>), see the <citetitle pubwork="book">&MAJOROSVER; System Administrator's Guide</citetitle>. + </para> + + </section> + <xi:include href="Common_Content/Conventions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Feedback.xml" xmlns:xi="http://www.w3.org/2001/XInclude"> + <xi:fallback xmlns:xi="http://www.w3.org/2001/XInclude"> + <xi:include href="Common_Content/Feedback.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + </xi:fallback> + </xi:include> + <section id="pref-Acknowledgments"> + <title>Acknowledgments</title> + <para> + Certain portions of this text first appeared in the <citetitle>Red Hat Enterprise Linux 6 Deployment Guide</citetitle>, copyright © 2010—YEAR Red Hat, Inc., available at <ulink url="https://access.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Deployment_Guide/index.html" />. + </para> + + + </section> +</preface> diff --git a/docs/guide/Revision_History.xml b/docs/guide/Revision_History.xml new file mode 100644 index 000000000..4fa344eb2 --- /dev/null +++ b/docs/guide/Revision_History.xml @@ -0,0 +1,128 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "Networking_Guide.ent"> +%BOOK_ENTITIES; +]> +<appendix id="app-Revision_History"> + <title>Revision History</title> + <simpara> + <revhistory> + + <revision> + <revnumber>3-0</revnumber> + <date>Mon Nov 02 2015</date> + <author> + <firstname>Stephen</firstname> + <surname>Wadeley</surname> + <email>swadeley@redhat.com</email> + </author> + <revdescription> + <simplelist> + <member>Fedora 23 release of the <citetitle>Networking Guide</citetitle>.</member> + </simplelist> + </revdescription> + </revision> + + <revision> + <revnumber>2-3</revnumber> + <date>Tue May 26 2015</date> + <author> + <firstname>Stephen</firstname> + <surname>Wadeley</surname> + <email>swadeley@redhat.com</email> + </author> + <revdescription> + <simplelist> + <member>Fedora 22 release of the <citetitle>Networking Guide</citetitle>.</member> + </simplelist> + </revdescription> + </revision> + + <revision> + <revnumber>2-2</revnumber> + <date>Mon Mar 30 2015</date> + <author> + <firstname>Stephen</firstname> + <surname>Wadeley</surname> + <email>swadeley@redhat.com</email> + </author> + <revdescription> + <simplelist> + <member> + Added "Modifying a Static Ethernet Connection" to the Configure Networking chapter. + </member> + </simplelist> + </revdescription> + </revision> + + <revision> + <revnumber>2-1</revnumber> + <date>Fri Feb 6 2015</date> + <author> + <firstname>Stephen</firstname> + <surname>Wadeley</surname> + <email>swadeley@redhat.com</email> + </author> + <revdescription> + <simplelist> + <member> + Added "VLAN over a Bond" to the bonding chapter. + </member> + </simplelist> + </revdescription> + </revision> + + <revision> + <revnumber>2-0</revnumber> + <date>Tues Jan 6 2015</date> + <author> + <firstname>Stephen</firstname> + <surname>Wadeley</surname> + <email>swadeley@redhat.com</email> + </author> + <revdescription> + <simplelist> + <member> + Update for Fedora 21. + </member> + </simplelist> + </revdescription> + </revision> + + <revision> + <revnumber>1-1.2</revnumber> + <date>Mon Jan 5 2015</date> + <author> + <firstname>Stephen</firstname> + <surname>Wadeley</surname> + <email>swadeley@redhat.com</email> + </author> + <revdescription> + <simplelist> + <member> + General update and corrections for Fedora 20. + </member> + </simplelist> + </revdescription> + </revision> + + <revision> + <revnumber>1-1</revnumber> + <date>Fri Aug 1 2014</date> + <author> + <firstname>Stephen</firstname> + <surname>Wadeley</surname> + <email>swadeley@redhat.com</email> + </author> + <revdescription> + <simplelist> + <member> + First version of the Fedora Networking Guide. + </member> + </simplelist> + </revdescription> + </revision> + </revhistory> + </simpara> +</appendix> + |
