diff options
| -rw-r--r-- | debian/changelog | 6 | ||||
| -rw-r--r-- | en/appendix/preseed.xml | 349 |
2 files changed, 225 insertions, 130 deletions
diff --git a/debian/changelog b/debian/changelog index 0ed4ef844..3ad82052a 100644 --- a/debian/changelog +++ b/debian/changelog @@ -72,7 +72,11 @@ installation-guide (2006xxxx) UNRELEASED; urgency=low * Clarify how -- affects which parameters end up in the target system's bootloader's command line. - -- Frans Pop <fjp@debian.org> Sat, 28 Oct 2006 23:31:16 +0200 + [ Joey Hess ] + * Applied Phil's auto mode documentation patch, edited it, and moved + some things around for clarity. Closes: #395910 + + -- Joey Hess <joeyh@debian.org> Mon, 30 Oct 2006 15:24:06 -0500 installation-guide (20060726) unstable; urgency=low diff --git a/en/appendix/preseed.xml b/en/appendix/preseed.xml index 1f8b9aa9b..8c6dc1451 100644 --- a/en/appendix/preseed.xml +++ b/en/appendix/preseed.xml @@ -17,8 +17,8 @@ Currently only a single variant of the example file is generated (for i386). <para> -This appendix explains the intricacies of preseeding answers to questions in -&d-i; to automate your installation. +This appendix explains how to preseed answers to questions in &d-i; to +automate your installation. </para><para> @@ -48,9 +48,7 @@ There are three methods that can be used for preseeding: <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 @@ installation methods. <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 @@ installation methods. <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,23 @@ configured. </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. +Obviously, any questions that have been processed before the +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><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. +In order to avoid the questions that would normally appear before the +preseeding occurs, you can start the installer in <quote>auto</quote> mode +by entering <userinput>auto</userinput> and parameters to indicate the +source of the preseed file, at the boot prompt. This delays questions that +would normally be asked too early for preseeding (i.e. language, country +and keyboard selection) until after the network comes up, thus allowing +them to be preseeded. It also runs the installation in crtitical priority, +which avoids many unimportant questions. See <xref linkend="preseed-auto"/> +for details. </para> </sect2> @@ -203,61 +206,20 @@ are stored in a separate, non-readable file in the same directory. </sect2> --> - <sect2 id="preseed-hooks"> - <title>Running custom commands during the installation</title> -<para> - -A very powerful and flexible option offered by the preconfiguration tools -is the ability to run commands or scripts at certain points in the -installation. See <xref linkend="preseed-shell"/> for details. - -</para> - -<itemizedlist> -<listitem><para> - <userinput>preseed/early_command</userinput>: is run as soon as the - preconfiguration file has been loaded -</para></listitem> -<listitem><para> - <userinput>preseed/late_command</userinput>: is run just before the reboot - at the end of the install, but before the <filename>/target</filename> - filesystem has been unmounted -</para></listitem> -</itemizedlist> - - </sect2> - - <sect2 id="preseed-seenflag"> - <title>Using preseeding to change default values</title> -<para> - -It is possible to use preseeding to change the default answer for a -question, but still have the question asked. To do this the -<firstterm>seen</firstterm> flag must be reset to <quote>false</quote> after -setting the value for a question. - -</para> - -<informalexample><screen> -d-i foo/bar string value -d-i foo/bar seen false -</screen></informalexample> - - </sect2> </sect1> <sect1 id="preseed-using"> <title>Using preseeding</title> <para> -Of course you will first need to create a preconfiguration file and place it in -the location from where you want to use it. Creating the preconfiguration file -is covered later in this appendix. Putting it in the correct location is fairly -straightforward for network preseeding or if you want to read the file off -a floppy or usb-stick. If you want to include the file on a CD or DVD, you -will have to remaster the ISO image. How to get the preconfiguration file -included in the initrd is outside the scope of this document; please consult -the developers documentation for &d-i;. +You will first need to create a preconfiguration file and place it in the +location from where you want to use it. Creating the preconfiguration file +is covered later in this appendix. Putting it in the correct location is +fairly straightforward for network preseeding or if you want to read the +file off a floppy or usb-stick. If you want to include the file on a CD or +DVD, you will have to remaster the ISO image. How to get the +preconfiguration file included in the initrd is outside the scope of this +document; please consult the developers documentation for &d-i;. </para><para> @@ -322,75 +284,27 @@ Note that <filename>preseed/url</filename> can be shortened to just <filename>url</filename> and <filename>preseed/file</filename> to just <filename>file</filename> when they are passed as boot parameters. -</para><para> - -While you're at it, you may want to add a boot parameter -<userinput>priority=critical</userinput>. This will avoid most -questions even if the preseeding below misses some. - </para> </sect2> - <sect2 id="preseed-dhcp"> - <title>Using a DHCP server to specify preconfiguration files</title> -<para> - -It's also possible to use DHCP to specify a preconfiguration file to download -from the network. DHCP allows specifying a filename. Normally this is a file -to netboot, but if it appears to be an URL then installation media that -support network preseeding will download the file from the URL and use it as a -preconfiguration file. Here is an example of how to set it up in the dhcpd.conf -for version 3 of the ISC DHCP server (the dhcp3-server Debian package). - -</para> - -<informalexample><screen> -if substring (option vendor-class-identifier, 0, 3) = "d-i" { - filename "http://host/preseed.cfg"; -} -</screen></informalexample> - -<para> - -Note that the above example limits this filename to DHCP clients that identify -themselves as "d-i", so it will not affect regular DHCP clients, but only -the installer. You can also put the text in a stanza for only one particular -host to avoid preseeding all installs on your network. - -</para><para> - -A good way to use the DHCP preseeding is to only preseed values specific to -your network, such as the Debian mirror to use. This way installs on your -network will automatically get a good mirror selected, but the rest of the -installation can be performed interactively. Using DHCP preseeding to fully -automate Debian installs should only be done with care. - -</para> - </sect2> - <sect2 id="preseed-bootparms"> <title>Using boot parameters to supplement preseeding</title> <para> -Some parts of the installation process cannot be automated using some forms -of preseeding because the questions are asked before the preconfiguration -file is loaded. For example, if the preconfiguration file is downloaded over -the network, the network setup must be done first. One reason to use initrd -preseeding is that it allows preseeding of even these early steps of the -installation process. +If a preconfiguration file cannot be used to preseed some steps, the +install can still be fully automated, since you can pass preseed values on +the command line when booting the installer. Just pass +<userinput>path/to/var=value</userinput> for any of the preseed variables +listed in the examples. </para><para> -If a preconfiguration file cannot be used to preseed some steps, the install -can still be fully automated, since you can pass preseed values to the kernel -on the command line. Just pass <userinput>path/to/var=value</userinput> -for any of the preseed variables listed in the examples. - -</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> @@ -423,6 +337,146 @@ parameters, even if you delimit them with quotes. </para></note> </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 preseed 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> + +If there is no local DHCP or DNS infrastructure, or if you +do not want to use the default path to the preseed.cfg, you 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 periods, 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, you 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 defined 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 its +DHCP query. + +</para> + </sect2> + + + <sect2 id="preseed-dhcp"> + <title>Using a DHCP server to specify preconfiguration files</title> +<para> + +It's also possible to use DHCP to specify a preconfiguration file to download +from the network. DHCP allows specifying a filename. Normally this is a file +to netboot, but if it appears to be an URL then installation media that +support network preseeding will download the file from the URL and use it as a +preconfiguration file. Here is an example of how to set it up in the dhcpd.conf +for version 3 of the ISC DHCP server (the dhcp3-server Debian package). + +</para> + +<informalexample><screen> +if substring (option vendor-class-identifier, 0, 3) = "d-i" { + filename "http://host/preseed.cfg"; +} +</screen></informalexample> + +<para> + +Note that the above example limits this filename to DHCP clients that identify +themselves as "d-i", so it will not affect regular DHCP clients, but only +the installer. You can also put the text in a stanza for only one particular +host to avoid preseeding all installs on your network. + +</para><para> + +A good way to use the DHCP preseeding is to only preseed values specific to +your network, such as the Debian mirror to use. This way installs on your +network will automatically get a good mirror selected, but the rest of the +installation can be performed interactively. Using DHCP preseeding to fully +automate Debian installs should only be done with care. + +</para> + </sect2> </sect1> <sect1 id="preseed-creating"> @@ -1188,8 +1242,15 @@ xserver-xorg xserver-xorg/config/monitor/mode-list \ <sect1 id="preseed-advanced"> <title>Advanced options</title> - <sect2 id="preseed-shell"> - <title>Shell commands</title> + <sect2 id="preseed-hooks"> + <title>Running custom commands during the installation</title> +<para> + +A very powerful and flexible option offered by the preconfiguration tools +is the ability to run commands or scripts at certain points in the +installation. + +</para> <informalexample role="example"><screen> # d-i preseeding is inherently not secure. Nothing in the installer checks @@ -1211,6 +1272,24 @@ xserver-xorg xserver-xorg/config/monitor/mode-list \ </screen></informalexample> </sect2> + + <sect2 id="preseed-seenflag"> + <title>Using preseeding to change default values</title> +<para> + +It is possible to use preseeding to change the default answer for a +question, but still have the question asked. To do this the +<firstterm>seen</firstterm> flag must be reset to <quote>false</quote> after +setting the value for a question. + +</para> + +<informalexample><screen> +d-i foo/bar string value +d-i foo/bar seen false +</screen></informalexample> + + </sect2> <sect2 id="preseed-chainload"> <title>Chainloading preconfiguration files</title> @@ -1225,7 +1304,7 @@ settings for certain configurations in other files. </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. @@ -1248,6 +1327,18 @@ settings for certain configurations in other files. 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. You need to be careful when doing this, since there will be two +distinct runs at preseeding, meaning for example that you get another +chance to run the preseed/early command, the second one happening after the +network comes up. + +</para> + </sect2> </sect1> </appendix> |