XenClient Enterprise 5.0

1. XenClient Enterprise 5.0 Extracting Engine Logs with Ubuntu Live Desktop

2. Table of Contents

3. Motivation • There are two main ways to get diagnostics from XenClient Enterprise Engine: • A problem report may be submitted directly from the Engine. This will upload a standard diagnostics package to Citrix technical support. • Engine diagnostics can also be requested through the Synchronizer console. • These mechanisms are usually reliable and convenient, but sometimes they won't work: • If the Engine is experiencing network connectivity issues and can't upload diagnostics to Citrix or to the Synchronizer server. • If the Engine is in a state where it won't boot properly. • For problems installing the Engine software onto a computer. • An alternate method for extracting Engine log files from a computer is to boot the computer into a Linux Live session, then mount the disk volume containing the Engine log files. The log files can analyzed in place, copied to USB or network storage, or uploaded to ShareFile or a different network location.

4. Warning • Extreme caution should be used when following these procedures, especially if you are not familiar with root-level access in Linux or Unix environments. • The Linux command-line is very powerful but also potentially dangerous. Incorrect commands can cause severe problems and there are usually no warning or confirmation messages before carrying out destructive operations. • If you have any questions or uncertainty about these procedures, please contact Citrix Technical Support for assistance. • Citrix cannot be responsible for any problems that may arise as a result of incorrect Linux usage, including damage to the Engine installation or deployed VMs.

5. First Steps • What Is Needed: • Direct physical access to the XenClient Enterprise computer. • A USB stick (2 GB or larger) that can be formatted. • A separate Windows computer to run the UNetbootin program. • The XenClient Enterprise computer must be connected to a network with Internet access. • Format the USB Stick: • In Windows explorer, format the USB stick with a new FAT32 file system. • This will destroy all data on the USB stick! • Don’t skip this step. UNetbootin works best with newly formatted USB sticks. • Download and Run UNetbootin: • Download from http://unetbootin.sourceforge.net/ • UNetbootin is a simple executable file with a name like unetbootin-windows-585.exe. • Download the file to a convenient location and run it.

6. UNetbootin Options Select Ubuntu 13.04_Live. This should be set to USB Drive. Make sure the correct drive letter is set. This should be a newly-formatted USB stick.

7. UNetbootin Execution UNetbootin will download the Linux Live distribution as an ISO file. Linux Live distributions are typically a few hundred MB in size and may take a while to download. After the download is complete, UNetbootin will copy the contents of the ISO file to the USB stick and configure the USB stick as a bootable device. This process will take a few minutes to complete. When UNetbootin is done, it will offer the option to reboot or exit. Do not reboot! Instead, exit Unetbootin, eject the USB stick in Windows explorer, and remove it from the Windows computer.

8. Boot the XCE Computer into Ubuntu Linux After UNetbootin is finished, eject the USB stick from Windows then transfer it to the XenClient Enterprise computer. Boot the XenClient Enterprise computer from the USB stick. When the computer boots, choose the Try Ubuntu Without Installing option.

9. Ubuntu Desktop and Command Terminal • The computer should boot into the Ubuntu Desktop. • To open a command terminal, click the icon indicated below and search for terminal. • Root access is required for some of the commands that follow, so run sudo su in the terminal to become the root user.

10. Ubuntu Networking To configure networking or view networking status, click the networking icon at the top right of the Ubuntu Desktop. To view the current IP address, click the networking icon and select Connection Information:

11. Enable SSH Access SSH access is not enabled by default in Ubuntu Live Desktop. Run these commands in the Ubuntu terminal to enable SSH access. If these commands are successful, external SSH clients should be able to connect to Ubuntu Live Desktop with the user root and the password set with the passwd command.

12. Mount the XCE Log Volume (Part 1) These commands are for encrypted or unencrypted computers.

13. Mount the XCE Log Volume (Part 2a) This is for unencrypted computers. For encrypted computers, proceed to Part 2b. If these commands are successful the Engine log volume should be mounted to /mnt/8 (read-only).

14. Mount the XCE Log Volume (Part 2b) This is for encrypted computers. For unencrypted computers, use Part 2a instead. If these commands are successful the Engine log volume should be mounted to /mnt/8 (read-only).

15. Mount the XCE Log Volume (Part 2c) This is for encrypted computers if Part 2b doesn't work. Depending on the Engine upgrade history, the key to unlock the log volume may be in volume 6 instead of volume 5. If these commands are successful the Engine log volume should be mounted to /mnt/8 (read-only).

16. Create a Log File Archive This is for encrypted or unencrypted computers. After the Engine log volume is mounted, run these commands to create a zip file archive of the log volume contents. The zip file archive may be copied to USB or network storage, or uploaded to ShareFile or another network location.

17. Upload the Log Archive to ShareFile Launch FireFox from the Ubuntu desktop and enter the ShareFile upload URL. In the Upload Files section, click the icon to select a file for upload. Then select File System and the tmp folder. Select the logs.zip file and click Open to complete the ShareFile upload process. When the file is uploaded, notify Citrix that the file should be available.

18. Shutdown Ubuntu Live Desktop • When finished extracting log files from the Engine log volume, shutdown the Ubuntu Live Desktop session as shown. • Don't forget to remove the USB stick before rebooting the computer back into the XenClient Enterprise Engine.

19. Appendix A: Engine Boot Parameters

20. Mounting Boot Volumes in Linux Live Desktop • It may be useful to mount the Engine boot volumes. Usually this is done to change boot parameters for the hypervisor (Xen) or dom0 (commonly referred to as "the Engine" or simply "Linux"). • There are two boot volumes (volume 1 and volume 2) used for the "current" and "previous" Engine versions. • For Initial Engine install, volume 1 is the "current" version (volume 2 is empty). • For the first Engine upgrade, volume 2 is "current" (volume 1 is "previous"). • For the second Engine upgrade, volume 1 is "current" (volume 2 is "previous"). • Etc. • Use the procedures outlined in this document to boot the Engine computer into a Linux Live Desktop session, and open a command-line terminal with root privileges. Then run these commands to mount the boot volumes: • apt-get install lvm2 • vgchange -a y • mkdir /mnt/1 • mkdir /mnt/2 • mount /dev/mapper/NxVG*1 /mnt/1 • mount /dev/mapper/NxVG*2 /mnt/2 • This will mount the boot volumes read/write, not read-only, so the contents of the volumes may be modified. Best practice is to make a backup copy of any file before changing it. Incorrect changes to files in the boot volumes may render the Engine unbootable. • Boot parameters for the Engine are defined in the following GRUB configuration files. It can be difficult to tell which is for the "current" or "previous" Engine version, so usual practice is to edit both files. • /mnt/1/grub/grub.cfg • /mnt/2/grub/grub.cfg

21. Setting Boot Parameters in grub.cfg • In the grub.cfg file, look for a section starting with #DEFAULT_START. It should look like this: • #DEFAULT_START • menuentry "Boot Entry 1: XenClient Enterprise Engine 5.0.3 ${debug_status}" { • saved_entry=0 • save_default_entry • set root=(NxVG-210d63b6-3872-4439-aa10-f8bbe4c045d7-NxDisk1) • multiboot /xen.gz [hypervisor boot parameters] • module /vmlinuz-3.8.13-orc [dom0 boot parameters] • module /initrd.img-3.8.13-orc • } • #DEFAULT_END • This is where the hypervisor (Xen) and Engine (dom0) boot parameters are defined. In this example, the actual boot parameters are omitted to avoid confusion caused by line wrapping (these lines can be long). • Green line (starting with "multiboot /xen.gz"): • Boot parameters for the hypervisor (Xen). • Orange line (starting with "module /vmlinuz-3.8.13-orc"): • Boot parameters for dom0 (often referred to as "the Engine" or simply "Linux"). • To add a boot parameter: • Append the new boot parameter to the end of the correct line (not the beginning!). • Boot parameters should be separated by a single space. • Do not create new lines or reformat any section of grub.cfg (it is OK if the lines grow long).

22. Example Boot Parameter Settings • Enable Verbose Boot • This will enable additional messages during Engine boot that may aid debugging. • Hypervisor boot parameter changes: • None needed • Dom0 boot parameter changes: • Remove splash • Remove quiet • Enable Serial Console • This will redirect console output to the serial port for computers with an on-board serial port (not a USB serial adapter). A different computer could then establish a serial-to-serial connection using a null modem cable and a serial terminal client program such as minicom, hyperterm, or putty. • Hypervisor boot parameter changes: • Set com1=115200,8n1 (may be set to NULL or something else already, change it) • Set console=com1 • Dom0 boot parameter changes: • Remove splash • Remove quiet • Set xencons=tty • Set console=hvc0