From 29847ba9df4c0d44e3da8eb015f308e39b2341cf Mon Sep 17 00:00:00 2001 From: Nikos Skalkotos Date: Mon, 4 Nov 2013 14:04:33 +0200 Subject: [PATCH] docs: Update the doc to reflect the latest changes Update the documtation to reflect the changes made to support NetBSD and OpenBSD systems. --- docs/architecture.rst | 76 +++++++++++++++++++++++++++---------------------- docs/index.rst | 3 +- docs/interface.rst | 35 ++++++++++++++++------- 3 files changed, 69 insertions(+), 45 deletions(-) diff --git a/docs/architecture.rst b/docs/architecture.rst index 70d4490..f90a26e 100644 --- a/docs/architecture.rst +++ b/docs/architecture.rst @@ -127,16 +127,21 @@ below for a description of each one of them: **FixPartitionTable**: Enlarges the last partition in the partition table of the instance, to consume all the available space and optionally adds a swap -partition in the end. +partition in the end. The task will fail if the environmental variable +*SNF_IMAGE_DEV*, which specifies the device file of the instance's hard disk, +is missing. **FilesystemResizeUnmounted**: Extends the file system of the last partition to -cover up the whole partition. This only works for ext{2,3,4} file systems. Any -other file system type is ignored and a warning is triggered. The task will -fail if *SNF_IMAGE_DEV* environmental variable is missing. - -**MountImage**: Mounts the nth partition of *SNF_IMAGE_DEV*, which is specified -by *SNF_IMAGE_PROPERTY_ROOT_PARTITION* variable under the directory specified -by *SNF_IMAGE_TARGET*. The script will fail if any of those 3 variables has a +cover up the whole partition. This only works for ext{2,3,4} and ufs2 file +systems. Any other file system type is ignored and a warning is triggered. The +task will fail if *SNF_IMAGE_DEV* environmental variable is missing. + +**MountImage**: Mounts the root partition of the instance, specified by the +*SNF_IMAGE_PROPERTY_ROOT_PARTITION* variable. On Linux systems after the root +fs is mounted, the instance's ``/etc/fstab`` file is examined and the rest of +the disk file systems are mounted too, in a correct order. The script will fail +if any of the environmental variables *SNF_IMAGE_DEV*, +*SNF_IMAGE_PROPERTY_ROOT_PARTITION* or *SNF_IMAGE_TARGET* is unset or has a non-sane value. **AddSwap**: Formats the swap partition added by *FixPartitionTable* task and @@ -144,39 +149,42 @@ adds an appropriate swap entry in the system's ``/etc/fstab``. The script will only run if *SNF_IMAGE_PROPERTY_SWAP* is present and will fail if *SNF_IMAGE_TARGET* in not defined. -**DeleteSSHKeys**: For Linux images, this script will clear out any ssh keys -found in the image and for Debian, it will recreate them too. In order to find -the ssh keys, the script looks in default locations (/etc/ssh/ssh_*_key) and -also parses ``/etc/ssh/sshd_config`` file if present. The script will fail if -*SNF_IMAGE_TARGET* is not set. +**DeleteSSHKeys**: On Linux and \*BSD instances, this script will clear out any +ssh keys found in the instance's disk. For Debian and Ubuntu systems, the keys +are also recreated. Besides removing files that comply to the +``/etc/ssh/ssh_*_key`` pattern, the script will also parses +``/etc/ssh/sshd_config`` file for custom keys. The only variable this script +depends on is *SNF_IMAGE_TARGET*. **DisableRemoteDesktopConnections**: This script temporary disables RDP -connections in windows instances by changing the value *fDenyTSConnection* +connections on windows instances by changing the value of *fDenyTSConnection* registry key. RDP connections will be enabled back during the specialize pass of the Windows setup. The task will fail if *SNF_IMAGE_TARGET* is not defined. -**InstallUnattend**: Installs the Unattend.xml files in windows images. This is -needed by windows in order to perform an unattended setup. The +**InstallUnattend**: Installs the Unattend.xml files on windows instances. This +is needed by windows in order to perform an unattended setup. The *SNF_IMAGE_TARGET* variables needs to be present for this task to run. **SELinuxAutorelabel**: Creates *.autorelabel* file in Red Hat images. This is -needed if SELinux is enabled to enforce an automatic file system relabeling at -the next boot. The only environmental variable required by this task is +needed if SELinux is enabled to enforce an automatic file system relabeling +during the first boot. The only environmental variable required by this task is *SNF_IMAGE_TARGET*. -**AssignHostname**: Assigns or changes the hostname in a Linux or Windows -image. The task will fail if the Linux distribution is not supported. For now, -we support Debian, Red Hat, Slackware, SUSE and Gentoo derived distributions. -The hostname is read from *SNF_IMAGE_HOSTNAME* variable. In addition to the -latter, *SNF_IMAGE_TARGET* is also required. - -**ChangePassword**: Changes the password for a list of users. For Linux systems -this is accomplished by directly altering the image's ``/etc/shadow`` file. For -Windows systems a script is injected into the VM's hard disk. This script will -be executed during the specialize pass of the Windows setup. For FreeBSD -``/etc/master.passwd`` is altered, ``/etc/spwd.db`` is removed and a script is -injected into the VM's hard disk that will recreate the aforementioned file. -The list of users whose passwords will changed is determined by the +**AssignHostname**: Assigns or changes the hostname of the instance. The task +will fail if the Linux distribution is not supported and ``/etc/hostname`` is +not present on the file system. For now, we support Debian, Red Hat, Slackware, +SUSE and Gentoo derived distributions. The hostname is read from +*SNF_IMAGE_HOSTNAME* variable. In addition to the latter, *SNF_IMAGE_TARGET* is +also required. + +**ChangePassword**: Changes the password for a list of existing users. On Linux +systems this is accomplished by directly altering the instance's +``/etc/shadow`` file. On Windows systems a script is injected into the VM's +hard disk. This script will be executed during the specialize pass of the +Windows setup. On \*BSD systems ``/etc/master.passwd`` is altered, +``/etc/spwd.db`` is removed and a script is injected into the VM's hard disk +that will recreate the aforementioned file during the first boot. The list of +users whose passwords will changed is determined by the *SNF_IMAGE_PROPERTY_USERS* variable (see :ref:`image-properties`). For this task to run *SNF_IMAGE_TARGET* and *SNF_IMAGE_PASSWORD* variables need to be present. @@ -188,10 +196,10 @@ script will run during the specialize pass of the Windows setup. If the **EnforcePersonality**: Injects the files specified by the *SNF_IMAGE_PROPERTY_OSFAMILY* variable into the file system. If the variable is -missing a warning is produced. The only environmental variable required is -*SNF_IMAGE_TARGET*. +missing a warning is produced. Only *SNF_IMAGE_TARGET* is required for this +task to run. -**UmountImage**: Umounts the file system previously mounted by MountImage. The +**UmountImage**: Umounts the file systems previously mounted by MountImage. The only environmental variable required is *SNF_IMAGE_TARGET*. diff --git a/docs/index.rst b/docs/index.rst index 43df2c4..aa035b6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -27,7 +27,8 @@ snf-image also supports Image customization via hooks. Hooks allow for: snf-image is being used in large scale production environments with Ganeti to successfully deploy many major Linux distributions (Debian, Ubuntu/Kubuntu, CentOS, Fedora, OpenSUSE), Windows 2008 R2 & Windows Server 2012, as well as -FreeBSD. +FreeBSD. Support for OpenBSD and NetBSD is also included with exception to +extending partitions. The snf-image Ganeti OS Definition is released under `GPLv2 `_. diff --git a/docs/interface.rst b/docs/interface.rst index 8909f5c..5998cfc 100644 --- a/docs/interface.rst +++ b/docs/interface.rst @@ -42,10 +42,10 @@ Image ID (img_id) ^^^^^^^^^^^^^^^^^ The **img_id** OS parameter points to the actual Image that we want to deploy. -It is a URI and its prefix denotes the type of :ref:`backend ` -to be used. If no prefix is used, it defaults to the local backend: +It is a URI and its prefix denotes the type of :ref:`back-end ` +to be used. If no prefix is used, it defaults to the local back-end: - * **Local backend**: + * **Local back-end**: To select it, the prefix should be ``local://``, followed by the name of the image. All local images are expected to be found under a predefined image directory (``/var/lib/snf-image`` by default). @@ -55,7 +55,7 @@ to be used. If no prefix is used, it defaults to the local backend: | We need to assign: | ``img_id=local://slackware.diskdump`` - * **Network backend**: + * **Network back-end**: If the **imd_id** starts with ``http:``, ``https:``, ``ftp:`` or ``ftps:``, snf-image will treat the **img_id** as a remote URL and will try to fetch the image using `cURL `_. @@ -63,7 +63,7 @@ to be used. If no prefix is used, it defaults to the local backend: | For example, if we want to deploy an image from an http location: | ``img_id=http://www.synnefo.org/path/to/image/slackware-image`` - * **Pithos backend**: + * **Pithos back-end**: If the **img_id** is prefixed with ``pithos://`` or ``pithosmap://`` the image is considered to reside on a Pithos deployment. For ``pithosmap://`` images, the user needs to have set a valid value for the @@ -77,8 +77,8 @@ to be used. If no prefix is used, it defaults to the local backend: | or if we already know the map: | ``img_id=pithosmap://`` - * **Null backend**: - To select the Null backend and skip the fetching and extraction step, we set + * **Null back-end**: + To select the Null back-end and skip the fetching and extraction step, we set ``img_id=null``. .. _image-properties: @@ -103,8 +103,8 @@ A list of all properties follows: Mandatory properties (for diskdump only) ++++++++++++++++++++++++++++++++++++++++ - * **OSFAMILY={linux,windows}** - This specifies whether the image is a Linux or a Windows Image. + * **OSFAMILY=linux|windows|freebsd|netbsd|openbsd** + This specifies whether the image is a Linux, a Windows or a \*BSD Image. {ext,ntfs}dump formats are self descriptive regarding this property. * **ROOT_PARTITION=n** This specifies the partition number of the root partition. As mentioned @@ -122,7 +122,22 @@ Optional properties The rules we currently use are listed below: * For Windows images, the *Administrator*'s password is reset. - * For Linux and FreeBSD images, the *root* password is reset. + * For Linux and \*BSD images, the *root* password is reset. + + * **DO_SYNC=yes** + 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. I for some reason you need to disable this behavior, use the + *DO_SYNC* image property. + + * **PASSWORD_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 + instance. For Linux and FreeBSD instances ``sha512`` is used, for OpenBSD + ``blowfish`` and for NetBSD ``sha1``. Use this property with care. Most + systems don't support all hashing methods (see + `here `_ + for more info). * **EXCLUDE_ALL_TASKS=yes** If this property is defined with a value other than null, then during the -- 1.7.10.4