Stuffer 2.0 Readme ************************* IMPORTANT! ************************* This version of Stuffer requires Azureus 2.3.0.5_B47 or higher to work.  It will not load in earlier versions. Also, Stuffer does require a significant, although intermittent amount of CPU usage to purge the filters, so before you report any bugs to the authors of Azureus about heavy CPU usage, be sure to test Azureus without this plugin! ************************* IMPORTANT! ************************* Sections: 1 - Overview 2 - Installation 3 - Basic Plugin Settings 4 - Main Stuffer Tab 4.1 - Activity Tab 4.1.1 - Top Row Settings 4.1.2 - Client Blocking Information Settings 4.1.3 - IPFilter Removal Information Settings 4.1.4 - Capture/Save Block and Purge List Information 4.2 - Settings Tab 4.2.1 - Buttons 4.2.2 - Client Filter List 4.2.3 - Add New Clients Dialogue 5 - Examples 5.1 - Activity Tab Examples 5.2 - Settings Tab Examples 5.2.1 - Simple Filter Examples 5.2.2 - Regex Examples 6 - Acknowledgements ============================================================== 1 - Overview Stuffer will kick/ban peers that match the filter strings you set. The IPs of these peers are then added to the Azureus IP Filter list. Stuffer will periodically purge the IP Filter list of all IPs it has filtered. Stuffer also checks all the peers once every minute for any that may have escaped detection. Escaped peers that are caught will be kick/banned as normal. As of v2.0, you may now enter up to 200 filter strings, and filter strings now support regular expressions, thus giving you a virtually unlimited set of filters. Filters will be saved to the clientlist.config file in your stuffer folder. Be sure to create a backup of this file when updating in the future. -------------------------------------------------------------- 2 - Installation If you wish to use the Azureus Plugin Installation Wizard, go to Plugins -> Installation Wizard. Choose "By file" and click Next. Browse to the location where you saved stuffer_2.0.jar, select it, and click Next. Choose the type of installation you prefer and click Finish. Alternatively, create a new "stuffer" folder in your Azureus\plugins directory and place the stuffer_2.0.jar file there. In Windows, the path should be similar to the following: C:\Windows\Application Data\Azureus\plugins\stuffer\stuffer_2.0.jar -------------------------------------------------------------- 3 - Basic Plugin Settings These settings can be found by going to Tools -> Options -> Plugins -> Stuffer. "24hr Time": Check this box to change any times shown in the plugin to the 24 hour format, including European style date (dd:mm:yy). Note that the "Next Auto Purge" time will not change until it is updated, and times from entries in the two list boxes that came before checking this option will not be changed. "Auto Open": Check this box to have Azureus automatically open the Stuffer Tab when starting Azureus. -------------------------------------------------------------- 4 - Main Stuffer Tab This is where you will find nearly all of the information and settings. To enable it, in the Azureus menu bar, go to Plugins and select Stuffer. ================================ 4.1 - Activity Tab This tab is where Stuffer reports what peers have been stuffed and which IPs have been purged from the IPFilter. Rules for the automation of these processes as well as manual methods are both available in this tab. -------------------------------- 4.1.1 - Top row settings "Check PeerID every [x] seconds for a total of [y] seconds.": When a peer first connects with you, Stuffer checks how long the peer has been connected with you. After x seconds, Stuffer will check the peer against all of your filter rules (see section 4.2 - Settings Tab). It will perform this check every x seconds thereafter until a total of y seconds have elapsed. At that point, Stuffer will no longer actively check that peer. *** IMPORTANT: DO NOT SET X TO BE GREATER THAN Y! If x is larger than y, Stuffer will remove the peer from its check routine BEFORE the first check interval arrives. This means Stuffer will not check your peers through the normal checking process! DO NOT SET X TO BE GREATER THAN Y! *** You may notice higher CPU usage when x is set to a low number and/or y is set to a high number. Please use common sense when choosing your settings! The recommended setting for x is from 5 to 10. For y, between 20 and 30. For examples, see section 5.1 - Activity Tab Examples. "Re-Zero Counters" button: This button will reset the various counters to 0 (zero). Note that this does not affect any timers. "Clear All Lists" button: This button will clear both lists in the "Client Blocking Information" and "IPFilter Removal Information" boxes. -------------------------------- 4.1.2 - Client Blocking Information Settings Pause button: When depressed, this will cause all of your filter rules to be ignored. NOTE: Ignoring your filter rules will also cause Stuffer to not catch escaped peers. "Clear List" button: Clicking this button will clear the blocked clients list. -------------------------------- 4.1.3 - IPFilter Removal Information settings - The Big Red X: When depressed, Stuffer will ignore all settings to auto- purge the Azureus IP Filter List. This does NOT stop/pause the timer. Timer box: Enter how often you want Stuffer to auto-purge IPs in the Azureus IP Filter list. Time is in minutes and must be a minimum of 1 minute and a maximum of 10000 minutes. Only IPs that were filtered by Stuffer will be auto-purged. All other IPs in the IP Filter list will be ignored. "Restart Timer" button: Clicking this button will cause the IP Filter auto-purge timer to restart counting from the beginning. The new time scheduled for auto-purging will be shown after "Next Auto Purge." Trash Can button: Clicking this button immediately purges the Azureus IP Filter List of all IPs filtered by Stuffer. In other words, it trashes all IPs that you have Stuffed so far. Clicking this button has no effect on any auto-purge settings. "Next Auto Purge": Shows the time Stuffer will initiate the next auto-purge. "Clear List" button: Clicking this button will clear the list of IPs that have been purged from the IP Filter. -------------------------------- 4.1.4 - Capture/Save Block and Purge List Information To capture a single line from either list, right-click on the line and select "Copy the selected line to the clipboard". To save either the Block List or Purge List to a file, right- click on the appropriate table and select "Save table contents to file". A save dialogue box will pop up. Either select the file you want to use, or enter the name of a new file and click Save. If you save to a new file, nothing else needs to be done. If you choose to save to an already existing file, a new pop up will appear with three choices: Overwrite, Append, and Cancel. Overwrite: This will erase everything currently in the file before writing the contents of the table to it. Thus, the file will contain only the contents from your save. Append: This will add the contents of the table to the end of the file. The file will then contain both the data you just saved and whatever data was in there before. Cancel: Cancels the save action. Nothing is written to the file. The file is not changed in any way. NOTE: You can also hit Esc on your keyboard to cancel the save at any time. ================================ 4.2 - Settings Tab This tab is where you create and manage your filter rules. -------------------------------- 4.2.1 - Buttons The Green Plus button: Click this button to begin adding a new client-filter rule. See "Add New Clients Dialogue" below for more information. The Red X button: When a client-filter rule is highlighted, click this button to remove that rule. The Information button: Clicking this button will pop up a window with a brief reminder of how to use the Settings Tab. -------------------------------- 4.2.2 - Client Filter list "Filter" Column: This column shows the filter string for the rule. The string can either be simple or a regular expression. Double- clicking the string allows you to edit it. To keep the changes you made, hit Enter or just click outside the filter string. To cancel your changes, hit the Escape key. "Expression Type" Column: This column shows whether the filter string is a simple or regular expression. Clicking on the expression type will allow you to change it via a drop-down menu. "Downloading" Column: This column shows if the filter is being applied to all of your downloading torrents. To disable this rule for a filter, simply uncheck the box. "Seeding" Column: This column shows if the filter is being applied to all of your seeding torrents, INCLUDING torrents that you have set to SuperSeed. To disable this rule for a filter, simply uncheck the box. "only if SuperSeeding" Column: This column shows if the filter is being applied ONLY to your torrents that are set to SuperSeed. NOTE: This rule is exclusive! If this box is checked for a filter, the Download and Seeding options for that filter will be automatically unchecked. Similarly, if either the Download or Seeding option is checked, "only if SuperSeeding" will be unchecked. "Color" Column: This column shows the color applied to each filter's information strings when they appear in the Activity Tab. Double-click the color to change it. -------------------------------- 4.2.3 - Add New Clients Dialogue After clicking on the Green Plus button, you will be presented with a dialogue for making a new filter. In the text box, enter the string you want to have Stuffer use when checking against connecting peers. You can use either a simple string or a regular expression (regex). Simple strings are not case sensitive. Regexes are. Filters can match ANY portion of the client ID. (For examples, see section 5.2.1 - Simple Filter Examples.) IMPORTANT: If you enter a regex, you MUST choose "RegEx (complex match)", or Stuffer will assume you're using a simple string. (More on regexes can be found in section 5.2.2 - Regex Examples.) All that's left is to then choose the color you want applied to the filter's information strings when they appear in the Activity Tab. Remember, this color can be changed at any time as explained under "Color Column" in section 4.2.2 above. Click Accept to create the new rule. Click Cancel to abort the new rule creation. -------------------------------------------------------------- 5 - Examples A few examples of key functionality. ================================ 5.1 - Activity Tab Examples "Check PeerID every [x] seconds for a total of [y] seconds." Let's say x=3 and y=20. Stuffer will check each peer on the 3rd, 6th, 9th, 12th, 15th, and 18th seconds that peer has been connected. The 21st second would be the next time Stuffer checks, but the client is removed from the checking routine before then because the time limit is set to 20 seconds. If x=15 and y=10, then Stuffer never gets around to checking the peer. This is because the first time Stuffer would attempt to check would be on the 15th second, a full 5 seconds AFTER the peer is removed from the checking routine! Remember, x cannot be greater than y! ================================ 5.2 - Settings Tab Examples Here are some examples of how filters work. -------------------------------- 5.2.1 - Simple Filter Examples A simple string filter "a" will block any client with that letter in it, regardless of the letter's position in the client name, and regardless of whether it is capitalized or not. Here are a few clients that would be blocked using this simple filter: Azureus, Mainline, BitTornado, Shad0w. A regex filter "a" will block any client with that letter in it, regardless of the letter's position in the client name, but the case must be the same. Thus of the clients listed in the previous example, Azureus is the only one that would NOT be blocked. -------------------------------- 5.2.2 - Regex Examples Because of the large number of filters Stuffer now allows you to create, it is possible to use only simple strings for nearly all your needs. In fact, you would need to be seperately filtering each version of nearly every client currently in existance to run out of filters. However, going to such extreme lengths can get tedious. That's why it is now possible to use regexes (regular expressions). Regexes are a very powerful tool. It is possible to make a single filter using a regex that is capable of catching all the clients you wish to see Stuffed. However, regexes have a very strict syntax that must be followed, and explaining that syntax is beyond the scope of this Readme. For that reason, it is strongly recommended that you stick with simple strings unless you are willing to learn how to properly use regexes, which you can do by visiting the following website: http://www.regular-expressions.info/ Following are some simple regex examples to give you an idea of what they are capable of doing in Stuffer. Bit(Tornado|Comet|Lord|Spirit) This regex filter is the same as the four seperate simple string filters "BitTornado", "BitComet", "BitLord", and "BitSpirit". BitComet\s0\.[0-5][\d] This will block all BitComet versions from 0.00 to 0.59. Azureus\s([^2]|2\.[^3]|2\.3\.[^0]|2\.3\.0\.[^4]) All versions of Azureus except version 2.3.0.4 will be blocked by this regex. Azureus\s([^2]|2\.[^3]|2\.3\.[^0]|2\.3\.0\.[^4])|Bit(Tornado|Lord|Spirit|Comet\s0\.[0-5][\d]) This last example is just one way to combine the three example filters above into one large regex filter. -------------------------------------------------------------- 6 - Acknowledgements To the Azureus devs for their continuing efforts to bring us the best bittorrent client in the world! This plugin wouldn't exist without them. To our families for their support in all we do. We may make our livings doing other things, but that doesn't mean we can't thank our families. :) To those who report bugs and request new features. Need we say more? And finally, to everyone who uses Stuffer. Your support is what keeps us working on this project. Thank you, The Stuffer Team ---------------- If you have any bug-reports, comments, questions, or requests about this plugin, send an email to omschaub at users.sourceforge.net, or post to the following thread on the Azureus forums: http://sourceforge.net/forum/forum.php?thread_id=1376095&forum_id=377614