Bug#395910: debian-installer-manual: add auto mode section, and update info about network preseeding
Package: debian-installer-manual
Severity: normal
This is a first attempt at documenting the auto mode and auto-install
It also updates the stuff about network preseeding to reflect the fact
that you can chain into network preseeding by setting preseed/url in an
earlier preseed, as long as you're not trying a stand-alone networkless
install, obviously.
Related to this, we should probably have a section that includes the
preseed_aliases file amd documents it, so that we can add references to
that section where needed.
Cheers, Phil.
Index: en/appendix/preseed.xml
===================================================================
--- en/appendix/preseed.xml (revision 42292)
+++ en/appendix/preseed.xml (working copy)
@@ -48,9 +48,7 @@
<firstterm>network</firstterm>. Initrd preseeding will work with any
installation method and supports preseeding of more things, but it requires
the most preparation. File and network preseeding each can be used with
-different installation methods. With file and network preseeding the first
-few installer questions cannot be preseeded because the preconfiguration
-file is only loaded after they have been asked.
+different installation methods.
</para><para>
@@ -71,7 +69,8 @@
<entry>CD/DVD</entry>
<entry>yes</entry>
<entry>yes</entry>
- <entry>no</entry>
+ <entry>yes<footnote id='apx-ps-net'><para>
+ but only if you have network access, and set preseed/url appropriately</para></footnote></entry>
</row><row>
<entry>netboot</entry>
<entry>yes</entry>
@@ -81,12 +80,12 @@
<entry>hd-media <phrase condition="bootable-usb">(including usb-stick)</phrase></entry>
<entry>yes</entry>
<entry>yes</entry>
- <entry>no</entry>
+ <entry>yes<footnoteref linkend='apx-ps-net'/></entry>
</row><row condition="supports-floppy-boot">
<entry>floppy based (cd-drivers)</entry>
<entry>yes</entry>
<entry>yes</entry>
- <entry>no</entry>
+ <entry>yes<footnoteref linkend='apx-ps-net'/></entry>
</row><row condition="supports-floppy-boot">
<entry>floppy based (net-drivers)</entry>
<entry>yes</entry>
@@ -113,19 +112,28 @@
</para><para>
-In practical terms this means for file and network preseeding that the
-questions about language, country and keyboard selection will already have
-been asked. For network preseeding add to that any questions related to
-network configuration. Some other questions that are only displayed
-at medium or low priority (like the first hardware detection run) will
-also already have been processed.
+In order to facilitate preseeding of the questions that would normally
+appear before the file or network preseeding occur, one can start the
+installer in <quote>auto</quote> mode by entering
+<userinput>auto</userinput> and parameters to indicate the source of
+the preseed file, as required, at the boot prompt. This sets
+auto-install/enabled=true for you, which results in questions that
+would normally be asked too early for preseeding (i.e. language,
+country and keyboard selection) to be delayed until after the network
+comes up, thus allowing them to be preseeded then. Of course, if you
+need to set the up network with static IP address, that will still
+need to be done either by hand, or by specifying these settings via
+one of the methods that are available before the network is used (at
+the boot prompt, or via initrd, file preseeding or perhaps via DHCP).
+<quote>auto</quote> mode also sets debconf/priority=critical for you.
</para><para>
Obviously, any questions that have been processed before the
-preconfiguration file is loaded cannot be preseeded.
-<xref linkend="preseed-bootparms"/> offers a way to avoid these
-questions being asked.
+preconfiguration file is loaded cannot be preseeded (this will include
+questions that are only displayed at medium or low priority, like the
+first hardware detection run). <xref linkend="preseed-bootparms"/>
+offers a way to avoid these questions being asked.
</para>
</sect2>
@@ -324,8 +332,9 @@
</para><para>
-While you're at it, you may want to add a boot parameter
-<userinput>priority=critical</userinput>. This will avoid most
+While you're at it, you may want to take advantage of <xref
+linkend="preseed-auto"/>, which adds a boot parameter
+<userinput>priority=critical</userinput> for you. This will avoid most
questions even if the preseeding below misses some.
</para>
@@ -368,6 +377,108 @@
</para>
</sect2>
+ <sect2 id="preseed-auto">
+ <title>Auto mode</title>
+<para>
+
+There are several features of Debian-installer that combine to allow
+fairly simple command lines at the boot prompt to result in
+arbitrarily complex customised automatic installs. To illustrate
+this, here are some examples that can be used at the boot prompt:
+
+<informalexample><screen>
+ auto url=autoserver
+</screen></informalexample>
+
+This relies on there being a DHCP server that will get the machine to
+the point where <literal>autoserver</literal> can be resolved by DNS,
+perhaps after adding the local domain if that was provided by DHCP.
+If this was done at a site where the domain is
+<literal>example.com</literal>, and they have a reasonably sane DHCP
+setup, it would result in the preseed file being retrieved from
+<literal>http://autoserver.example.com/d-i/etch/./preseed.cfg</literal>.
+The the path segment of that comes from
+<literal>auto-install/defaultroot</literal>, which includes the
+directory <literal>etch</literal> by default to allow future versions
+to specify their own codename to let people migrate forwards in a
+controlled manner. The <literal>/./</literal> bit is used to indicate
+a root relative to which subsequent paths can be anchored (for use in
+preseed/include and presseed/run). This allows files to be specified
+either as full URLs, paths starting with / that are thus anchored, or
+even paths relative to the location where the last freseed file was
+found. This can be used to construct more portable scripts where an
+entire hierarchy of scripts can be moved to a new location without
+breaking it, for example copying the files onto a USB stick when they
+started out on a web server. In this example, if the preseed file
+sets <literal>preseed/run</literal> to
+<literal>/scripts/late_command.sh</literal> then the file will be
+fetched from
+<literal>http://autoserver.example.com/d-i/etch/./scripts/late_command.sh</literal>.
+
+</para><para>
+
+Of course, if there is no local DHCP or DNS infrastructure, or if you
+do not want to use the default path to the preseed.cfg, one can still
+use an explicit url, and if you don't use the <literal>/./</literal>
+element it will be anchored to the start of the path (i.e. the third /
+in the URL). Here is an example that requires minimal support from
+the local network infrastructure:
+
+<informalexample><screen>
+ auto url=http://192.168.1.2/path/to/mypreseed.file
+</screen></informalexample>
+
+The way this works is that if the URL is missing a protocol, http is
+assumed, if the hostname section had no full-stops, it has the domain
+derived from DHCP appended to it, and if there's no /'s after the
+hostname, then the default path is added.
+
+</para><para>
+
+In addition to specifying the url, one can also specify settings that
+do not directly affect the behavior of debian-installer itself, but
+can be passed through to any scripts that might be specified
+preseed/run settings in the loaded preseed file. At present, the only
+example of this is <literal>auto-install/classes</literal>, which has
+an alias <literal>classes</literal>. This can be used thus:
+
+<informalexample><screen>
+ auto url=hands.com classes=xen3
+</screen></informalexample>
+
+refer to http://hands.com/d-i/ for more details how this example
+works. If you want to come up with other paradigms, it is reasonable
+to use the auto-install namespace for this, so one might have
+something like <literal>auto-install/style</literal> which is then
+used in your scripts. If you feel the need to do this, please mention
+it to the debian-boot mailing list so that we can avoid namespace
+conflicts, and perhaps add a preseed_alias for you.
+
+</para><para>
+
+The <literal>auto</literal> boot label is not yet definied on all
+architectures. The same effect may be achieved by simply adding the
+two settings <literal>auto=true priority=critical</literal> to the
+kernel command line yourself to achieve the same effect. The
+<literal>auto</literal> is an alias for
+<literal>auto-install/enabled</literal> and controls the delay of the
+locale and keyboard questions until after there has been a chance to
+preseed them, while <literal>priority</literal> is an alias for
+<literal>preseed/priority</literal> and setting it to
+<literal>critical</literal> stops any questions with a lower priority
+from being asked.
+
+</para><para>
+
+Additional options that may be of interest while attempting to
+automate an install while using DHCP are: <literal>interface=auto
+netcfg/dhcp_timeout=60</literal> which makes the machine choose the
+first viable NIC and be more patient about getting a reply to it's
+DHCP query.
+
+</para>
+ </sect2>
+
<sect2 id="preseed-bootparms">
<title>Using boot parameters to supplement preseeding</title>
<para>
@@ -388,9 +499,12 @@
</para><para>
-Note that some variables that are frequently set at the boot prompt have a
-shorter alias. If an alias is available, it is used in the examples in
-this appendix instead of the full variable.
+Note that some variables that are frequently set at the boot prompt
+have a shorter alias. If an alias is available, it is used in the
+examples in this appendix instead of the full variable. In
+particular, the <literal>preseed/url</literal> variable has been
+aliased as <literal>url</literal> and has some extra magic to allow
+shortened urls to be used.
</para><para>
@@ -1226,7 +1340,7 @@
</para>
<informalexample><screen>
-# More that one file can be listed, separated by spaces; all will be
+# More than one file can be listed, separated by spaces; all will be
# loaded. The included files can have preseed/include directives of their
# own as well. Note that if the filenames are relative, they are taken from
# the same directory as the preconfiguration file that includes them.
@@ -1249,6 +1363,19 @@
d-i preseed/run string foo.sh
</screen></informalexample>
+<para>
+
+It is also possible to chainload from the initrd or file preseeding
+phase, into networking preseeding by setting preseed/url in the earlier
+files. This will cause network preseeding to be performed when the
+network comes up. One needs to be careful in one's assumptions when
+doing this, since there will be two distinct runs at preseeding,
+meaning for example that one gets another chance to run the
+preseed/early command, the second one happening after the network
+comes up.
+
+</para>
+
</sect2>
</sect1>
</appendix>
Reply to: