Commit 88dbf393 authored by Nikos Skalkotos's avatar Nikos Skalkotos
Browse files

Update the docs to reflect the latest changes made

parent f5e68537
......@@ -52,7 +52,8 @@ Although *diskdump* is a lot more flexible than the older formats, there are
still some rules to follow:
* For Linux:
* All block devices in ``/etc/fstab`` should be specified using persistent names (UUID or LABEL)
* All block devices in ``/etc/fstab`` should be specified using persistent
names (UUID or LABEL)
* LVM partitions are not supported
* Only ext{2,3,4} file systems are supported
* For FreeBSD:
......@@ -80,14 +81,20 @@ previously been generalized [#f1]_ with a command like this:
The pre-included Unattend.xml file that *snf-image* will by default install on
the VM's hard disk is this one:
.. literalinclude:: ../snf-image-helper/unattend.xml
.. literalinclude:: ../snf-image-host/unattend.xml.in
:language: xml
:emphasize-lines: 7,15-24
:linenos:
The file above is expected to work with all AMD64 releases (Server or Desktop)
of Microsoft Windows starting from version 6.1. The table below lists the
releases the developers have confirmed it to work with:
The file above is expected to work with all releases (Server or Desktop)
of Microsoft Windows starting from version 6.1. The ``@TIMEZONE@`` containers
you see are replaced by snf-image with the value of the *WINDOWS_TIMEZONE*
configuration variable during the deployment. Also, as you may have already
noticed, all *component* elements of the pre-included Unattend.xml are in 2
copies. One for *processorArchitecture* *amd64* and one for *x86*. This is done
in order to support both 32-bit and 64-bit versions of Windows using only one
file.
The table below lists the releases the developers have confirmed it to work
with:
+-------+----------------------+----------------------+
|Version|Marketing name | Editions |
......@@ -106,19 +113,44 @@ releases the developers have confirmed it to work with:
+-------+----------------------+----------------------+
Nevertheless, the user may want to use a custom Unattend.xml file that better
fits his needs. To do so, he can either update the *UNATTEND* configuration
parameter in ``/etc/default/snf-image`` to point to such a file in the host
system or put his copy of the file in the root directory of the image's
%SystemDrive% (*snf-image* will not install an Unattend.xml file if it is
already present in the image, unless *IGNORE_UNATTEND* image property is
defined). The latter is the recommended way to do it since it allows to provide
answer files in a per-image basis.
fits his needs. To do so, he can either use the *os_answer_file* OS parameter
during the deployment to specify one or put his copy of the file in the root
directory of the image's %SystemDrive%. *snf-image* will not install an
Unattend.xml file if it is already present in the image, unless
*IGNORE_UNATTEND* image property is defined.
Windows Legacy Deployment
+++++++++++++++++++++++++
For Windows OSes prior to Windows Vista, the System Preparation Tool (Sysprep)
utility is completely different than the one used on later versions. It is not
installed with the OS itself. It's located in the Windows product CD in the
``/Sypport/Tools/Deploy.cab`` file and needs to be extracted under the
``%SYSTEMDRIVE%\Sysprep`` folder by the user. The commands that needs to be
executed in order to put the system in a state ready for cloning looks like
this one:
.. code-block:: console
Sysprep -mini -quiet
The answer file which is typically called Sysprep.inf has an INI format. The
one *snf-image* hosts and will install under ``C:\Sysprep\Sysprep.inf`` is this
one:
.. warning::
When using custom Unattend.xml files, keep in mind that the highlighted
entries (lines 7 & 21-30) are crucial for *snf-image* to work. You may remove
or add settings in the file but the highlighted entries must be present.
.. literalinclude:: ../snf-image-host/sysprep.inf.in
:language: ini
The ``@TIMEZONE_INDEX@`` container will be replaced during the installation of
the file by the index value of the time zone which is specified through the
*WINDOWS_TIMEZONE* configuration variable. For more info check `here
<https://msdn.microsoft.com/en-us/library/ms912391%28v=winembedded.11%29.aspx>`_.
This file is known to work with Windows XP and in order for the deployment to
be completely unattended, the user must provide a Windows Product key using the
*os_product_key* OS parameter *snf-image* offers. As with the newer Windows
versions, the user is free to use his custom copy of *sysprep.inf* either by
putting it inside the image (under ``C:\Sysprep\Sysprep.inf``) or by using the
*os_answer_file* OS parameter.
Progress Monitoring Interface
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
......@@ -273,9 +305,11 @@ environment variables that are present when the configuration tasks run.
| |parameter (see :ref:`Configuration Parameters |
| |<configuration-parameters>`) |
+---------------------+-------------------------------------------------------+
|UNATTEND |The value of the UNATTED configuration parameter (see |
| |:ref:`Configuration Parameters |
| |<configuration-parameters>`) |
|UNATTEND |The path to the Windows setup answer file |
| |(Unattend.xml) |
+---------------------+-------------------------------------------------------+
|SYSPREPINF |The path to the Windows legacy setup answer file |
| |(sysprep.inf) |
+---------------------+-------------------------------------------------------+
.. [#] all environment variable names are prefixed with *SNF_IMAGE_*
......@@ -297,7 +331,6 @@ executable should make use of the :ref:`Configuration Tasks Environment
configuration tasks that run while the image is mounted (have a priority
between 31 and 79).
Return Code and post execution
++++++++++++++++++++++++++++++
......
......@@ -41,6 +41,20 @@ some external programs in ``/etc/default/snf-image``:
# HELPER_MEMORY: Virtual RAM size in megabytes to be given to the helper VM.
# HELPER_MEMORY="512"
# HELPER_DEBUG: When enabled, the helper VM will drop to a root shell
# whenever a task fails. This allows the administrator or a developer
# to examine its internal state for debugging purposes.
# To access the shell, use a program like 'minicom' to connect to /dev/pts/X on
# the host, where /dev/pts/X is the name of the device reported in the Ganeti
# OS installation logs for helper's 3rd serial port, e.g.,
# "char device redirected to /dev/pts/9 (label serial3)".
# This feature is KVM-specific for the time being.
# For HELPER_DEBUG to be useful, you also need to set HELPER_SOFT_TIMEOUT
# to a much higher value.
# WARNING: DO NOT ENABLE THIS FEATURE IN PRODUCTION. Every failure to deploy
# an Image will cause the helper VM to hang.
# HELPER_DEBUG="no"
# MULTISTRAP_CONFIG: Configuration file to be used with multistrap to create
# the rootfs of the helper image.
# MULTISTRAP_CONFIG="/etc/snf-image/multistrap.conf"
......@@ -52,6 +66,12 @@ some external programs in ``/etc/default/snf-image``:
# XEN_SCRIPTS_DIR: Directory where the Xen scripts are stored
# XEN_SCRIPTS_DIR="/etc/xen/scripts"
# XEN_CMD: This variable specifies the Xen CLI tool snf-image should use. This
# depends on the XEN version and configuration and should probably coincide
# with the Ganeti's xen_cmd hypervisor parameter for xen-hvm or xen-pvm. Right
# now the supported ones are 'xm' and 'xl'.
# XEN_CMD="xl"
# PITHOS_DB: Pithos database in SQLAlchemy format
# PITHOS_DB="sqlite://///var/lib/pithos/backend.db"
......@@ -101,14 +121,24 @@ some external programs in ``/etc/default/snf-image``:
# will configure a VM's NIC to perform SLAAC and Stateless DHCPv6 if the card
# is expected to have an IPv6 address and any of those tags is present in the
# card's NETWORK_TAGS variable.
# STATELESS_DHCPV6_TAGS="nfdhcpd stateless_dhcpv6
# STATELESS_DHCPV6_TAGS="nfdhcpd stateless_dhcpv6"
# UNATTEND: This variable overwrites the unattend.xml file used when deploying
# a Windows image. snf-image-helper will use its own unattend.xml file if this
# variable is empty. Please leave this empty, unless you really know what you
# are doing.
# variable is empty.
# WARNING: This variable is DEPRECATED. If you need to define an answer file
# different that the one shipped with snf-image, which is very likely, put it
# inside the image or use the os_answer_file OS parameter.
# UNATTEND=""
# WINDOWS_TIMEZONE: This variable is used to specify the time zone when
# deploying a Windows image. This will only work if you are using snf-image's
# default OS answer file. If the Windows image already contains an answer file
# or the os_answer_file OS parameter is used to define one, this variable will
# be completely ignored. For a list of available time zones, check here:
# https://msdn.microsoft.com/en-us/library/ms912391%28v=winembedded.11%29.aspx
# WINDOWS_TIMEZONE="GMT Standard Time"
# Paths for needed programs. Uncomment and change the variables below if you
# don't want to use the default one.
# MD5SUM="md5sum"
......@@ -140,8 +170,9 @@ The most common configuration parameters the user may need to overwrite are:
* **STATELESS_DHCPV6_TAGS**: To specify which Ganeti networks support SLAAC
and stateless DHCPv6
* **STATEFUL_DHCPV6_TAGS**: To specify which Ganeti networks support DHCPv6
* **UNATTEND**: To specify a custom Unattend.xml file to use on Windows
instead of the default one
* **WINDOWS_TIMEZONE**: To specify a time zone to use when deploying Windows
images that do not host an Unattend.xml file and depend on the one provided
by *snf-image*.
Paths of external programs
^^^^^^^^^^^^^^^^^^^^^^^^^^
......
......@@ -29,7 +29,7 @@ successfully deploy many major Linux distributions (Debian, Ubuntu/Kubuntu,
CentOS, Fedora, OpenSUSE, Slackware, Arch Linux, CoreOS), Windows Server
flavors (2008 R2, 2012, 20012 R2), as well as BSD systems (FreeBSD, OpenBSD,
NetBSD). It is also known to work well with current Desktop versions of Windows
(7, 8, 8.1).
(7, 8, 8.1) as well as Windows XP.
The snf-image Ganeti OS Definition is released under
`GPLv2 <http://www.gnu.org/licenses/gpl-2.0.html>`_.
......
......@@ -20,6 +20,10 @@ following OS Parameters:
* **img_personality** (optional): files to be injected into the image's file
system (:ref:`details <image-personality>`)
* **config_url** (optional): the URL to download configuration data from
* **os_product_key** (optional): a product key to be used to license a Windows
deployment (windows-only)
* **os_answer_file** (optional): an answer file used by Windows to automate
the setup process, instead the default one (windows-only)
.. _image-format:
......@@ -129,8 +133,9 @@ A list of all properties follows:
Diskdump only properties
++++++++++++++++++++++++
* **OSFAMILY=linux|windows|freebsd|netbsd|openbsd**
This specifies whether the image is a Linux, a Windows or a \*BSD Image.
* **OSFAMILY=linux|windows|windows-legacy|freebsd|netbsd|openbsd**
This specifies whether the image is a Linux, a Windows or a \*BSD Image. For
Windows OSes prior to Vista, *windows-legacy* should be used.
*{ext,ntfs}dump* formats are self descriptive regarding this property.
* **ROOT_PARTITION=n**
This specifies the partition number of the root partition. As mentioned
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment