gtk-gnutella logo
Current version: 1.1.13

Filtering mini-HOWTO

© 2002 Vidar Madsen, Markus Goetz
This is very much a work-in-progress. Please send comments and suggestions to


The filtering code in gtk-gnutella 0.90 was dramatically improved. This small howto will tell you how to deal with the power given by those filters.

Note that filters will only be applied to new search results as they come in. There is currently no way to apply them to the results that are already in the list.

State flags

When a search result arrives at the filtering engine it has two state flags; DOWNLOAD and DISPLAY. Initially the state flags are in an "undefined" state, and by applying various tests to each result, these flags can be set to DO and DON'T.

Note: As soon as both state flags are defined, i.e. set to either DO or DON'T, the filtering is aborted, and the application will proceed to DISPLAY and/or DOWNLOAD if the respective flags are set. Furthermore, each of the flags can be set only once (subsequent attempts to set them will be silently ignored), so the order in which you set up the rules is quite important.


A filter is basically a set of rules. There are three types of user-definable filters; Global filters, Search filters, and Free filters;


There are several different rule types. Most of them have some flags that might warrant an explanation;

Size rules

Size rules have three similar uses;

Name rules

Name rules perform tests on the results' filenames. The "Condition" pulldown should be quite self-explanatory.

Flag rules

The flag rules can be used to filter results based on the hosting servent's flags; "Stable", "Busy "and "Push". For example, if you are behind a firewall and unable to received pushed files, you can add a rule that directs all results with the Push flag set to DON'T DISPLAY.

Jump rules

The jump rule is used to either set a DO or DON'T flag directly, or it can be used to call one of the free filters for subsequent testing.

IP rules

IP rules filter results based on the servent's IP address. A typical use for this is to ignore certain spammer hosts which return bogus hits. Or one can auto-download results that come from a certain IP address or network which is known to be fast.

urn:sha1 rules

The urn:sha1 rules are special, and can't be edited manually. They can only be added via the right-click-menu in the search results window. They are used to match a given file, and flag it for either DON'T DISPLAY (if picked via the "ignore" menu item) or DOWNLOAD (if picked via the "auto-download" item).

State rules

State rules can be used to process results that have already been through a number of other tests. A common application for this rule is to automatically download results that haven't been marked as DON'T DISPLAY. See under "Sample rulesets" for a full example.


Sample filters

Here is a sample "movie" filter as mentioned earlier. If you set this up as a free filter, you can jump to it from the search filters to filter out a lot of bogus hits. Also, when doing a new search, you can select it on the default filter pulldown directly.

! Condition Target
  If filesize is smaller than 400000000 (381.5 MB) DON'T DISPLAY
  If filename ends with ".avi" RETURN
  If filename ends with ".mpg" RETURN

Here is a filter that will download MPEG music videos of Rammstein tracks. The trick is to use inverted conditions (note the X'es in front), and the last rule that will mark all files that aren't flagged as DON'T DISPLAY with DOWNLOAD.

! Condition Target
X If filename contains the words "rammstein" DON'T DISPLAY
X If filename ends with "mpg" DON'T DISPLAY
  If filesize is smaller than 20000000 (19.1 MB) DON'T DISPLAY
X If flag DON'T DISPLAY DOWNLOAD Logo   Glade   RSS Feed Available   Ohloh Metrics   Coverity Scan Build Status   gtk-gnutella at GitHub  
gtk-gnutella © 2000-2014 by Yann Grossel, Raphaël Manfredi and various contributors.