For Windows 2003 Server and Windows 2008 Server (all 32-bit varieties).

Files

• apk-ver-windows.tar.gz - the appliance kit

Compatibility

The apk-*-windows versions are compatible with the following OS distros:

• Windows 2003 Server, all varieties (32-bit)
• Windows 2008 Server, all varieties (32-bit)

To install APK you need either:

• an existing appliance based on Windows
  
• a vanilla installation of the OS, in a XEN HVM environment.
• optional: para-virtual device drivers (3rd-party, not released with APK - require separate license!). APK has been tested with the Novell (SUSE) VMDP (virtual machine driver pack) and with the Halsign TurboGate drivers (TurboGate ver. 1.2.1 or later required, note that ver 1.2.1 works only on Windows 2003, a newer version is needed for Windows 2008).

Preparing the image

The following steps may vary, depending on how the OS was originally installed. They are not performed by the APK setup script, and are left to the discretion of the operator. Some of these steps require GUI access and may not be doable with an automated script, others are invasive and may be destructive - therefore running them in an automated script may be inadvisable.

Skip any steps that are not appropriate.

• Disable all "desktop experience" visual goodies (animated menus, shadows, full-window drag, etc.) for best operation over VNC or remote desktop.
• Disable the screen saver and screen lockout
• Set a strong password for the Administrator account.
• un-install/disable any OS services that will not be used (e.g., the Browser service and the Server service).
• Install all Windows Update hotfixes (will require multiple reboots!). Note: failure to install the updates on Windows 2008 may cause APK to fail.
• Take any other measures needed to secure the OS before it is made accessible on the network.
• Enable Remote Administration (via terminal services) - NOTE that this is different from configuring the OS as a Terminal Server (the latter requires paid licenses on the clients, do it only if this is the intended use of the installation).
• Configure the network with a publicly-accessible IP address; the remaining steps can now be performed via the remote desktop.
• Install CygWin (www.cygwin.com). Do the installation as Administrator and choose "install for all users". Add at least the following to the base set of packages: ssh server. DO NOT configure the sshd server yourself, let APK do this.
• make sure that the following GNU utilities are installed (should be in the base packages, but double-check and add them if they're missing): bash, wget, gzip, tar.
• Install the XEN-aware (paravirutal) device drivers, if desired. If using PV drivers, it is recommended to reboot Windows after they are installed and prior to installing APK and verify that the PV drivers operate normally.

NOTE: The minimal Windows 2003 install requires over 1GB of disk space. Windows 2008 needs nearly 8GB for the full install (less for the "server core"). Leave adequate room for installing CygWin and the Windows Update hotfixes (keep in mind that Windows will retain ALL previous versions of the binary files replaced by the hotfixes). Ensure that at least 5-10MB of free space is left, to have space for installing APK, as well as to have some headroom for log files, temporary files, etc.

Installing APK

The installation must be performed on a live system. APK for Windows cannot be installed into a mounted OS disk image that is not the OS actually running. For best results, use an OS image that has external network access configured and log into it using a remote desktop client from your favorite OS (e.g., rdesktop). This provides better interactive operation than using VNC to see the HVM emulated video screen.

Log in as Administrator and open a CygWin shell.

Copy the APK files to the /tmp directory.

Change to the CygWin root directory (/) and un-pack the the APK binary archive into the root directory, .e.g:

  cd /


  gtar -zxf tmp/apk-2.0.10-windows.tar.gz

Run the Install script:

  bash tmp/apk-install

This should complete without any error messages. If there are any, please check the preparation steps above and retry. Note that it is safe to re-run the install script multiple times, it will not damage the installation in any way.

The setup script and the APK tar file can be removed now:

  rm tmp/apk-install  tmp/apk-*.tar.gz

Shut down the OS.

If the image preparation was done outside of an AppLogic grid, the image can now be copied into a grid and used to create an appliance.

If the image was created on a grid as a new OS installation: disable the "unmanaged appliance" option (TBD: currently this is done by un-checking the Field Engineering Code box).

Ensure that the Device Schema is set to hda/hdb/hdc/hdd (in the Editor: Edt Class -> General -> Virtualization Mode -> Advanced).

Important Windows-specific Information

File Names

Unless otherwise stated, names in this document are in the CygWin file name space, which emulates a Posix system. Note that these names cannot be used with any non-Cygwin utilities. This includes the APK binaries themselves (vme and udlparse), as well as all of the native Windows command-line tools. Most Cygwin utilities will accept either a CygWin name (posix-style) or a Windows name (e.g., C:\path\), with the exception of those that consider strings with ":" in them to mean computername:filename, e.g., scp, rsync, and notably tar. The latter can be forced to accept a Windows name with the --force-local option.

To convert a file name between the Windows and Cygwin namespaces, use cygpath.

windowspath=`cygpath -w /var/applogic/appliance.desc`

Disk Mounts

When specifying a mount point for disks, use the following names, as desired:

X - a single letter (A,B,D-Z) will make the disk accessible as X:\.

X:\ - same as X

C:\dir1\[dir2\...] - makes the disk accessible in the given sub-directory of the boot file system. If the directory does not exist, it will be created. Note that it is not recommended to let APK create the directory, because the default directory permissions may not be what you want them to be.

Leaving a disk without a mount point specified in the class descriptor will cause APK to ignore the disk and leave its mount assignment in Windows as-is. In this case, any mount point assignment for that disk done manually from Windows itself is persistent and takes priority over assignment of the same mount point to another disk via the class descriptor (the latter assignment will have no effect and will leave the disk un-mounted). For example, if you have specified this in the class editor:

disk 0 -> (boot)
disk 1 -> (no mount assigned)
disk 2 -> Z:\ 

and you log into the appliance, remove Z from disk2 and assign it to disk1, then Z will stay assigned to disk1 across reboots and the 'disk2 -> Z' assignment in the class descriptor will not take effect. Disk2 will not be mounted anywhere, until Z is removed from disk1 or something other than Z is set for disk2.

C:\ is reserved and cannot be assigned as the mount point for any disk. Any assignment for the boot disk will be ignored and it will be reported as mounted on "C:\" in the appliance instance descriptor.

Do not use mount paths with sub-directories on any drive except C:. Doing this may cause your mount not to be useable, as it depends on the order in which the disks are mounted.

Keep in mind that Windows will not refuse to mount an un-formatted disk (or one formatted with a file system that is not understood by Windows). There will be no error or warning at all when the mount is assigned by APK, but attempts to access the mount point and any subpaths of it will fail.

BUG: If using the Novell PV drivers on an appliance that has an ISO (CD/DVD) disk image configured, the mount assignment feature of AppLogic APK must be disabled (see Appliance Init Configuration below). This is because the Novell PV drivers do not support CD-ROMs, making it impossible for APK to find and configure the correct mount point assignments.

User Names

The APK install script will make the CygWin alias for the Administrator be root . Therefore, root will be the user name seen by any CygWin binary and will show up as the current user name in a CygWin shell, as well as in directory listings. This setting allows accessing the appliance via the remote shell AppLogic command ( 3t ssh component-name).

Note that the mapping between CygWin user names and Windows user names is not automatic, it is described in the /etc/passwd and /etc/group files, which are not automatically updated when adding/removing Windows users. CygWin includes utilities to maintain the /etc/passwd and /etc/group files. When using these utilities, take care to preserve the special mapping for 'root' created by APK, otherwise ssh login from the grid will stop working.

Customizing Appliance Behavior - Quick Reference

For full details please refer to the User Guide.

Appliance Init Configuration

If the file /etc/sysconfig/applogic_init is present, the APK init script reads it as a shell include script (with the "." command). The following parameters can be defined in /etc/sysconfig/applogic_init :

Important: the /etc/sysconfig/applogic_init file is executed before any configuration data is retrieved or or applied, therefore the script cannot rely on the presence of any of the appliance's configuration files. Do not use this file for executing initialization code, only for the configuration variables defined above.

Example /etc/sysconfig/applogic_init:

APK_CONFIG_FILES=/etc/httpd/conf.d/myconfig.conf
APK_AUTH_KEY_PATH=/root/.ssh/alternate_keys

Appliance Post-start Check

If the file /etc/sysconfig/applogic_appliance is present, the APK "late init" script reads it as a shell include script (with the "." command), after all other services on the appliance have been started. The return status from the script indicates whether the appliance is to be considered "started OK" or "failed". If the script prints a message to stderr and returns an error, the last line from this message will be used as the error message sent to the controller.

Example post-start check file, for a Web server appliance - verifies that the server is up and responds to HTTP GET to the home page:

if ! wget -q -O /dev/null http://localhost/ ; then
echo "start failed - Web server is not responding" >&2
return 1
fi
return 0

Avoid using /etc/sysconfig/applogic_appliance , as "startup script" to launch appliance services. Doing this will prevent your setup form being used or tested outside of an appliance which has APK installed.

IMPORTANT Windows-specific note: unlike the other platforms supported by APK, the applogic_appliance post-start check is initiated after the Windows SCM (service control manager) has loaded all services - NOT when they have completed initializing. Things are further complicated by the fact that in Windows 2003/2008 some services are started by other services using an API call, rather than as an explicit dependency (and therefore cannot be accounted for simply by waiting on the automatic services load completion event). Therefore any 'startup check' code added to the /etc/sysconfig/applogic_appliance file must account for this and wait for any of the services that it needs to monitor, in case they haven't yet initialized.

-- LeoKalev - 13 Nov 2008

-- BeckyH - 12 Sep 2008