Customizing the WebConverger Kiosk – The fast way

Recently I was asked to assist a co-worker find a good locked down Kiosk solution for a local coffee shop. The project requirement was small – mostly just a simple browser.

There seems to have been a LOT of Linux based Kiosk projects out there, most of them now deprecated. After a bit of searching, I came across a good one – WebConverger.


Webconverger is a Live Debian build, created and maintained by Kai Hendry using the Debian Live-builder packages. The LiveCD includes the lightweight  Dynamic Window Manager (DWM) , the IceWeasel browser with Webconverger kiosk extension (to lock things down), and… well that’s about it.

Kai has excellent documentation on rolling your own Webconverger LiveCD using his GIT repository, although being pressed for time I opted to go the BraindeadProjects route: Just modify his already released ISO.

To begin modifying it in this manner, first mount the iso using a loopback device:

#mkdir /mnt/webconverger
#mount -o loop webc-7.2.iso /mnt/webconverger

Next mount the SquashFS image, also using a loopback device:

#mkdir /mnt/webconverger-filesystem
#mount -o loop -t squashfs /mnt/webconverger/live/filesystem.squashfs \

As these two mounts are readonly, we need to create editable copies of each.

#mkdir /devel/isolinux
#rsync -av /mnt/webconverger/ /devel/isolinux/

#mkdir /devel/squashfs
#rsync -av /mnt/webconverger-filesystem/ /devel/squashfs/

Now we can go about modifying these two directories. Changing out the ISOLINUX boot splash image is an easy start. The image found under /devel/isolinux/isolinux/splash.png is actually an LSS16 image. To replace it, take or create an image 640×480 in size, and convert it to 14 indexed colors. (In GIMP, these options are under Image/Index)

Indexing Colors in Gimp

Once complete, save your image in PPM format.

Next, you’ll need the syslinux package installed on your machine. The syslinux package includes a handy utility to convert PPM to LSS16 (for use as a bootsplash image)

#ppmtolss16 < /tmp/myimage-boot.ppm > splash.png

Since you’re already working on the ISOLINUX side of things, I recommend looking at and revising your boot menu. Once I have an image that I’m happy with, I set the following options to prevent someone from rebooting the Kiosk and tampering with boot parameters:

menu background /isolinux/splash.png
default /isolinux/vesamenu.c32
noescape 1
nocomplete 1
prompt 0
timeout 15
allowoptions 0

While you can nest a number of ISOLINUX boot configs together, I generally keep it to one file that includes the above directives. Dont’ forget to include at least one label for a kernel to boot.

After updating the Boot Splash screen, have a look at /devel/squashfs/home/webc/ This script is what causes IceWeasel to start, restart if closed, and sets the desktop background image (amongst other things). This script also downloads a background image from your homepage at boot – which can come in handy if you want to rotate daily ads.  I’ve personally modified my installation to always load the same background image, and fullscreen that image.

The webpage that appears each time IceWeasel starts is passed as kernel boot parameter (homepage). To update the homepage, simply edit the labels in the ISOLINUX  directory.

You will notice that when pressing the home button in the browser however, that you’re actually taken to an about: page that gives details about the current IceWeasel build. To configure this homepage, look at /usr/lib/iceweasel/

I personally like to lock things down a bit more than the standard release. For that reason I also add the following to /etc/iceweasel/pref/local.js

pref(“network.protocol-handler.external.snews”, false);
pref(“”, false);
pref(“network.protocol-handler.external.irc”, false);
pref(“network.protocol-handler.external.mail”, false);
pref(“network.protocol-handler.external.mailto”, false);

Another thing that may prove beneficial is to remove any and all remnants of xterm. As xorg does depend upon xterm, it will have to be forceably removed. This is best done in a chroot environment

#chroot /devel/squashfs/ /bin/bash
#dpkg –force-all -p xterm

Once you have your modifications complete, you will want to re-squash the squash filesystem. To do this, you’ll need squashfs-tools version 4 (Centos is currently distributing version 3, so do keep that in mind). Squashing using version 3 of the tools will result in a non-bootable kiosk.

#mksquashfs /devel/squashfs/ /tmp/webc.squashfs
#mv /tmp/webc.squashfs /devel/isolinux/live/filesystem.squashfs
#cd /devel/isolinux/
#mkisofs -o /tmp/my-webc.iso -b -r -J -l -cache-inodes -allow-multidot -no-emul-boot \
-boot-load-size 4 -boot-info-table -b  isolinux/isolinux.bin -c isolinux/ \

Finally, isohybrid your ISO:

isohybrid /tmp/my-webc.iso

I highly recommend testing your ISO image in VirtualBox. Using VirtualBox (or any other virtualization option), saves you from constantly burning an image to  a CD or USB drive. Be mindful that you can skip the isohybrid step and test with VirtualBox, although you won’t be able to install it later using dd.

Once you have an image that you’re happy with, use dd to copy the ISO onto the hard drive of your Kiosk machine. Personally, I copy my ISO to a USB thumbdrive running the Gentoo Based  System Rescue CD, boot into it and then install onto the harddrive:

dd if =/livemnt/boot/kiosk/my-kiosk.iso of=/dev/sda


Of course, one could save time and simply use the WebConverger Customization Service… but why not use this as an opportunity to sharpen one’s skills.

Coming soon to – a walkthrough on how to build and customize a WebConverger ISO from Kai’s GIT repository (as opposed to re-rolling his ISO).

20 thoughts on “Customizing the WebConverger Kiosk – The fast way”

  1. Cheers for the info. This is exactly what im looking for. Done a similar project with other linux distros, but they I never got them locked down in the way that webc does it.

    looking forward to “customize a webc iso from the GIT repository”, and hopefully i can then add in some wireless connectivity to the webc -> its the one thing that lets it down.

  2. Thanks! Hey, what kind of wireless connectivity are you looking to add? Kai has things setup so that you can pass a boot variable “wlan=ESSID,KEY” to cause WebConverger to connect to that ESSID using a psk. If it’s an open AP, you can simply do “wlan=ESSID,” (The ending comma is necessary).

    Should have the GIT repository tutorial up soon.

  3. Thanks so much for this information !
    I’m really excited to see the next tutorial with the GIT because I will like to be able to customize more deeply and able to update the Firefox version is needed (and add some plugins if possible).


  4. Thanks so much for this information !
    I’m really excited to see the next tutorial with the GIT because I will like to be able to customize more deeply and able to update the Firefox version is needed (and add some plugins if possible).

    Any idea when it will be online ?

  5. Thanks! I’ll see if I can get the GIT tutorial done in the next 2 weeks… I’ve got a bit of traveling and “domestic” duties, but I should have that shortly.

  6. Very nice howto. One minor comment, however, wouldn’t you want to chroot into /devel/squashfs/ instead of /mnt/webconverger-filesystem ?

  7. Ah, you’re absolutely correct – thanks for pointing that out. My proofreading isn’t the best at times (and I write from notes and not bash history).

    Thanks for the help!

  8. I’ve been pretty busy the last few months, which has unfortunately cut down on the amount of time I’ve had to write. Thankfully things should die down a bit after the holidays.

    Are you working with Webconverger right now? I’d be interested in your thoughts on it.

    In the meantime you might look over Kai Hendry’s developer wiki here –

  9. I’ve spent a while working on it, its really working out great for our touchscreen kiosks.

    Just a note on your post: the reason your homepage button isnt working is probably because you changed the hostname. A init script checks the value and exit’s before the homepage pref is set.

    The way I changed that script and other things within wc’s repo is just place the file within includes.chroot, since it’s used after the packages are installed.

    Other thing i’ve been working on is a way to change the grub screen without respinning the ISO.

  10. Hi. I am trying to modify a webconverger iso and I came across your post. I am having trouble with the command #mount -o loop -t squashfs /mnt/webconverger/live/filesystem.squashfs /mnt/webconverger-filesystem

    It gives me the error
    mount: mounting /dev/loop1 on /mnt/webconverger-filesystem/ failed:No such device

    I am using these commands in a virtualbox running Slitax Linux 4.0. I downloaded the webconverger iso and mounted it.

    Your help will be greatly appreciated.

  11. Hi Nick, thanks for checking out BraindeadProjects.

    The error message that you’re receiving is due to Slitaz not having the squashfs kernel module. It’s compiled in, but they appear to have removed it from their live cd:

    #zgrep CONFIG_SQUASHFS= /proc/config.gz

    #find /lib/modules/`uname -r` -name “*squash*”

    #losetup | grep loop1
    /dev/loop1: 0 /mnt/webconverger/live/filesystem.squashfs

    So it looks like it loop mounts the file fine, but can’t mount the squashfs filesystem onto /mnt/webconverger-filesystem.

    You’ll unfortunately not be able to use Slitaz in this instance. You might consider using the excellent “System Rescue CD” available at or another live cd.

    If you try to use something else, you’ll want to verify that it has squashfs support. Here’s how you can check:

    #grep squashfs /proc/filesystems

    If it doesn’t list squashfs, you might try “modprobe squashfs” and see if it’s present. If not, move to yet another live cd.

    Good luck!

  12. Thank you for your prompt response, I will give System Rescue CD a try. In the meantime, I found out that the changes that I make to a live distro boot parameters do not transfer to a hard-disk install.
    So, I have one more question for you if you do not mind.
    If I install webconverger on a hard-disk, and I boot up with System Rescue CD Live, are there any files that I change in the webconverger installation, so I can bypass the config screen, change the homepage, and replace the hosts file?

  13. I’m not sure where you found that information, but I can assure you that it’s false. In fact, all of the changes in this article were later installed onto a harddrive in a coffee shop where it’s run perfectly for ages (I should probably update it since Kai has released a newer version of WebConverger, but haven’t found the time).

    What I would do is follow this article step by step and get your first instance up and running on a hard drive (The article walks you through everything), and go from there. As I demonstrate, you can change the homepage, etc. If you wanted to, you could alter the /etc/hosts file as well.

    Save your .iso image – any subsequent changes could then be done by following the loop mount procedures again, but this time using your customized iso instead of the webconverger release. (In fact, I had a number of revisions before I was finally happy with my work)

    The config screen that you’re referring to is probably the ISOLINUX boot screen. Where I specify “timeout 15” you may try “timeout 0”. If that doesn’t work, consult the ISOLINUX manpages for how to bypass the menu.

    Let me know if you have any other questions, I try to get back to people as quickly as I can. But yeah, you can modify pretty much anything you want in WebConverger. (Either using my method or compiling from Kai Hendry’s repository)

    Good luck!

  14. Hi,

    Using another distro (Knoppix), I followed your instructions (edited the live.cfg file) and it worked like a charm when I booted off live. It kept all my changes for homepage, bypassing configuration, etc.

    Then I installed it using the menu option at boot time. This is Webc 13.0 and one of the menu options is to install it to the hd. However, when I booted off the hd, it forgot all my settings. Maybe the installer does a full install of the distro, and my isolinux boot parameters do not work anymore.

    You said that you dd the iso to an hd and boot to it using System Rescue Cd. Is that sort of having a frugal install? You do not install it right? You just dd the iso to the hd and boot off it live.

    So, I am assuming, you do not need the System Rescue Cd after booting and the read speeds should be faster since the iso is on the hd.

    In short, can you clarify how you boot to the iso after you dd it to an hd?

  15. Excellent news. I’ve not looked at WebConverger 13 yet, I don’t believe that install option was present in the version I used.

    I’m guessing that the install option may download the latest version of WebConverger and install it, and not simply install what you have currently running. This would make sense for a handful of reasons (which I won’t elaborate on now). Try to use the dd method to write your iso to a drive.

    When you dd the iso onto your hard drive, you are installing it. (So, obviously you want to be careful not to overwrite a hard drive that you didn’t intend to).

    **Make sure you isohybrid your iso image before you install it via dd. If you don’t it simply won’t boot off the hard drive.

    Once you dd the isohybridized iso onto the hard drive, remove any livecd or usb thumbdrive from your machine and it should just boot right up off the drive. You’re basically installing an image that can be either booted off a cd-rom or BIOS recognized drive. More information on that here:

    It sounds like you’ve made some good progress and are in the final few steps of getting your system up and running. If you like WebConverger (or any open source piece of software for that matter), I’d encourage you to contribute back to it in any way that you can. Bug reports (preferably with patches if you’re capable), a small donation, or at the very least an email to the author saying “thanks for all of your hard work” tend to be appreciated and keep the fire going. (I’m not affiliated with WC, I only found it extremely useful and filling a major void – there are seemingly no other free Kiosks out there)

    Developers have a lot of time invested in these things, and a lot of really good projects have become deprecated due to lack of interest, time, participation, or voiced appreciation.

  16. Hello.

    When I enter
    /mnt/webconverger/live/filesystem.squashfs \

    I get:
    I then enter after the >,

    I get:

    bash: /mnt/webconverger/live/filesystem.squashfs: No such file or directory. Suggestions?

  17. This writeup was for a previous version of WebConverger, which used squashfs. It appears the current version has migrated to gitfs fuse. You’ll need to dig into that for modifications, I’ll see if I have time for a followup article early next year.

Leave a Reply

Your email address will not be published. Required fields are marked *