How Autoyast networking works in SLES9-SP2
==========================================

$Revision: 1.1.2.3 $ $Date: 2006/03/06 12:26:49 $ - work in progress!
Martin Vidner <mvidner@suse.cz>

Use case 1 - One ethernet card with DHCP
----------------------------------------

Probably the simplest case. Here is what one gets when configuring it
using the GUI:

    <networking>
      <dns>
        <dhcp_hostname config:type="boolean">false</dhcp_hostname>
        <dhcp_resolv config:type="boolean">true</dhcp_resolv>
        <domain>SuSE.Cz</domain>
        <hostname>Medusa</hostname>
      </dns>
      <interfaces config:type="list">
        <interface>
          <bootproto>dhcp</bootproto>
          <device>eth0</device>
          <startmode>onboot</startmode>
        </interface>
      </interfaces>
      <modules config:type="list">
        <module_entry>
          <device>static-0</device>
          <module></module>
          <options></options>
        </module_entry>
      </modules>
      <routing>
        <ip_forward config:type="boolean">true</ip_forward>
      </routing>
    </networking>

Here the contents of <device> entries do not matter - the resulting
configuration files are named using the MAC address and PCI bus
location (ifcfg-eth-id-00:00:1c:b5:70:7e, hwcfg-bus-pci-0000:00:0b.0).

(Note: I installed from a network installation source. So install.inf
was used. CD installation may behave differently)

Ideas from code reading
-----------------------

Autoinstall checks Hardware!=[] && interfaces != []. That will not
create config for a card that is not currently plugged in.


How it Works
------------

SP2: If <interfaces> is not empty (and Hardware is not empty, possible
bug), do autoinstallation configuration, otherwise do the installation
proposal, including routing and resolver.

SP3 (since 2.9.84): If <interfaces> is not empty, use it for
autoinstallation configuration, otherwise propose only the
interfaces. Routing and resolver will be taken from the profile in
both cases (see also bug #117484).

2.9.89: For each of <interfaces>, <routing><routes>, <dns><hostname>,
and <dns><nameservers>, if it is not empty, use it for
autoinstallation configuration, otherwise use the values from install.inf
(bug #153426).

  Autoinstallation
  ----------------

For each <interface>:
Find a device which matches it (complex rules, see below).
If we found a matching device, get the corresponding <module_entry>
(having equal <device>). If found, it overrides the detected settings,
else use the detected driver.
If we did not find a matching device, use driver settings from
install.inf. If there are none, don't set up the interface.
Set interface properties.

  Proposal
  --------

  Finding a Matching Device
  -------------------------

Let D be <interface/device>.
Look for the first match:
- (0) matching MAC for D being *-id-MAC
- (0) matching bus id for D being *-bus-BUS-ID (PCI and in SP3 VIO)
- (0) matching module (of first driver) for corresponding
      <module_entry/module> [a]

Then, when configuring the first interface:
- (1) matching MAC with install.inf
- (1) matching module (1st driver) with install.inf
- (1) first that has an active module
- (1) first that has a module

For subsequent interfaces, instead:
- (2) take the first device that does not have a configuration yet
      (checking only the default name, eg *-id-MAC, BTW how are the
      resulting configs named???) and has the same type (eth...) as
      <interface/device>.


[a]: If there are two devices with the same module, the first will be
picked, even if it has already been configured. That is why (2) exists
to overrule it. Unfortunately in SLES9 SP2, (2) also overrules the
other, unique, (0) selections (bug #119592#c9).
It has been "fixed" in SP3 in a broken way, to apply (2) only if (0)
did not match. This means that specifying two devices by bus ID will
work but specifying two devices with the same module can break (bug
#146965).

Why not just take what is written in the profile?
-------------------------------------------------

Currently YaST relies on some data that is obtained from hardware
detection, like the Unique ID from hwinfo. In the future it should be
possible to avoid that.

Notes
-----

<foo/bar> denotes the XML element bar that is under foo. Think of
XPath.

/etc/install.inf contains the parameters passed to YaST by linuxrc,
the text mode bootstrap program. linuxrc gets them from the kernel
command line or by asking the user.
