Gentoo Wiki









This HOWTO is now for beagle-0.1.1.

Update (10/26/2005) - beagle has been included in portage. Just emerge app-misc/beagle to get the latest and greatest, hooray!

A more up-to-date Gentoo installation guide can be found on the official Beagle wiki

The related discussion in gentoo forums is taking place here.


First step is optional but strongly recommended for best experience with beagle - It is to compile the kernel with the inotify support (Robert Love's new implementation for notifying user-space about changes to files/dirs). You can thus skip the inotify step of the installation and come back after you are finished installing beagle.

Gentoo's kernel sources now include the inotify patch. This can be installed by installing the gentoo-sources ebuild with a version >= 2.6.11-r3, although a kernel >=2.6.13 is required for the official beagle ebuild.

Correspondance between Beagle, Inotify and Gentoo-sources version-number

Beagle Inotify Gentoo-sources 0.20 2.6.11-r3(*)
0.0.9 0.21 2.6.11-r4(*) and -r5(*)
none 0.22 2.6.11-r6(*) to -r11
0.0.10 and 0.0.11 0.23 2.6.12
0.1.0 and above 0.24 2.6.13

(*): currently removed from portage for security reasons

Note: inotify has been placed back in to the current (2.6.12-gentoo-r4) kernel version as the unmount bug has been fixed.

See Gentoo Bug #67768 ( for progress on getting this into the portage tree.

Versions of the Vanilla Sources prior to 2.6.13 do not include the inotifypatch, to support inotify you have to download the patch. Get it here (You need the one that matches your kernel). To patch your kernel do something like that:

cd /usr/src/linux
patch -p1 < /path/to/inotify...patch

Once the kernel sources are patched you need to make sure it's configured correctly in menuconfig:

Code: menuconfig
File Systems >
[*] Inotify file change notification support

Don't recompile your kernel just yet, because you probably need to enable extended attributes in the next step.

According to [1] there is no /dev/inotify now that inotify support is part of the standard kernel. The interface is through sys calls. You should be fine as long as you have beagle >=0.0.14 and a kernel >=2.6.13

Extended Attributes

Very important (and NOT optional) is to enable extended attributes for your filesystems. Again, in the kernel configuration:

As of version 0.0.12 extended attributes are no longer essential for beagle to function:

Code: menuconfig
File systems >
<*> Second extended fs support
[*]   Ext2 extended attributes

That's for ext2. Do the same for Ext3 or Reiserfs according to your need. XFS and JFS include extended attributes out of the box, no additional configuration is needed.

After that compile and install your kernel, and if appropriate, update your bootloader config as usual.

Extended attributes need to be enabled in /etc/fstab too, so you should add the to your filesystem[s] "user_xattr" option, e.g:

File: /etc/fstab
/dev/hda4 / reiserfs noatime,notail,user_xattr 0 0

If you are running a live system with extended attributes enabled in your kernel but not active on your filesystem, you can enable them without rebooting:

mount -o remount,user_xattr /

Note: If you have updated /etc/fstab and run above command, you'll get: /dev/md4 on /data type ext3 (rw,noatime,user_xattr,user_xattr) I don't know, if this is only cosmetic issue.

Download ebuilds

Untill recently, beagle ebuilds only were available from this bug report. Beagle has made it into portage, so it is no longer necessary to download ebuilds there. Nevertheless, there's still some discussion going on which is worth following, and there are still ebuilds posted. As those differ from the version in portage, you might want to try one of those if you encounter problems with the official portage ebuild. If you do so, the ebuild needs to be put in your overlay (Assuming you have one, or know how to configure it). Keep to the portage category and put it in /usr/local/portage/app-misc/beagle/.

It is possible that you will have to download a different ebuild version. In that case you might need to rename the file you download to represent beagle-0.1.1, e.g: beagle-0.1.1 etc... It is also recommended that you follow the discussion on that bug report.

Once you have downloaded the ebuild, you need to 'digest it' so it can be emerged: -

ebuild /usr/local/portage/app-misc/beagle/beagle-0.1.1.ebuild digest

If you wish beagle to index your address book from evolution, enable the 'eds' USE flag. Recently this will pull in evolution-sharp to the merge. Prior to recent portage distributions one would have to download the evolution-sharp ebuild here. Place it in /usr/local/portage/dev-dotnet/evolution-sharp/ and digest it:

# ebuild /usr/local/portage/dev-dotnet/evolution-sharp/evolution-sharp-0.6.ebuild digest

Note that even without the evolution-sharp/evolution-data-server packages beagle will index your Evolution emails. These packages are only needed if you wish beagle to index your address book too.

Unmask packages and emerge Beagle


AMD64 user no longer need to edit portage.mask or portage.keywords, all beagle related packages are now marked stable on that architecture and a simple emerge app-misc/beagle is all that is required


Before you can actually emerge beagle, you still need to make sure all dependencies are unmasked. The most important package is mono. Mono has two branches: stable and development. As of the latest version, the mono team recommends the development release (1.1.9) over the stable (1.0.6), and I suggest you follow that recommendation. I have had great results with that release; mono 1.1 is much faster, and results in much reduced memory consumption.

NOTE: dbus is no longer required for the latest versions of beagle.

It is important to unmask dbus/mono/libgdiplus and beagle itself so you use the latest version of it in portage, so add to /etc/portage/package.keywords:

File: /etc/portage/package.keywords
sys-apps/dbus ~x86
app-misc/beagle ~x86
dev-lang/mono ~x86
dev-dotnet/libgdiplus ~x86

The easiest way to find out what other packages need to be unmasked in /etc/portage/package.keywords and /etc/portage/package.unmask is to run: # emerge -av app-misc/beagle

And see what ebuilds that are needed are masked. then just add those to /etc/portage/package.keywords and/or /etc/portage/package.unmask in the category/package-name form. Note that contrary to popular belief, there is no need to append that with a specific tree such as "~x86".

Also you need to add to your USE flags: "mono" and "dbus", and optionally "eds" too in your /etc/make.conf.

Probably you also want to set the following USE flags to enable more features in beagle: "firefox" and "epiphany" and "webservices". "firefox" enables an extension /usr/share/beagle/beagle.xpi, which you have to install. You can install this extension by pointing to the adress in the browser. The "webservices" USE flag enables a really nice search webinterface. More information about the webinterface here.

Continue to unmask all packages until eventually beagle and all its dependencies are emerged.

Seamonkey vs. Firefox

There is an annoying inaccuracy in the current gecko-sharp ebuild that makes Beagle indirectly dependant on Seamonkey (Mozilla Suite). Whether or not the suite it is required for the mozilla extension to function properly (I don't know), gecko-sharp will compile with firefox and gecko-sdk and a Beagle install built with the resulting gecko-sharp will run normally.

My solution was to simply remove the Mozilla dependency from gecko-sharp-0.6.ebuild, put it into the overlay, and wait for someone less lazy to figure out exactly what part of my favored setup is the minimum required replacement for Seamonkey in this case.

Restart system

NOTE: dbus is no longer required for the latest versions of beagle.

If you haven't done so yet, it's probably time to restart your system, so the recompiled kernel gets loaded, as well as the filesystem mounted with extended attributes support. DBUS has two daemons: a system daemon and a session daemon. To have the system daemon started add its init script to the default runlevel (if you haven't already done so):

# rc-update add dbus default

The latest dbus ebuilds take care of automatically starting the DBUS session daemon when you log in to your session. (I'm removing now my instructions on manually getting it to work...)

NOW you are ready to restart your machine! Good luck!

Running Beagle

Now we are ready to launch beagle itself, which is a daemon that indexes your files/data and allows searching through. Generally it should be running all the time. I suggest that for a start you run beagle in the foreground to see that it works OK:

$ beagled --fg --debug

If you receive an error here and beagled quits, it is possible that either dbus is not running, your environment is not set correctly, Inotify is not installed or extended attributes are not setup.

Code: ps ax|grep dbus
10453 ?        Ss     0:00 /usr/bin/dbus-daemon-1 --system
17518 ?        Ss     0:00 dbus-daemon-1 --fork --print-pid 8 --print-address 6 --session
18655 pts/2    S+     0:00 grep dbus

So you can see that both the system DBUS daemon and the user session daemon are running.

To check if environment is set correctly:

Code: export|grep DBUS
declare -x DBUS_SESSION_BUS_ADDRESS="unix:abstract=/tmp/dbus-pfX5xlSlMV"

Note: Newer versions of Beagle do not need DBUS anymore. [As of beagle-0.3.6, the "beagle-search" gui tool uses DBUS. You may need to use dbus-launch to run beagle-search, ex: dbus-launch beagle-search; this is almost always true if using gnome tools but not running in the gnome-environment. It may be beneficial to alias beagle-search to "dbus-launch beagle-search"]

To check if Inotify is enabled and working just look if you got a /dev/inotify. To check if extended attributes are used run:


and check to see in the output user_xattr set on your filesystem[s]:

/dev/hda3 on / type reiserfs (rw,noatime,notail,user_xattr)

If you are having other problems, you should read the Troubleshooting Beagle wiki page.

If the beagle daemon seems to run fine, you can just run it with:


The daemon will fork and start indexing your data. This takes a bit of time. You can monitor what the daemon is doing/indexing by running:


Contrary to a comment made here (btw, what again is the use of the "discussion and bugs" tab?) beagle does work with reiserfs V3, which is what you most probably use if you haven't patched your kernel manually to include V4. V4 indeed doesn't work with beagle, as stated on the beagle website (further info: discussion and bugs).

Running Beagle regularly

Once everything works correctly you might consider adding beagled to your startup programs, either (if you're using Gnome) by adding it to your Gnome session or by adding a shell script to your Desktop/Autostart directory.
Gnome-Session: In the gnome-session preferences dialog add 'beagled' to the list of "Startup Programs" (The third tab).

exec beagled

Using Beagle

Now that dbus and beagle are running you have two ways to perform a beagle search. One is through the command line tool:

beagle-query search_term

Running that should output the data that matches your search_term. The other way is through the beagle-search tool which is a GTK+ GUI. Run the command:


Once it's running, pressing on F12 will show the search window, through which you perform the search. Both methods talk to the beagle daemon through DBUS, so you have to make sure that on the console or terminal where you run them you have the proper environment setting needed for DBUS to work. You can check this according to the instructions mentioned earlier in step 5.

Under KDE 3.5.9 and beagle-0.3.6, you may need to use dbus-launch to run beagle-search. For example: dbus-launch beagle-search. You may prefer to change the Command in the menu editor under Utilities, Search to "dbus-launch beagle-search. While editing the Search item, you may want to set the Current shortcut key to F12 (or your pleasure).

Mozilla Firefox Extension

Another feature you can easily add to Beagle, is the option to index the webpages you visit in Firefox. This is done through a Firefox extension that comes with Beagle. Once you install the extension and enable it through Firefox, beagle will index the webpages you visit, and will then return results about webpages matching your search term. To install the extension open a Mozilla Firefox window, and put in the address bar:


note: new versions of beagle don't build this extension. indeed even the old extension has been removed from the beagle pages. See here: [2]

Press Enter and you will be prompted to install the extension. After that you will need to restart Firefox, and then in the Extensions window (from the Tools menu), you can change the Beagle extension's options (enable it...). A small beagle icon will appear on the status bar, bottom right, of Firefox, which allows you to quicly enable/disable the extension. Also keep in mind that you will need to have ENV variables of dbus available to Firefox.

The firefox extension is a very nice feature, but I had experience with it slowing my machine and taking up quite a bit of memory. Mono-1.1.6 has many improvements for better memory consumtion, so that's a major reason to use it. Be warned...


It is possible that you might need to remove your whole index when upgrading beagle, because beagle is in early stages of development, and index/API might not be compatible across different versions. This is done by:

$ rm -r ~/.beagle/


Installing Beagle it's possible to have a configure error related to requested libraries "gtk-sharp glade-sharp gecko-sharp = 0.6 gnome-sharp gconf-sharp gmime-sharp >= 2.1.13" not found. This error can come associated with an undefined variable (exec_prefix) in "usr/lib/pkgconfig/gmime-sharp.pc" that in fact looks like:


Name: gmime-sharp
Description: .NET binding for GMime
Version: 2.1.14
Libs: -r:${libdir}/mono/gmime-sharp/gmime-sharp.dll

Error can be recovered changing "exec_prefix" in "prefix", as previously defined.

You may need to emerge "mono" and "gtk-sharp" before "gmime" since the dependencies in the gmime-2.1.16 ebuild are wrong.

There is a problem with versions of wv before 1.0.3-r1 that will send beagled into an infinite loop while indexing MS word documents. Use wv-1.0.3-r1 or later to avoid this.

Retrieved from ""

Last modified: Sat, 06 Sep 2008 12:13:00 +0000 Hits: 80,540