Gentoo Logo
Gentoo Logo Side

HOWTO setup coLinux to run Gentoo


1. Introduction

What is coLinux? 

coLinux is a Windows daemon program. The purpose is to run the Linux kernel as a native Windows thread, and thereby run Linux natively within Windows.

The main flaw is probably performance. Performance of X applications is bad, but usable. Ordinary applications run just as fast as real Linux.

Warning: coLinux is still pretty alpha. It works and works well, but there are many things which are not yet supported.

This HOWTO is based on a compilation and merge of two excellent HOWTOs provided in the Gentoo forums by IWBCMAN and janlaur. The links to these discussions are provided below for your reference:

2. Installation

Getting coLinux 

Warning: You must run Windows 2000, 2003, or XP (Home/Professional) to use coLinux.

You only need to download the lastest snapshot from

Note: coLinux-20040417.exe was used for this HOWTO. There are also several nice bugfixes in the snapshots so we recommend that you use these.

The .EXE file is an installer program which is able to download a basic distribution image from SourceForge (Gentoo/Debian/Fedora).

Start the .EXE, leave the default values as is except, of course, when you choose your distribution, in which case you should select Gentoo.

The image will be downloaded to the installation dir and is called gentoo-i586-ext3-2g-deluxe.bz2.

This new virtual partition file contains a stage3 Gentoo installation. Actually, it is more than just a stage3 as it includes XFree86, XFCE4, Firefox, GAIM and XChat. The virtual partition is formatted in ext3.

  • Extract this file to any Windows drive that has room for a 2 gigabyte file
  • There should be no spaces in the path to this file
  • Optionally, you can delete the .bz2 file after extraction

You'll probably need Winrar for Windows to unpack it. Check out the coLinux Nice Tools page to find the tools for extracting the image files and creating virtual swap partitions.

3. Configuration

Modifying the configuration file 

There is only a single configuration file; it's located in the installation directory and is named default.colinux.xml. Open it with your favorite editor and edit it to look like this:

Code Listing 3.1: default.colinux.xml

<?xml version="1.0" encoding="UTF-8"?>
    <!-- your path may differ slightly. -->
    <block_device index="0" path="\DosDevices\e:\gentoo-i586-ext3-2g-deluxe" enabled="true"></block_device>
    <image path="vmlinux"></image>
    <!-- adjust the size to your needs -->
    <memory size="256"></memory>
    <!-- Make sure name= the exact name of the TAP device in your Network Connections!-->
    <network index="0" type="tap" name="TAP"></network>

Change the path to where you extracted the image and configure how much memory you want to allocate to coLinux.

Setting up Networking 

You should now be able to boot coLinux by double-clicking on colinux-daemon.exe, but since most people want networking, we'll configure that first. You need to install the virtual network adapter to start with.

  • Select "Add Hardware" from the control panel then click "Next"
  • Click "Yes I have already connected the new hardware" then click "Next"
  • Scroll to the bottom of the list in the next window and select "Add a new hardware device" then click "Next"
  • Select "Install the hardware that I manually select from a list" then click "Next"
  • Select "Network Adapters" then click "next"
  • Click "Have Disk" and navigate to the place where you extracted colinux to. Go into the "netdriver" directory. A file should show up.
  • Select it and click "Open"

You now have your virtual network adapter configured! You can configure it just like the other adapters already on your system.

  • Go to "Control Panel->Network Connections"
  • Click on your internet connection, and then CTRL+click on your new TAP network connection.
  • Right click, and choose "Bridge connections".

Windows should create a network bridge. If you still have an active Internet connection in Windows, then it probably works.


Now you're ready to open colinux-daemon.exe and see the magic: you're now booted in a basic Gentoo install, with programs like XFree86, XFCE4, GAIM, kernel-2.4.26 and other basic stuff at your disposal.

Once you are in, you'll want to do a few things first:

  • Login as root with no password and set the root password
  • Check that networking is running
  • Start sshd, and ssh into it with Putty (Use cygwin as your terminal type)

You'll probably want to update your system, so let's do this now:

Code Listing 3.2: Finalizing the setup

# emerge --sync
# env-update && source /etc/profile
(If you prefer to use vnc)
# emerge tightvnc

Now you need to configure X. You can simply copy over your /etc/X11/XF86Config from your Linux installation to your coLinux install (if applicable).

Note: You can only use drivers provided with X (ie. no nvidia-glx/kernel) and it only seems to work with a color depth of 16, so you'll have to edit the file a little. Remember you have no direct access to the video hardware of Windows, so you have to either copy this file from elsewhere or manually create it. Alternatively you can also just boot the machine with Knoppix and let Knoppix create a XF86Config file for you.

When that is finished create ~/.vnc/xstartup:

Code Listing 3.3: Sample ~/.vnc/xstartup

startxfce4 &

Now simply run the vncserver with your options. You will be prompted for a password, create one and remember it.

Code Listing 3.4: Starting vncserver

$ vncserver -geometry "1024x768" -depth 16

All you will need to do now is download VNC for Windows, run the vncviewer, and give it the IP address of your virtual network adapter (ie. 192.168.0.X:1) along with your password. If all goes well vncviewer should now bring up your XFCE4 desktop - have a lot of fun!

4. Advanced Topics

Adding a swap partition 

Download a swapfile from here (the file name indicates the swapsize). Extract it to wherever you have the room for it and add the following to your default.colinux.xml:

Code Listing 4.1: Adding a swap drive

    <-- index="1" means that it will be mapped to /dev/cobd1 -->
    <block_device index="1" path="\DosDevices\e:\swap-file" enabled="true"></block_device>

Now (re)start coLinux, and run mkswap:

Code Listing 4.2: Setting up your swap partition

# mkswap /dev/cobd1

You'll also need to modify your /etc/fstab to add the following line:

Code Listing 4.3: Add to /etc/fstab

/dev/cobd1	none	swap	sw	0 0

Now enable the swap without rebooting!

Code Listing 4.4: Enabling your swap

# swapon -a

Accessing your existing Linux partitions from coLinux 

The coLinux website provides a document that covers the basics. After reading that you can end up with following config:

Code Listing 4.5: New default.colinux.xml

<?xml version="1.0" encoding="UTF-8"?>
    <block_device index="0" path="\DosDevices\e:\gentoo-i586-ext3-2g-deluxe" enabled="true"></block_device>
    <block_device index="1" path="\DosDevices\e:\swap-file" enabled="true"></block_device>
    <!-- Your path may differ based on your disk layout, etc -->
    <block_device index="2" path="\Device\Harddisk0\Partition5" enabled="true"></block_device> 
    <image path="vmlinux"></image>
    <memory size="256"></memory>
    <network index="0" type="tap" name="TAP"></network>

You will have to (re)start coLinux to let the changes be taken into account. You should be able to access "\Device\Harddisk0\Partition5" through the /dev/cobd2 device in coLinux.

Code Listing 4.6: Mounting

# mount /dev/cobd2 /mnt/linux

Important: Remember that this will only work with partitions that Windows doesn't use. If Windows uses it, you need to access it through smbfs.

5. Q&A

What USE flags should I use? 

The USE are the same as the native system.

Will I be able to share my dial-up connection? 

It uses the Internet connection sharing to connect the Linux network to the outside network so you should be able to bridge the TAP connection to your PPP connection.

Can the Linux kernel still access hardware? 

coLinux emulates each type of hardware needed. You have emulated disk access, networking, etc. What isn't available yet are USB, direct graphics, or soundcard access. The good news is that coLinux is currently working on getting USB working (excluding USB keyboards and mice).

Are there any alternatives to coLinux? 


Will coLinux work with the 2.6 kernel? 

At the present time, no, it uses a 2.4 based kernel that has been patched to allow for the emulated devices as well as shared resources with Windows.

Why doesn't X work? 

There is no native X support. You must use either vnc or Cygwin-X11. Follow the directions in this HOWTO.

6. Conclusion

There is an amazing array of possibilites with coLinux. You can run Apache, Samba, DHCP, mail, distcc, NFS, you name it server under colinux. With exception of device support and disk access one cannot tell that one is running Linux under Windows which is truly amazing.

The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.
Updated October 2, 2004


Joshua Preston

Jon Portnoy

Summary:  This HOWTO is intended to provide instructions on a simple setup for coLinux to allow your Windows machine to run Linux as a thread.
The Gentoo Linux Store
Copyright 2001-2004 Gentoo Foundation, Inc. Questions, Comments, Corrections? Email [email protected].