Turnkey Linux and TKLPatch

sbscherer's picture

Hi everyone,

I have two related questions and apologize in advance if they have already been covered in previous posts.

First, the amount content that has been created in the form of TKLPatches as a result of the contest is just amazing. Does TKL plan to spin all these into appliances, publish just the TKLPatches in the repository, or do some combination of both?

Second, I have followed TKL for over a year now and the TKLPatch subject comes up pretty frequently.  However, I haven't been able to find a good post to learn how to install a TKLPatch.   Would someone be willing to put together a post with directions, maybe even with a screen recording if complex, to help catch some of us up?  

I appreciate all the hard work that has gone into TKL.  I can't wait to see what the contest will bring.  Thanks!

Jeremy Davis's picture

You'll need to wait to hear from Alon & Liraz re your first question, but I'd imagine that they'll look through the patches and make a decision on which ones to release as TKLpatches. TBH I'd guess they'll use many of them. I doubt they'll publish any patches as they're all available here anyway, but I could be wrong.

It's really easy to apply a patch to an ISO. You'll need TKLPatch installed obviously. Unless you're running Ubuntu (and probably even them) the best way is to install TKL Core into a Virtual Machine (Virtual Box is a nice free one, but there are others). Then install TKLPatch (apt-get update && apt-get install tklpatch), then have the patch and the ISO to be patched in the same folder and run this command:

tklpatch image.iso patch.tar.gz

Using this example you will get a resulting ISO called image-patched.iso Too easy! You can also install to a live system but it is not recommended as there are some potential downfalls. Read about that in the TKLPatch documentation.

If you want to have a play with TKLPatch I'd strongly suggest you read through the whole documentation, if you can cope with commandline then it's all pretty straightforward.

sbscherer's picture


I am definitely looking forward to seeing more appliances.  However, I figure whether or not everything gets converted into appliances, I should probably learn a lot more about the patch process. 

It seems I was just misunderstanding which environment to use in order to apply the patch, so I should be able to handle it.  I appreciate the guidance JedMeister.

I might be getting ahead of myself, but I am wondering if it is possible to use a TKLPatch to reliably convert a batch of appliances to run in para-virtualized mode, like to run on XenServer or ESXi.  Any thoughts?

Liraz Siri's picture

Good news. We already have a conversion process for Xen and ESXi in place. The Xen images we've been providing to hosting providers that reached out to us. The ESXi we gave to VMWare for integration with vSphere and the VMWare marketplace but for some reason they've only integrated a handful of appliances.

I just launched our conversion machine on EC2 and will be uploading these images to sourceforge where everyone can get them.

Liraz Siri's picture

OK the upload for the ESX4 optimized images just finished (at 10MB/s), and I've just starting uploading the Xen optimized builds. Should be done in a few minutes.

For some reason it impresses the hell out of me I'm getting faster upload speeds between EC2 and Sourceforge than I can get on my home 100Mbit LAN...

sbscherer's picture

I can't tell you how happy it makes me to be able to use those images as a starting point.  I will finally be able to deploy some of these great tools into a real production environment.

This is huge for our small business, because this will be the first step towards reducing Microsoft's footprint as well as the first time since 2003 (Office and XP) that we can deploy new productivity tools.  High prices, reliability concerns, support expenses, and the resulting lock-in has kept our users in the dark ages.  

For anyone else reading this post, see the link below for the XenServer and ESXi images...

sbscherer's picture

One follow up question.  What is the proper way to convert the file system into an .iso that can be used on the Xen or ESXi hypervisor?  I have tried a couple things, but am getting errors.  Thanks!

Landis Arnold's picture

I ended up at Turnkey because I was looking for prebuilt appliances.   ISo's seemed not where i wanted to go as I was scared (still am) of some of Linux...  that said, by now I have found using ISO's is no problem

This is the process I use w/ VMWare Esxi 4  (similar process in VMWare Server also - just a few diffs)


Download the ISO

Open VMWARE Sphere Client, log in as Root. 

Configuration ->  hit Storage

right click on your Data Store (DataStore1 for me), and choose -> Browse Datastore

If you have not made a Folder, hit the Folder+ icon  -- to make a new Folder

Call it ISOImages or ISODisks

Open the Folder

Hit the "upload file' button.

Choose your TKL ISO image.

Close your Datastore Browser


have a beer


(Add a "Next Click to each of the following lines0

now go to "Virtual Machines" tab in VMWare Client (near where you are in "Configuration"

Right Click below all the other machines and choose "New Virtual Machine" .

Choose "typical"

Give it a Name (I like to use a close resembance to the ISO I want to install from)

Double click on your DataStore, to define where you want to store it, and then hit NEXT

Select "Linux" radio button, and then select "Ubuntu Linux 32bit"

(now slow down here)

I take the standard 8gb Virtual Disk, then CLICK "Allocate Space on Demand"  (this will save a lot of space till you need it!) -- if it is a super high load site, maybe don't do that.. but for me it works.

Click IMMEDIATELY next on "Edit the virtual machine settings", then Click "Finish"

You will be presented with your Settings now:

Go to "New CD/DVD"

Choose - > "DataStore ISO" 

Choose the ISO File in the DataStore/ISOImages Folder you already uploaded

IMMEDIATELY Choose "Power on at Startup" - you can't boot without this switch!

you are ready to Roll now  (Installation is pretty much Automatic)


Your VMWare Machine is on equal footing with any others now. 


Hit the Power/Go/Green Arrow. 

Click on the Console Button (better than the tab) in order to watch and interact with the install.

If "No OS is found" you need to Auto Power Down via "Inventory Virtual Machines, Right Click Power Down" as you don't have VMWare tools installed and this is the only place to do this othewise.  Click Edit settins, and make sure "Power On at Startup" is clicked for your CD - so the machine can boot from the ISOFile.


During Installation, I have learned to choose the LVD Options and then answer yes and no in ways that are occassionally counterintuitive (and compunded because the whole install is rolling pretty fast)

You will get all the way to the end and it will ask you to implement TKLBam (choose Skip is my recomendation, it won't work if you don't have an IP address yet and you can get it going very quickly when you login to WebMin (:12321) as soon as you want)

Next:  Accept the "Auto Security Updates"  --> this will create an error as you still don't have a Network connection, but I don't know how to set it up automatically in WebMin otherwise...

Finally: you will may be told:  No Networking is SetUp and you will  be moved on to a screen where you can choose between DHCP (auto ip assignment) or Static IP.  I use DHCP behind my firewall, and Static in my DMZ as I don't have DHCP in the DMZ and I usually need a Server there not on the back side.

In Static: Know the IP you are assigning, and hopefully you will already have DNS setup to point at the IP / or Mapped IP you are defining. IF not, give it a Free IP Address and know your host/dns/access mappings so that you can set your Router to allow-facilitate access. 

Once you define the IP, the system will be LIVE.

This all takes a lot less time than I just spent typing this and you will have an awesome system that is easy to maintain and easy to backup and many other things.  ISO Files are a fine way to install.

TKL Patch turns out to be pretty easy too...  Read the post below, or float around a bit and you will find logs of the install process.  Really quite easy.  Creates an ISO you can Install just the way I have tried to describe.

Basically any version of VMSomethng will install similarly to the VMWware ESXI process I have been referencing.

A few closing notes:

You can boot from a CD the same way also, just by not using an ISO but by using your Server's CD drive.  Don't try to use a Remote CD however (in my experience --  you can't engage the remote CD at startup fast enough no matter how many times you try).  VMWare Server (on another Server can use a Mapped Drive which was intuitively easier for me than the Browse DataStore to find - BUT DOES NOT WORK W/ ESXI without some ISCSI or SMB connection. 

Ideally a Shared DataStore that you can get to from any Server is Best as you only would have to store an ISO Once and use it on any Server Box.., but I haven't crossed that Rubicon yet though I have tried a few times. (Can't figure how to get the TKL FileServer to work the way I understand it does in CIFS or SMB)..  If your Server is not performing as you like "edit settings" give it more ram, and do a google search on "PHP Ram" in refernce to your Application.  You will probably want to give the Application more Ram in one of its settings files, not just the Virtual Machine.

all for now.  I hope this is helpful 

(I notice here it is a bit out of synch but I think folks will be running into the same questions I had over the last few months --  it gets pretty easy w/ a little practice.)

Liraz Siri's picture

And I wrote one that is more distantly related but that you might find helpful as well:

Jonathan's picture

Hello guys, thank you for all your effort, you're doing a Great work for all the community.

I have a question with that Xen images... First, Is that Citrix Xenserver images? Second, How may i used it?

Thank in advance.

Jeremy Davis's picture

As you may know Xen is the open source cousin of XenServer. Liraz (one of the TKL core devs) wrote an interesting post with his take on Citrix and their XenServer image format. You may find some of the other posts on that thread useful for looking at ways to import to XenServer.

sbscherer's picture

Is it possible to install a TurnkeyLinux ISO appliance with the hvc0 kernel?  That way, Citrix users can simply install the Xentools themselves afterwards. 

I agree with Liraz and I can't see a reason to provide Citrix "xva" images, but having the ability to install a TurnkeyLinux appliance on Citrix XenServer should be a priority.  It provides the flexibility for production environments to move to Linux at their own pace, which ultimately leads to a bigger community. 

Jeremy Davis's picture

But I think that the nature of TKL is open source, so support for open source technologies should IMO have a priority. The unfortunate reality of that is that with a two man dev team, that doesn't leave a lot of room for anything much else, but....

That's where you come in as a TKL community member! I think the best way to go would be to test and document how to set it up. The new release of TKL will be based on Lucid/10.04 and isn't that far away. I hope I'm not jumping the gun, but it looks like lots of TKL Lucid based RC ISOs are available from TKL's SourceForge page.

It seems that even getting Ubuntu 10.04 to run nicely on XenServer is not as straightforward as it perhaps should be. A quick google turned up a few pages that may be of interest to you. Have a look here, here and here.Have a play, get it working and write it up on the Dev Wiki and take it from there.

You may be able to leverage TKLPatch and make a patch to transform standard TKL ISOs into XenServer ones with the kernel you want, perhaps even XenTools preinstalled too? Otherwise some helper scripts or something could be the go. And/or you could build ISOs and/or 'xva' images yourself and upload them somewhere with free filesharing and post links here on the forums?

Regardless, I think investigating this and writing up your findings (either here in the forums or probably even better on the Dev Wiki) would definately be useful for others, and the TKL community as a whole. For a bit of a round up of Dev stuff, have a look at the Dev info page here.

sbscherer's picture

I have never swapped kernels befores, but the process was fairly straightforward.  However, it looks like the TKL Core 10.04 LTS appliance doesn't have the HVC0 kernel like the standard 10.04 LTS server does.  Can anyone confirm this?

It seems like other alternatives to getting it working on Citrix XenServer are:

  1. Install the HVC0 kernel to a TKL Core appliance then swap kernels
  2. Convert a image to an installable ISO using Liraz and Alan's TKLpatch posts
  3. Build a TKL Core appliance from scratch on the HVC0 kernel on 10.04 LTS JeOS
  4. Leverage a TKLPatch to install application on Ubuntu 10.04 LTS HVC0

I nearly completed option 2, but the resulting ISO would not install properly.  I was not able to complete option 1 due to an error (see below).  I could probably handle option 3 on my own with a good set of instructions. 

Internal error: XenguestHelper.Xc_dom_LInux_build_failure(2, " elf_xen_note_check: ERROR: Will only load images built \\\"")

I successfully installed 10.04 LTS JeOS and swapped to the HVC0 kernel using the directions above (thanks JedMeister).  Option 4 is how I have been getting by.  On a related note, are the TKLPatches on the Dev Wiki for all the original appliances?

sbscherer's picture

Ubuntu Guest Console:

  1. cp /etc/init/tty1.conf /etc/init/hvc0.conf
  2. nano -w /etc/init/hvc0.conf (replace all tty1 with hvc0)
  3. shutdown -P now

Citrix XenServer Console:

  1. xe vm-list power-state=halted (write down UUID for Core VM)
  2. xe vm-param-set uuid=<UUID> HVM-boot-policy=
  3. xe vm-param-set uuid=<UUID> PV-bootloader=pygrub
  4. xe vm-disk-list uuid=<UUID> (find VB disk UUID)
  5. xe vbd-param-set uuid=<VBD UUID> bootable=true
  6. Start appliance and restart XenCenter Manager

Jeremy Davis's picture

So I can't really help much with that.

I would think that option 1 would be the ideal, as then a TKLPatch can be contructed to repeat the process for any TKL appliance. Perhaps if you document the exact steps you have taken (either here or on the Dev wiki) others may be able to help. It may also be worth posting on the XenServer forums to see if others over there could help you out.

Option 2 should theoretically be ok (although not quite as useful as it would only apply to a single appliance rather than the whole range). Obviously though something is not quite right there either.

Option 3 is probably not really completely practical as you'd basically be starting from scratch and not getting many of the advantages of TKL. Basically it'd be a custom Ubuntu server (although you could get some good ideas from TKL).

Option 4 is more practical but still open to issues due to differences between vanilla Ubuntu & TKL. Also to also answer your final question; Only community developed appliances have TKLPatches available. All the dev developed appliances were developed inhouse prior to TKLPatch. So no patch exists for them.

It's strange that the HVC0 kernel seems to install fine to Ubuntu 10.04 but not to TKL 11.0RC. They have the same foundation, so I would imagine that the same steps would apply equally to both. TKL also have a v11.0RC bootstrap release, perhaps you could try the same steps on that as worked on Ubuntu JeOS?

sbscherer's picture

I was able to modify the grub config file and XenServer to boot both the full server installation and JeOS installation in HVC0 mode.  Only the TKL appliances are failing, I tried with Redmine and Core, so I am guessing some modification is getting in the way or there could even be a bug, but I can't tell myself.

sbscherer's picture

You make an excellent point about community assisting. I brought up the idea of a TKLPatch earlier. However that is too complicated for me to put together and probably for many others with familiarity with Ubuntu command line.

There is another option that would make sense. If liraz or Alan put a Citrix XenServer TKL Core appliance together, it would jumpstart development within the community. I would personally be happy to share appliances and documentation as time permits. The only barrier is I don't have the Citrix XenServer compatible 10.04 LTS Core appliance to start from. As you pointed out, it is difficult to swap kernels and more complicated with a TKL appliance.

Jeremy Davis's picture

Obviously I can't speak for the devs but I'd be surprised if they dedicate any of their time, anytime soon to support XenServer.

When you put it in perspective they have had plans to support OpenVZ (open source container virtualisation) for as long as I've been a member here (well over a year) and there is still no official support. Considering that XenServer support is not even on their todo list AFAIK, even if they add it, reality is that it could be years away (unless of course you or someone else contracts them to do it).

Even if you could just set it up (following the instructions from one of the links I posted earlier or similar) and clearly document your steps (in the Dev Wiki) would help. Getting Lucid based TKL to run nicely should be basically the same as getting Ubuntu Lucid/10.04 going. From there someone else may be willing to take the extra step to create a TKLPatch which would allow any of the ISOs to be patched to run nicely on XenServer.

Jonathan's picture

I found this and works perfectly, i hope this could help.

sbscherer's picture

Did you get this to work on a TKL appliance?  These instructions work fine on Server and JeOS installations, but not TKL appliances.  I just did it again and encountered the same error as before.  

Internal error: XenguestHelper.Xc_dom_LInux_build_failure(2, " elf_xen_note_check: ERROR: Will only load images built \\\"")

Jonathan's picture

You're right, I'm really sorry i didn't test on TKL appliance, it's working for me for a official cd ubuntu 10.04 server installation. I'm sorry for the misunderstanding.

Jeremy Davis's picture

So I'd guess that its an option that is selectable in Ubuntu but pre-configured in TKL. What about GRUB legacy? I read that apparently XenServer doesn't like GRUB2? Could that be it maybe? (I'm really only guessing).

TBH XenServer seems like a complete PITA, especially used in conjunction with Ubuntu. I certainly won't be trading in my (free, open source) ProxmoxVE server.

Jonathan's picture

That's true dude, XenServe doesn't like grub2 neither ext4, but is fully support for SUSE, REDHAT, CENTOS & Windows AND we have a windows enviroment (for engineering commercial software use) with some especifically linux box running (one is trixbox on centos and we're triying to implement BBB on ubuntu). So the free XenServer seems like can help us right now.

I didn't have idea about the Proxmox till you just talk about it.

Guest's picture

Following this guide here I was able to run an ubuntu template as described in this post
Basically XenServer is a good alternative for my use cases to ESXi because of some hardware restrictions. The kernel used in the fresh installed "minimal virtual machine" installation is
grep CONFIG_XEN /boot/config-2.6.32-24-generic-pae

# CONFIG_XEN_DEBUG_FS is not set

Anyway, I was not able to enabel the hypervisor mode on the turnkey instance.

It uses /boot/vmlinuz-2.6.32-25-generic
and there are no XEN in  options in this kernel

grep CONFIG_XEN /boot/config-2.6.32-25-generic results in 0 lines matched.

So installing a turnkey appliance in a XenServer 5.5 by using Windows Server 2008 32bit template properties gives at least a basic option to run the appliances. But turning the machine to hypervisored mode fails with an error which indicates that there is no xen support in the kernel or it is not activated

05.11.2010 16:44:34 Error: Starting VM 'Turnkey-Django' - Internal error: Failure("Error from xenguesthelper: caught exception: Failure(\\\"Subprocess failure: Failure(\\\\\\\"xc_dom_linux_build: [2] elf_xen_note_check: ERROR: Will only load images built \\\\\\\")\\\")")

Any suggestions would be great, sine I am not sure how both kernels differ from each other.


Jeremy Davis's picture

If you can get it to work with Ubuntu 10.04 with that kernel then that may be the thing thats stopping it from working properly on TKL? You can install that kernel in TKL with this command:

apt-get update && apt-get install linux-image-generic-pae

Let us know how it goes. If you can detail a clear set of steps that you take then I can probably help you to create a TKLPatch so TKL ISOs can be patched to support XenServer and include the tools - all ready to go.

RTG's picture

Hi JedMeister,

thanks for your respond. A better google search yesterday guided me already to this thread
which is quite the same procedure to get pae kernel on TKL.
After running the:

apt-get update
apt-get install linux-headers-server linux-image-server 

Everything went fine also installing the xen-tools. So this is a great option for everyone who is running xenserver 5.5. with TKL appliances, which can be hypervisored (32bit).
Thank you very much for the great job you doing on TKL, appliances and community just work.

Excited to see how you guys will commercialize the backup solution after the beta. Looking forward to see some affordable plans ;-). Thumbs up!


Jeremy Davis's picture

The 2009.10-2 release is based on Ubuntu 8.04/Hardy. From my understanding in Hardy the Server kernel supports 32-bit and 64-bit systems, and includes PAE when running in 32-bit mode. There was no specific PAE kernel, only the Server kernel (32PAE/64 bit) and Desktop ('Generic') kernel (32/64 bit). FYI Hardy actually has a specific Xen kernel, although I'm not clear on whether that works with XenServer? I imagine it would because AFAIK XenServer uses Xen underneath!?

The v11.0RC release is based on Ubuntu 10.04/Lucid. Lucid seems to do things a little different. From what I can gather, the Lucid Server kernel is 64 bit only and the Desktop kernel is 32/64 bit but with no PAE. There is a separate 32 bit PAE kernel.

Although perhaps thats not quite the case as you said in an earlier post (I assume it was you RTG? - same icon?) that you were using v11.0RC? So perhaps the Lucid Server kernel acts the same as the Hardy one? Be good if you can confirm that the Lucid Server kernel works with TKL (as obvioulsy at the moment TKL is 32 bit only).

Also I possibly should have included the kernel headers in my above instructions (as it was in the bit you posted) although it looks like sbscherer (see below) got it working fine without them. Its definitely out of my area of expertise but AFAIK headers are a bit like a kernel roadmap and can be quite important for the installation of drivers etc. Without them software is required to just make a 'best guess'. In a virtualised environment I would imagine they're possibly not required, although it may be worth testing with and without them - in case it helps things along with the installation of the Xen tools?

RTG's picture

Hi JedMeister,

yes both posts are from my side and i can confirm that the version v11.0RC was used to get the TKL 32bit running on the XenServer 5.5 and I adjusted it just by the pervious lines which changed it to generic-pae. The testing is however not solid, but the XenCenter recognizes the virtualization state as "optimized(version 5.5 installed)", which at least indicates that xen-tools are running properly.

Thanks for the details about the kernels and I see that the a change to a different kernel adds another level of testing complexity, but as far as I undestand adding the pae kernel installation step just only brings in the right /boot xen settings support and a proper kernel compile. It would be interesting to know if the same procedure works for generic kernel if xen parameters are included through the build properly. PAE just adds memory extenson as I understand in 32bit enviroments, but the rest of the kernel should have the same base and if compiled with XEN specifics, as stated here.
I think the generic kernel would run xen-tools too.
However the post installation of the pae kernel is simple, does the job and the option is also referenced from citrix as type 2 Installation.

"Paravirtualised Kernel Support, without vendor installer. (HVM mode, but can be switched into PV mode by installing/enabling PV kernel mode)."

But in case you want to have  a closer look of how to support Ubuntu and Debian, here are some links from their site.

BTW, I will not get any extra beers from Citrix for this and I would prefer to go with standard xen by default, but most prod. systems we have require stable Win drivers with support, so this is just the need to let smaller linux VM's properly without wasting of ressources.


sbscherer's picture


We were so close before, all we needed to install was the proper kernel.  Confirmed working on TKL Core 10.04 LTS (32-bit) appliance.  Thanks JedMeister!

Ubuntu Guest Console (Configure Guest):

  1. apt-get update && apt-get install linux-image-generic-pae
  2. cp /etc/init/tty1.conf /etc/init/hvc0.conf
  3. nano -w /etc/init/hvc0.conf (replace all tty1 with hvc0)
  4. shutdown -P now

Citrix XenServer Console (Configure XenServer):

  1. xe vm-list power-state=halted (write down UUID for TKL VM)
  2. xe vm-param-set uuid=<UUID> HVM-boot-policy=
  3. xe vm-param-set uuid=<UUID> PV-bootloader=pygrub
  4. xe vm-disk-list uuid=<UUID> (find VB disk UUID)
  5. xe vbd-param-set uuid=<VBD UUID> bootable=true
  6. Start appliance and restart XenCenter Manager

Ubuntu Guest Console (Install XenTools)

  1. mount /dev/xvdd /cdrom
  2. dpkg -i /mnt/Linux/xe-guest-utilities*i386.deb (OR dpkg -i /mnt/Linux/xe-guest-utilities*amd64.deb for 64-bit appliances)
  3. umount /mnt
  4. sudo reboot
Adrian Moya's picture

Glad to see you made this. Would you be so kind to make an entrance on the community documentation on this procedure? That way we can always point to your explanation when someone had the same question.


Jeremy Davis's picture

I'm really glad this is now working. It definately deserves a place in the wiki (the Dev wiki?). Nice work.

sbscherer's picture

Please feel free to help keep the instructions up-to-date.  Thanks to everyone who helped to get this worked out.

Jonathan's picture

First at all, HAPPY NEW YEAR! I hope you're fine guys.

I'm very glad with this work, it's just work perfect, i tested installing the TKL Torrent 11.0 from the iso and WORKS! =D Thanks to everyone once and once again.

I don't know if this is the right place to ask, But i have a little question, can i get back the initial TKL config blue-screen? (the screen with all used IPs and network configuration options?

Thanks Again for the wiki =D

And THANKS in advance for the help

Jeremy Davis's picture

If not, try using the full path: /usr/bin/confconsole

Dan 's picture

Tried the PV  unsuccessfully with the New Debian Builds just released.  Any ideas?

Jeremy Davis's picture

The new v12.0 TKL appliances are now based on Debian so the original process may require some subtle tweaks. As above, if you can find some instructions that work with vanilla Debian Squeeze/6.0 then that will give you a good starting point for adapting TKL.

Post new comment