<wiki:toc />

ruTorrent is designed with a robust plugin system. The reason for this is to allow users to customize the behavior of the WebUI, and exlude the parts they do not need.

== Installation ==

To install a plugin, download the tarball from [http://code.google.com/p/rutorrent/downloads/list the download page] and extract it in the plugins directory. (if rutorrent is installed to /var/www/rutorrent this would be {{{ /var/www/rutorrent/plugins }}} If you use the svn version of rutorrent, you can fetch the plguins via svn as well as follows: {{{ svn co http://rutorrent.googlecode.com/svn/trunk/plugins/PLUGIN_NAME }}}

Attention! Please install only those plug-ins you really need. The more plug-ins are installed - the longer load of the ruTorrent interface.

=== plugins.ini ===

Some of the following information is also included in [Config#Limiting_Plugins(plugins.ini) Config page]_

Since 3.0, rutorrent includes a configuration file for plugins called plugin.ini. It is located at rutorrent/conf/plugins.ini. As of the writing of this wiki, the default format is as follows:

{{{ ;; Plugin's permissions. ;; If flag is not found in plugin section, corresponding flag from "default" section is used. ;; If flag is not found in "default" section, it is assumed to be "yes". ;; ;; For setting individual plugin's permissions you must write something like that: ;; ;; [ratio] ;; enabled = yes ;; canChangeToolbar = yes ;; canChangeMenu = yes ;; canChangeOptions = no ;; canChangeTabs = yes ;; canChangeColumns = yes

[default] enabled = yes canChangeToolbar = yes canChangeMenu = yes canChangeOptions = yes canChangeTabs = yes canChangeColumns = yes }}}

These options allow you to change how each plugin behaves and allow you to create a unique configuration for multiple user systems.

For a multiuser system with rutorrent installed at /var/www/rutorrent with users tom dick and harry you would do something like:

{{{ cp /var/www/rutorrent/conf/plugins.ini /var/www/rutorrent/users/tom cp /var/www/rutorrent/conf/plugins.ini /var/www/rutorrent/users/dick cp /var/www/rutorrent/conf/plugins.ini /var/www/rutorrent/users/harry }}}

and edit each accordingly. For more information about multi-user setups, see [Config] and [Installation#Single_user_(or_no_Web_Auth)OR_Multiuser(Web_Auth) Installation]

==== Explanation of plugin.ini settings ====

• enabled - this setting should be obvious, when set to yes, a plugin is enabled. When set to no, it is not.
• canChangeToolbar - this setting controls whether or not a plugin can make changes to the main toolbar.
• canChangeMenu - this setting controls whether or not the plugin can effect the rightclick menu.
• canChangeOptions - this setting controls whether or not the plugin can add to the "Settings" menu.
• canChangeTabs - this setting controls whether or not a plugin can add a tab to the tab bar.
• canChangeColumns - this setting controls whether or not a plugin can add a data column to the torrent information window.

==== An Example of how to use plugins.ini ====

So why is this useful? Using our 3 user system from the earlier example, lets say for harry and dick, you want to completely disable the [PluginRSS RSS] plugin, but you wish to allow tom access to it. You would install [PluginRSS RSS] and add the following to both /var/www/rutorrent/conf/users/harry/plugins.ini and */var/www/rutorrent/conf/users/dick/plugins.ini

{{{ [rss] enabled = no }}}

Lets say you want to let tom use the [PluginUnpack unpack] plugin, but you do not want him to be able to enable "automatic unpack" via the settings window. You might add soemthing like this to /var/www/rutorrent/conf/users/tom/plugins.ini

{{{ [unpack] enabled = yes
canChangeToolbar = yes
canChangeMenu = yes
canChangeOptions = no
canChangeTabs = yes
canChangeColumns = yes }}}

=== per user plugin config files ===

In the new rutorrent 3.0 multi-user setup, it is possible to have different plugins config settings for each user. This is done by creating a plugins directory for each user, adding a directory for the plugin you wish to have the config for, and copying the base plugin conf.php to this directory. For example: If you have 3 users, tom dick and harry, and you want to have different rss update intervals for each user, you would do something like this: (note: the following assumes rutorrent installed at /var/www/rutorrent )

{{{ mkdir -p /var/www/rutorrent/conf/users/tom/plugins/rss mkdir -p /var/www/rutorrent/conf/users/dick/plugins/rss mkdir -p /var/www/rutorrent/conf/users/harry/plugins/rss cp /var/www/rutorrent/plugins/rss/conf.php /var/www/rutorrent/conf/users/tom/plugins/rss cp /var/www/rutorrent/plugins/rss/conf.php /var/www/rutorrent/conf/users/dick/plugins/rss cp /var/www/rutorrent/plugins/rss/conf.php /var/www/rutorrent/conf/users/harry/plugins/rss }}}

then edit accordingly. This works for all plugins which have a conf.php file.

=== a note on upgrading plugins ===

It's very important to remember, when upgrading a plugin, you should always:

Failure to stop/start rtorrent can result in plugins not behaving as you'd expect.

== Starting plugins with rtorrent ==

Plugins will load when the webui is opened. If you have plugins which need to poll for data (like rss or scheduler) you may wish to have them start when rtorrent starts, regardless of whether or not the webui has been loaded. In 2.0, this used to require a setting for each plugin via the .rtorrent.rc Now, all plugins can be brought up with a single .rtorrent.rc command. Be sure to edit this command for:

(the following is for user tom with rutorrent installed at /var/www/rutorrent)

{{{ execute = {sh,-c,/usr/bin/php /var/www/rutorrent/php/initplugins.php tom &} }}}

== Uninstallation ==

{{{ rm -r /var/www/rutorrent/plugins/rpc/ }}}

---

== Currently there are the following plug-ins: ==

== 3rd Party Plugins ==