Commit 10217957 authored by Nikos Skalkotos's avatar Nikos Skalkotos
Browse files

Merge branch 'master' into debian-trusty

parents c34760b0 0a613f84
2016-07-20, v0.19.1
* Add "auto" to the known Linux file systems
2016-01-28, v0.19
* Support Windows XP/2003 (windows-legacy OSFAMILY)
* Support 32-bit versions of Windows
* Add new os_product_key and os_answer_file OS parameters
* Allow offline resizing for NTFS
* Cleanup the default Unattend.xml file
* Allow defining the Windows time zone in the default Unattend.xml file
* Add new image configuration task that executes user defined code
* Allow the image itself to overwrite configuration tasks that run
during deployment when the image is mounted
* Support Ed24419 ssh keys
* Support making swap in secondary disk
* Strip down the helper kernel (reduces helper image size)
* Support Debian Jessie helpers
* Fix bugs and cleanup the code
* Update the documentation
2015-03-13, v0.18.1
* HELPER: Fix a bug in ConfigureNetwork task that caused a syntax error
if the SUBNET was missing for a NIC
2015-03-03, v0.18
* HELPER: Auto-detect OSFAMILY and ROOT_PARTITION properties if missing
* HELPER: Add new CofigureNetwork image configuration task
......
......@@ -24,7 +24,7 @@ for more information.
Copyright and license
=====================
Copyright (C) 2011-2014 GRNET S.A.
Copyright (C) 2011-2016 GRNET S.A. and individual contributors.
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
......
......@@ -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,21-30
: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
.. 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.
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:
.. 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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
......@@ -214,6 +246,104 @@ like this:
``{"subtype": "error", "type": "image-helper", "messages": ["The image contains a(n) MSDOS partition table. For FreeBSD images only GUID Partition Tables are supported."], "timestamp": 1379507910.799365}``
.. _configuration-tasks-environment:
Configuration Tasks Enviroment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When an *snf-image-helper* configuration task runs, it expects to find the
required information in its environment. In the table below we describe the
environment variables that are present when the configuration tasks run.
+---------------------+-------------------------------------------------------+
|Name [#]_ |Details |
+=====================+=======================================================+
|DEV_COUNT |The number of the instance's disks. |
+---------------------+-------------------------------------------------------+
|DEV_%N |The device file of the Nth disk. |
+---------------------+-------------------------------------------------------+
|DEV |The device file of the first disk (we keep this for |
| |backward compatibility) |
+---------------------+-------------------------------------------------------+
|PERSONALITY |The value of the img_personality OS parameter. |
+---------------------+-------------------------------------------------------+
|HOSTNAME |The instance's name. |
+---------------------+-------------------------------------------------------+
|PASSWD |The value of the img_passwd OS parameter. |
+---------------------+-------------------------------------------------------+
|PASSWD_HASH |The value of the img_passwd_hash OS parameter. |
+---------------------+-------------------------------------------------------+
|OS_PRODUCT_KEY |The value of the os_product_key parameter. |
+---------------------+-------------------------------------------------------+
|PROPERTY_* |The value of a specific image property that was |
| |specified in json through the img_properties OS |
| |parameter. |
+---------------------+-------------------------------------------------------+
|RESIZE_PART |The number of the partition that will be enlarged. |
+---------------------+-------------------------------------------------------+
|TARGET |The directory the instance's file systems are mounted |
| |under. |
+---------------------+-------------------------------------------------------+
|NIC_COUNT |The number of network interface controllers of the |
| |instance. |
+---------------------+-------------------------------------------------------+
|NIC_%N_* |The Ganeti provided environment variable for the Nth |
| |network interface controller. Check |
| |`here <http://docs.ganeti.org/ganeti/current/man/ganeti|
| |-os-interface.html>`_ |
+---------------------+-------------------------------------------------------+
|DHCP_TAGS |The value of the DHCP_TAGS configuration parameter (see|
| |:ref:`Configuration Parameters |
| |<configuration-parameters>`) |
+---------------------+-------------------------------------------------------+
|STATEFUL_DHCPV6_TAGS |The value of the STATEFUL_DHCPV6_TAGS configuration |
| |parameter (see :ref:`Configuration Parameters |
| |<configuration-parameters>`) |
+---------------------+-------------------------------------------------------+
|STATELESS_DHCPV6_TAGS|The value of the STATELESS_DHCPV6_TAGS 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_*
.. _overwriting-configuration-tasks:
Overwriting Configuration Tasks
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
One way to extend snf-image to work on images that are not directly supported
by it, is the overwriting mechanism for the :ref:`configuration tasks
<image-configuration-tasks>`. If the ``ALLOW_MOUNTED_TASK_OVERWRITING`` image
property is defined with yes, then the presence of an executable under the path
``/root/snf-image/helper/overwrite_task_<TASK>`` inside the image's file system
will make *snf-image-helper* interrupt the execution of the actual
configuration task and the image's file will be executed instead. This
executable should make use of the :ref:`Configuration Tasks Environment
<configuration-tasks-environment>`. Also keep in mind that this only works for
configuration tasks that run while the image is mounted (have a priority
between 31 and 79).
Return Code and post execution
++++++++++++++++++++++++++++++
If the return code of the execution of the image-defined executable is
non-zero, *snf-image* will translate this as a failure of the configuration
task. The only exception to this is the return code **101**, which will make
*snf-image* execute the original configuration task and then the image's
executable once again. The first time the image's executable will be called
with **pre-exec** as its first argument and the second with **post-exec**. This
way the executable itself can decide if it is going to be executed in
conjunction with the original configuration task and in which order (before,
after or in both cases).
.. rubric:: Footnotes
.. [#f1] http://technet.microsoft.com/en-us/library/hh824938.aspx
......@@ -215,49 +215,55 @@ will fail.
missing a warning is produced. Only *SNF_IMAGE_TARGET* is required for this
task to run.
**RunCustomTask**: Run a user-defined task specified by the
*SNF_IMAGE_PROPERTY_CUSTOM_TASK* variable. If the variable is missing or empty,
a warning is produced.
**UmountImage**: Umounts the file systems previously mounted by MountImage. The
only environment variable required is *SNF_IMAGE_TARGET*.
+-------------------------------+---+--------------------------------------------+-------------------------------------------+
| | | Dependencies | Enviromental Variables [#]_ |
+ Name | +------------------+-------------------------+-------------------------+-----------------+
| |Pr.| Run-After | Run-Before | Required | Optional |
+===============================+===+==================+=========================+=========================+=================+
|FixPartitionTable |10 | |FilesystemResizeUnmounted|DEV | |
+-------------------------------+---+------------------+-------------------------+-------------------------+-----------------+
|FilesystemResizeUnmounted |20 |FixPartitionTable |MountImage |DEV | |
+-------------------------------+---+------------------+-------------------------+-------------------------+-----------------+
|MountImage |30 | |UmountImage |DEV | |
| | | | |TARGET | |
| | | | |PROPERTY_ROOT_PARTITION | |
+-------------------------------+---+------------------+-------------------------+-------------------------+-----------------+
|AddSwap |40 |MountImage |EnforcePersonality |TARGET |PROPERTY_OSFAMILY|
| | | | | |PROPERTY_SWAP |
+-------------------------------+---+------------------+-------------------------+-------------------------+-----------------+
|DeleteSSHKeys |40 |MountImage |EnforcePersonality |TARGET |PROPERTY_OSFAMILY|
+-------------------------------+---+------------------+-------------------------+-------------------------+-----------------+
|DisableRemoteDesktopConnections|40 |EnforcePersonality|UmountImage |TARGET |PROPERTY_OSFAMILY|
+-------------------------------+---+------------------+-------------------------+-------------------------+-----------------+
|InstallUnattend |40 |MountImage |EnforcePersonality |TARGET |PROPERTY_OSFAMILY|
+-------------------------------+---+------------------+-------------------------+-------------------------+-----------------+
|SELinuxAutorelabel |40 |MountImage |EnforcePersonality |TARGET |PROPERTY_OSFAMILY|
+-------------------------------+---+------------------+-------------------------+-------------------------+-----------------+
|AssignHostname |50 |InstallUnattend |EnforcePersonality |TARGET | |
| | | | |HOSTNAME |PROPERTY_OSFAMILY|
+-------------------------------+---+------------------+-------------------------+-------------------------+-----------------+
|ChangePassword |50 |InstallUnattend |EnforcePersonality |TARGET |PROPERTY_USERS |
| | | | | |PROPERTY_OSFAMILY|
| | | | | |PASSWD |
+-------------------------------+---+------------------+-------------------------+-------------------------+-----------------+
|ConfigureNetwork |50 |InstallUnattend |EnforcePersonality |TARGET |NIC_* |
+-------------------------------+---+------------------+-------------------------+-------------------------+-----------------+
|FilesystemResizeMounted |50 |InstallUnattend |EnforcePersonality |TARGET |PROPERTY_OSFAMILY|
+-------------------------------+---+------------------+-------------------------+-------------------------+-----------------+
|EnforcePersonality |60 |MountImage |UmountImage |TARGET |PERSONALITY |
| | | | | |PROPERTY_OSFAMILY|
+-------------------------------+---+------------------+-------------------------+-------------------------+-----------------+
|UmountImage |80 |MountImage | |TARGET | |
+-------------------------------+---+------------------+-------------------------+-------------------------+-----------------+
+-------------------------------+---+--------------------------------------------+----------------------------------------------+
| | | Dependencies | Environment Variables [#]_ |
+ Name | +------------------+-------------------------+-------------------------+--------------------+
| |Pr.| Run-After | Run-Before | Required | Optional |
+===============================+===+==================+=========================+=========================+====================+
|FixPartitionTable |10 | |FilesystemResizeUnmounted|DEV | |
+-------------------------------+---+------------------+-------------------------+-------------------------+--------------------+
|FilesystemResizeUnmounted |20 |FixPartitionTable |MountImage |DEV | |
+-------------------------------+---+------------------+-------------------------+-------------------------+--------------------+
|MountImage |30 | |UmountImage |DEV | |
| | | | |TARGET | |
| | | | |PROPERTY_ROOT_PARTITION | |
+-------------------------------+---+------------------+-------------------------+-------------------------+--------------------+
|AddSwap |40 |MountImage |EnforcePersonality |TARGET |PROPERTY_OSFAMILY |
| | | | | |PROPERTY_SWAP |
+-------------------------------+---+------------------+-------------------------+-------------------------+--------------------+
|DeleteSSHKeys |40 |MountImage |EnforcePersonality |TARGET |PROPERTY_OSFAMILY |
+-------------------------------+---+------------------+-------------------------+-------------------------+--------------------+
|DisableRemoteDesktopConnections|40 |EnforcePersonality|UmountImage |TARGET |PROPERTY_OSFAMILY |
+-------------------------------+---+------------------+-------------------------+-------------------------+--------------------+
|InstallUnattend |40 |MountImage |EnforcePersonality |TARGET |PROPERTY_OSFAMILY |
+-------------------------------+---+------------------+-------------------------+-------------------------+--------------------+
|SELinuxAutorelabel |40 |MountImage |EnforcePersonality |TARGET |PROPERTY_OSFAMILY |
+-------------------------------+---+------------------+-------------------------+-------------------------+--------------------+
|AssignHostname |50 |InstallUnattend |EnforcePersonality |TARGET | |
| | | | |HOSTNAME |PROPERTY_OSFAMILY |
+-------------------------------+---+------------------+-------------------------+-------------------------+--------------------+
|ChangePassword |50 |InstallUnattend |EnforcePersonality |TARGET |PROPERTY_USERS |
| | | | | |PROPERTY_OSFAMILY |
| | | | | |PASSWD |
+-------------------------------+---+------------------+-------------------------+-------------------------+--------------------+
|ConfigureNetwork |50 |InstallUnattend |EnforcePersonality |TARGET |NIC_* |
+-------------------------------+---+------------------+-------------------------+-------------------------+--------------------+
|FilesystemResizeMounted |50 |InstallUnattend |EnforcePersonality |TARGET |PROPERTY_OSFAMILY |
+-------------------------------+---+------------------+-------------------------+-------------------------+--------------------+
|EnforcePersonality |60 |MountImage |UmountImage |TARGET |PERSONALITY |
| | | | | |PROPERTY_OSFAMILY |
+-------------------------------+---+------------------+-------------------------+-------------------------+--------------------+
|RunCustomTask |70 |MountImage |UmountImage |TARGET |PROPERTY_CUSTOM_TASK|
+-------------------------------+---+------------------+-------------------------+-------------------------+--------------------+
|UmountImage |80 |MountImage | |TARGET | |
+-------------------------------+---+------------------+-------------------------+-------------------------+--------------------+
.. [#] all environment variables are prefixed with *SNF_IMAGE_*
......@@ -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"
......@@ -121,6 +151,8 @@ some external programs in ``/etc/default/snf-image``:
# CURL="curl"
# TAR="tar"
.. _configuration-parameters:
Configuration parameters
^^^^^^^^^^^^^^^^^^^^^^^^
......@@ -138,6 +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
* **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
^^^^^^^^^^^^^^^^^^^^^^^^^^
......
Development
===========
Building a new snf-image-helper kernel
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The kernel used to boot the helper VM is custom. We build our own kernel
because the ones shipped with the major Linux distributions don't have UFS
write support enabled, since it is considered dangerous. The ability to write
to UFS file systems is needed in order to support the various \*BSD images. In
this tutorial we will show how to build a Debian Kernel package using the
kernel configuration shipped with the snf-image. The kernel configuration file
we provide with snf-image is stripped down. All unnecessary hardware drivers
are removed and only the ones that are needed to boot a KVM and a XEN guest are
left. In order to recompile a Debian kernel using our configuration file do the
following:
Install the dependencies
++++++++++++++++++++++++
Install the dependencies for compiling a kernel:
.. code-block:: console
# apt-get install build-essential fakeroot
# apt-get build-dep linux
Download the kernel package:
.. code-block:: console
$ apt-get source linux
Build the packages
++++++++++++++++++
Apply the existing patches:
.. code-block:: console
$ fakeroot debian/rules source
Setup the amd64 configuration:
.. code-block:: console
$ cd linux-<version>
$ fakeroot make -f debian/rules.gen setup_amd64_none
Copy the snf-image provided configuration to the new kernel:
.. code-block:: console
$ cp /usr/share/doc/snf-image/kconfig-* debian/build/build_amd64_none_amd64/.config
Apply the kernel configuration:
.. code-block:: console
$ make -C debian/build/build_amd64_none_amd64 oldconfig
$ cp debian/build/build_amd64_none_amd64/.config debian/build/config.amd64_none_amd64
Change the ABI name (the debian building system will complain otherwise):
.. code-block:: console
$ sed -i 's|abiname: .\+|abiname: 0.snf.image.helper.1|' debian/config/defines
Add a new entry in ``debian/changelog`` with ``jessie-helper`` as distribution:
.. code-block:: console
$ dch -D jessie-helper --force-distribution
Build the new kernel package:
.. code-block:: console
$ fakeroot make -j <num> -f debian/rules.gen binary-arch_amd64_none
Upload it to an apt repository
++++++++++++++++++++++++++++++
If you want to upload the package to a repository, you will need to create a
changes file:
.. code-block:: console
$ cp ../linux_<old_version>.dsc ../linux-<new_version>.dsc
$ dpkg-genchanges > ../lunux_<new_version>.changes
And sign it:
.. code-block:: console
$ debsign ../linux_<new_version>.changes
Now you can use ``dput`` or ``dupload`` to upload the package to a repository.
......@@ -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>`_.
......@@ -47,6 +47,7 @@ Contents:
configuration
usage
advanced
development
Indices and tables
==================
......
......@@ -13,11 +13,17 @@ following OS Parameters:
the image (:ref:`details <image-id>`)
* **img_passwd** (optional): the password to be injected into the image
(:ref:`details <image-passwd>`)
* **img_passwd_hash** (optional): the hash of the password to be injected into
the image (:ref:`details <image-passwd-hash>`)
* **img_properties** (optional): additional image properties used to customize
the image (:ref:`details <image-properties>`)
* **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:
......@@ -89,8 +95,22 @@ Image Password (img_passwd)
^^^^^^^^^^^^^^^^^^^^^^^^^^^
The value of this parameter is the password to be injected into the image. If
this parameter is not set at all, then the *ChangePassword* task (see
this parameter is not set at all and **img_passwd_hash** is missing too, then
the *ChangePassword* task (see
:ref:`Image Configuration Tasks <image-configuration-tasks>`) will not run.
This parameter cannot be defined in conjunction with **img_passwd_hash**.
.. _image-passwd-hash:
Image Password Hash (img_passwd_hash)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The value of this parameter is the hash of the password to be injected into the
image. If this parameter is not set at all and **img_passwd** is missing too,
then the *ChangePassword* task (see
:ref:`Image Configuration Tasks <image-configuration-tasks>`) will not run.
This parameter is not applicable on Windows images and cannot be defined in
conjunction with **img_passwd**.
.. _image-properties:
......@@ -113,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
......@@ -138,13 +159,13 @@ All image formats properties
* For Windows images, the *Administrator*'s password is reset.
* For Linux and \*BSD images, the *root* password is reset.
* **DO_SYNC=yes**
* **DO_SYNC=bool**
By default in ResizeUnmounted task, when ``resize2fs`` is executed to
enlarge a ext[234] file system, ``fsync()`` is disabled to speed up the
whole process. If for some reason you need to disable this behavior, use the
*DO_SYNC* image property.
* **IGNORE_UNATTEND=yes**
* **IGNORE_UNATTEND=bool**
When deploying a Windows image, the InstallUnattend configuration task will
install an Answer File for Unattended Installation (the one shipped with
*snf-image* or the one pointed out by the *UNATTEND* configuration
......@@ -154,6 +175,29 @@ All image formats properties
exists in the above-mentioned location. For more information on "answer
files" please refer to :ref:`windows-deployment`.
* **ALLOW_MOUNTED_TASK_OVERWRITING=bool**
If this property is defined with yes, then the presence of an executable
file under */root/snf-image/helper/overwrite_task_<TASK>* inside the image
will make *snf-image* execute the code hosted there instead of the default
one. See :ref:`Overwriting Configuration Tasks<overwriting-configuration-tasks>`
for more info.
* **OFFLINE_NTFSRESIZE=bool**
When deploying a Windows Image, perform an offline NTFS resize, instead of
setting up the Unattend.xml file so SYSPREP executes a custom DISKPART
script to perform an online resize during the first boot. Note NTFS is left
dirty and will be checked automatically on first boot when performing an
offline NTFS resize. Set the *OFFLINE_NTFSRESIZE_NOCHECK* property to yes to
disable this behavior (this is dangerous). For more information on "answer
files" please refer to :ref:`windows-deployment`.
* **OFFLINE_NTFSRESIZE_NOCHECK=bool**
Set this property to yes to skip the NTFS check performed by Windows upon
the first boot when performing an offline NTFS resize (see the
*OFFLINE_NTFSRESIZE* property). Skipping the initial filesystem check is
dangerous, as it may lead to bugs of the offline NTFS resize procedure going
undetected.
* **PASSWD_HASHING_METHOD=md5|sha1|blowfish|sha256|sha512**
This property can be used on Unix instances to specify the method to be used
to hash the users password. By default this is determined by the type of the
......@@ -163,25 +207,44 @@ All image formats properties
`here <http://pythonhosted.org/passlib/modular_crypt_format.html#mcf-identifiers>`_
for more info).
* **SWAP=<partition id>:<size>**
If this property is defined, *snf-image* will create a swap partition with
the specified size in MB. The *partition id* is the number that the Linux
* **SWAP=<partition id>:<size>|<disk letter>**
If this property is defined, *snf-image* will create a swap device in the
VM. If the first form is used, then a swap partition with the specified size
in MB will be created. The *partition id* is the number that the Linux
kernel will assign to this partition. For example, if you have a disk with
an MSDOS partition table on it and one primary partition, the image
property *SWAP=2:512* would instruct *snf-image* to create a 512MB long
primary partition for swap with id=2. On the other hand, if the *SWAP*
property had this form: *SWAP=5:512*, since primary partitions may have an
id from 1 to 4, *snf-image* would create a 512MB extended partition with
id=2 and a logical swap partition with id=5 in it with the same size. This
property only applies to Linux instances.
* **EXCLUDE_ALL_TASKS=yes**
If this property is defined with a value other than null, then during the
deployment, the image will not be configured at all. This is really handy
because it gives the ability to deploy images hosting operating systems