README

=======================================================================
$Id$
vim: set comments=fb\:o,fb\:#,fb\:-,fb\:*,fb\:A.,fb\:Q. et tw=72 sw=4:
=======================================================================

/**********************************************************************
TorrentFlux-NG README file
**********************************************************************/

    Contents:
    =========
    1. Introduction
    2. Features
    3. Requirements
        3.1 Minimum Requirements
        3.2 Additional/Optional Feature Requirements
        3.3 Fluxd Requirements
    4. Installation
    5. Support


/**********************************************************************
1. Introduction
**********************************************************************/

    TorrentFlux-NG is based on TorrentFlux B4rt

    It includes the new RedRound theme and use jQuery

    TorrentFlux-NG is a web based transfer control client.
    it allows you to control your bittorrent transfers
    from anywhere using a highly configurable web based front end.

    TorrentFlux-NG is very easy to install on a web server and includes
    a simple setup script which can be accessed from a web browser.
    Just upload the files to your web server, run the setup script and
    your torrentflux-b4rt installation is ready to go.

    Torrentflux-b4rt was originally based on the TorrentFlux BitTorrent
    controller written by Qrome, although has recently undergone a major
    rewrite to allow transparent integration with a number of transfer
    clients and protocols:

    TorrentFlux-NG has builtin support for transfers via:

        o BitTorrent - supported client(s) include:

            * Original BitTorrent/Mainline - supports trackerless
              torrents and encryption

            * BitTornado - uses slightly less resources than the original
              BT, allows file priority for downloading files selectively

            * Transmission - much smaller memory footprint without much
              loss in functionality

            * Azureus - control a number of transfers from a single
              control process, tighter control on total max bandwidth
              for all torrents

        o HTTP/FTP - supported client(s) include:

            * wget - standard lightweight file transfer utility on
              Linux, supported on many other platforms also

        o Usenet - supported client(s) include:

            * nzbperl - perl based application allowing multi-connection
              news server downloads from nzb files with functionality
              for bandwidth throttling.


    TorrentFlux-NG incorporates a huge number of advanced options to
    allow you finer grained control of your transfers. The
    administration panel in torrentflux-b4rt includes a large number of
    options to allow you fine grained control over every aspect of your
    bittorrent/transfers usage.

    TorrentFlux-NG is also a multi-user application, allowing you to
    create individual accounts and assign restrictions to those accounts
    as you wish.


/**********************************************************************
2. Features
**********************************************************************/

    Please see the FEATURES file for a comprehensive list of
    Torrentflux-b4rt features.


/**********************************************************************
3. Requirements
**********************************************************************/

    Due to the extensible nature of torrentflux-b4rt, there are a
    variety of 3rd party tools/utilities and extra functionality that
    can be enabled from within the administration control panel.

    TorrentFlux-NG also features a service daemon called Fluxd which
    can be used to schedule rss feed downloads, keep watch over running
    torrents and restart them if they die.

    The 3rd party utils/functionality and Fluxd all have their own
    requirements.  For this reason the requirements section is split
    into the following sections:

        3.1 Minimum Requirements
        3.2 Additional/Optional Feature Requirements
        3.3 Fluxd Requirements

    ALWAYS install the required items from the package installation
    manager for your OS whenever possible.  This will save a lot of time
    and headaches, and ensure all the dependencies are installed
    correctly. See your OS documentation for details about the software
    management systems available on your OS.


/**********************************************************************
3.1 Minimum Requirements
**********************************************************************/

    This section lists the minimum requirements required to operate
    torrentflux with the basic core functionality.  This list may
    seem daunting, but most Unix like OSs have many of these features
    available as part of their software distribution system.

    /******************************************************************
    Notes:
    =====

    - The following lists are NOT exhaustive - if you use a Unix like
      OS/webserver/database/etc not listed below, basic functionality of
      torrentflux-b4rt may well work.  Success reports installing
      torrentflux-b4rt on other OSs other than those below above are
      welcome on the forum:

            http://tf-b4rt.berlios.de/forum/

    - IT IS STRONGLY ADVISED THAT YOU INSTALL THE COMPONENTS LISTED
      BELOW FROM THE SOFTWARE DISTRIBUTION SYSTEM INCLUDED WITH YOUR OS
      (ie apt-get, rpm package management, FreeBSD ports system, etc).
    ******************************************************************/


    The core minimum requirements follow below:

    o A Unix like OS (no Win32 support).
      Current tested OSs include:

        * Linux:
            o Debian, Ubuntu, Gentoo, RedHat, Fedora, NSLU2,
              ClarkConnect - amongst others

            Note:
            =====
            SELinux should be turned off.

        * BSD:
            o FreeBSD, OpenBSD, NetBSD

        * Apple:
            o Mac OS X


    o A Web Server.
      Current tested webservers include:

        * Apache
            http://www.apache.org/

        * LightTPD
            http://www.lighttpd.net/


    o An SQL-Database.
      Currently Supported databases:

        * MySQL
            http://www.mysql.com/

        * SQLite
            http://www.sqlite.org/

        * PostgreSQL
            http://www.postgresql.org/


    o PHP in 'web mode' (ie mod_php or php-cgi - preferably mod_php) >=
      4.3.x built with database (MySQL, SQLite or PostgreSQL), session,
      sockets and PCRE support enabled.  For image recognition/captcha
	  support for logins, GD support must be enabled in PHP.

    o PHP in 'commandline mode' (php-cli) >= 4.3.x built with database
      (MySQL, SQLite or PostgreSQL), session, sockets and PCRE support
      enabled.

        http://www.php.net/

        PHP Notes:
        ==========
        o Safe Mode must be turned off:
            * php.ini: safe_mode = Off

        o Allow Url fopen must be allowed:
            * php.ini: allow_url_fopen = On

        o open_basedir must be empty:
            * php.ini: open_basedir = ''

            Note: some web control panels like cPanel use
            open_basedir to restrict users as to what they can do with
            PHP.  torrentflux-b4rt does NOT officially support
            installations on shared hosting platforms due to the
            complications that arise (such as the use of open_basedir
            amongst many other things).  However if you do choose to
            attempt to install torrentflux-b4rt on a shared host running
            a control panel such as cPanel, be aware of the problems
            open_basedir can cause.

            Please see:

            http://php.net/manual/en/features.safe-mode.php#ini.open-basedir

            for more info.

        o As mentioned above, both the PHP web module and the
          commandline / cli binary must be installed, both with support
          for the database you plan to use and with support for PCRE and
          sessions.  Check the package management system
          documentation/website for your OS for more info on installing
          PHP with support for web and cli.


    o Python is required for the BitTorrent, BitTornado and Azureus
      bittorrent clients:

        * Python >= 2.2 for BitTornado
        * Python >= 2.4 for BitTorrent Mainline (original 'BitTorrent client)
        * Python >= 2.2.1 for Azureus


    o Perl >= 5.6 or higher for fluxd, nzbperl.pl, ttools.pl and
      fluxpoller.pl.  See section 3.2 below for extra info.


    Once more(!), it is highly advisable to install these requirements
    using the recommended package management system for your OS.


/**********************************************************************
3.2 Additional/Optional Feature Requirements
**********************************************************************/

    The following is a list of additional requirements needed before
    enabling additional features and options in torrentflux-b4rt.  By
    default these options or features are disabled and can be enabled
    via the administration panel - please ensure the requirements are
    installed before enabling additional features.

    As mentioned above, it is strongly advised that these requirements
    are installed from your OS's software distribution system to ensure
    all dependencies are installed correctly.


    Additional/optional feature requirements follow below:

    o BitTorrent Mainline Client requirements:

        * PyCrypto (Python Cryptography Toolkit)
            http://sourceforge.net/projects/pycrypto/

        * Twisted Python libs
            http://twistedmatrix.com/trac/

            Note:
            =====
            Twisted also requires Zope Interface >=3.0.1
                http://www.zope.org/Products/ZopeInterface/

            see Twisted installation docs for more info.


    o Azureus/Vuze Client requirements:

        * Azureus 2.5.0.0 or higher with the XML/HTTP Plugin
            http://azureus.sourceforge.net
            http://azureus.sourceforge.net/plugin_details.php?plugin=xml_http_if

        see azureus installation doc (doc/azureus.txt) for more info.

        A new interface with xmwebui rpc interface will come soon...


    o wget transfer functionality requirements:
        * wget
            http://www.gnu.org/software/wget/


    o nzbperl.pl requirements:

        * UUDeview
            http://fpx.de/fp/Software/UUDeview/

        The following perl modules are also required for nzbperl:

        * IO::File
        * IO::Select
        * IO::Socket::INET
        * File::Basename
        * Getopt::Long
        * Cwd
        * XML::Simple
        * XML::DOM

        Optional nzbperl perl modules:

        * Threads
        * Thread::Queue


    o Archive (rar/zip) extraction functionality requirements:

        * unrar
            http://www.rarlab.com/rar/


    o SFV file integrity checking functionality requirements:

        * cksfv
            http://zakalwe.fi/~shd/foss/cksfv/


    o vlc streaming functionality requirements:
        * vlc
            http://www.videolan.org/


    o ttools.pl is an alternative BitTorrent metadata client that
      supports metadata scraping.  It can be enabled in the
      Administration panel.  It requires the following modules:

        * Digest::SHA1     (perl -MCPAN -e "install Digest::SHA1")
        * LWP::UserAgent   (perl -MCPAN -e "install LWP::UserAgent")

    o Mac OS X specific:

        o Compilation of Transmission on Mac OS X requirements:
            * Apple Developer Tools
                http://developer.apple.com/tools/

        o wget functionality on Mac OS X requirements:
            * wget
                http://www.statusq.org/images/wget.zip


/**********************************************************************
3.3 Fluxd Requirements
**********************************************************************/

    The fluxd daemon works as part of torrentflux-b4rt to run in the
    background on your server performing various tasks that you
    schedule.  Fluxd is started from the Administration control panel -
    by default it is not running.

    Fluxd is written in the Perl scripting language and requires a
    number of perl modules to run.  In the following list, the perl
    command is given for you to install the corresponding module from
    CPAN.  HOWEVER, most of these modules should be available from your
    OS's package management system and it is strongly advised that you
    install the modules from there rather than directly using the perl
    CPAN system.

    The required perl modules are as follows:

    o Core fluxd functionality:

        * IO::Select       (perl -MCPAN -e "install IO::Select")
        * IO::Socket::UNIX (perl -MCPAN -e "install IO::Socket::UNIX")
        * IO::Socket::INET (perl -MCPAN -e "install IO::Socket::INET")
        * POSIX            (perl -MCPAN -e "install POSIX")

    IMPORTANT:
    ==========
    Additionally, Fluxd uses a PHP based helper script called
    fluxcli.php and for this to run correctly the commandline (cli)
    version of PHP must be installed with the correct extensions
    (database, PCRE, socket and session support).  See the notes above
    in section 3.1 for more information.


    o (Optional) Fluxd database connectivity using Perl DBI - Perl DBI
      db connectivity is not required to run Fluxd.  The option exists
      to enable perl DBI however in the Admin panel.  The following
      modules are required to run Fluxd in Perl DBI mode:

       * all database-types:
         DBI              (perl -MCPAN -e "install Bundle::DBI")

       * MySQL:
         DBD::mysql       (perl -MCPAN -e "install DBD::mysql")

       * SQLite:
         DBD::SQLite      (perl -MCPAN -e "install DBD::SQLite")

       * PostgreSQL:
         DBD::Pg          (perl -MCPAN -e "install DBD::Pg")


    o (Optional) Fluxinet functionality requirements - Fluxinet allows
      remote connections directly to the Fluxd daemon over TCP.  It
      is not enabled by default:

       * IO::Select       (perl -MCPAN -e "install IO::Select")

       * IO::Socket::INET (perl -MCPAN -e "install IO::Socket::INET")


/**********************************************************************
4. Installation
**********************************************************************/

    TorrentFlux-NG can be installed quickly from a web browser using
    the included setup script. For full details of how to install,
    please see the INSTALL file.

    It is also possible to Upgrade an existing installation of 2.1-b4rt
    or official TF (2.1 - 2.3) to TorrentFlux-NG. Details about
    upgrades can be found in the INSTALL file.


/**********************************************************************
5. Support
**********************************************************************/

    Please see the SUPPORT file for information on getting help with
    your Torrentflux-NG installation.