                         Goanseech

	  (      Global anime series leech, a 
	   Multi source Series Retrieval System )

LICENSE
=======
Released under GNU General Public License 2. See file COPYING.

Exception for the files ServerTcp*, ClientTcp*, Ssl* which are a future
part of POE, the author is Rocco Caputo <troc at netrus.net>, and
they are released under the Perl licence.
  
BEWARE ServerTcp*, ClientTcp*, Ssl* are NOT part of this distribution, they are
only there for your convenience until they are officially part of the POE
distribution!


WHATS ABOUT
===========

This whole thing is a spinoff of the leverlada IRC leech script
http://www.geocities.com/iwronsky/

one of its core parts was extracted and refunded into a stand-alone
server. Its starting point is patternServer.pl. You need to invoke that
one at some point and let it run. All the other parts revolve around
that server.

INSTALLATION
============

<rant>
Ok, i gave h2xs and MakeMaker a try, but i would need 5 years of full time
studies to begin to understand how this works, so if someone else want to set
up that system feel free to do it, as far as i can tell the makefile produced
by makemaker are totally useless, extremely ugly and completely out of purpose:
i only want to install some pl and pm scripts i don't see what all that C
compiling stuff has to do in the makefiles....

anyway all this to say that the use of those systems is counter intuitive, time
consuming, lacks proper documentation and i don't speak of the cryptic result that's
unreadable, in short, no way to get a working result by default.

</rant>

Fetch http://bboett.free.fr/goanseech-ssl.tbz (this is vital!!)

Unpack the archive somewhere, from the same place unpack Goanseech-ssl.tbz (it
has the same Goanseech root directory as the archive) and change into the project
directory.

To be able to call those files from anywhere out of the system a ~/.goanseech
directory is supposed. You might define other locations for those configuration files
by passing the  --config <alternatepath> to the script calls.

You need to copy the configuration files (*.sample) over to the configuration-directory, e.g.
~/.goanseech and edit them to your wishes, at least the settings.pm should be
adapted.

Alternatively call the makefile:
to install the libraries and executables:
make install   
to install the configuration files:
make install-config

since this is a quick and half-hearted hack don't push too much hopes on this
though.

SERIES SERVER
=============

This thing will read an actual list of definitions from a file
(leve.series) which consist of a pattern describing the textual part of
some series (.e.g. archetype.*?force, the .*? being a Perl regexp
    meaning any char of any quantity in between those 2 words), the
actually seeking episode number and the maximum episode number.

This server works with SSL, thus a valid certificate is needed. In case
you don't have one, don't want to buy one, you can install the open-SSL
software and generate one:
initializes the system:
 openssl genrsa>privkey.pem

create a private RSA key:
 openssl genrsa -out plain-rsa.pem 2048

create a certificate:
 openssl req -new -key privkey.pem -out cert.csr

sign ourselves that certificate:
 openssl req -new -x509 -key privkey.pem -out plain-cert.pem -days 1095

SHELL
=====

once the server is running you can launch a curses shell to connect to
it, patternQuery.pl is the script that does that. In the file settings.pm
are the common settings needed by most of the programs. Among others
the login needed to connect to the server. 

Actually a variety of commands might be send to the server, type help on the shell to get a list:

  load 
    load the configuration and pattern file
  save
    save the configuration and pattern file
  series
    list the requesting series, or add a new one
  delwish
    delete a pattern from the wish-list
  request
    create a string with the patterns with the highest priorities
  delseries
    delete a pattern from the series list
  addepisode
    an episode appeared from somewhere, register this fact
  delepisode
    an episode was wrongly registered as fetched, reschedule it
  modseries
   modify the settings of a series
  listwishes
    list the recorded wishes
  rawnames
    send a listing of all the patterns stripped of the rest of the information
    (needed e.g. for the shell completion)
  find
    check the presence of a given file, if it matches some pattern

GTK GUI
=======

Next utility, which will ease the update of the series, it fires up a
Perl-GTK interface which displays a listing of the patterns with their
boundaries, with spin boxes to increase decrease those boundaries.
actually its not possible to add intermediary episodes, nor to act on the
server.

GTK2 GUI
=======

This one needs http://bboett.free.fr/POE::Loop:Gtk2.pm and
http://bboett.free.fr/Gtk2-FormFactory.tgz to start-up. Otherwise it has nearly
the same functionality as the curses client.

DIRECTORY WATCHER
=================

This script watches a given number of directories for files and matches
them against the patterns, if a new episode appeared an update on the server
is made. This is a one shot script, thought to be launched by cron

actually the directories are stored inside of the script

sample crontab line to activate this: 1/15 * * * *    (cd ~/leverloda/goanseech; ./dirWatcher.pl )

if you want this script to run in daemon mode you have to set 'dirscan' to
something different than 0 in ~/.goanseech/settings.pm

TORRENTS EXTRACTOR
==================

This uses the URL's specified in ~/.goanseech/url.conf as index-pages and
explores all links found in those index-pages for exploitable torrent links.
The extracted URL's are compared to the data of the server, if some URL-link
descriptions match, those links  are checked,  if its already a torrent URL its
added to the URL's to fetch. Once the whole stack of pages to parse is worked
through the list of harvested torrent files are passed to the bit-torrent
controller which fires up a variable number of bit-torrent clients (controlled
    by torrentcmd and concurrentTorrents in ~/.goanseech/settings.pm) and
begins the retrieval.



NOTES
=====

Goanseech hasn't been verified by formal methods. It might
(and probably will) perform badly in situations not foreseen.

Goanseech can handle multiple connections the scripts are still in alpha
stage.

We encourage you to tweak. Please send us all the useful 
results. ;)


TROUBLESHOOTING
-------------------
Make sure you retrieved all the necessary libs and put them where Perl might
find them

Albeit the scripts were written in a pwd independent manner, its safest to run
them from within the distribution directory.

Is your computer connected to the electric socket?  

If you still can't start the script, make sure that you
have all the necessary Perl modules installed on your
system. (See lines "use <blah>;" in *.pl and *.pm). 


AUTHOR
======

B. Boettcher went through this in lots of sleepless nights, driven by the
never-ending frustration of having to work himself and not having a
subdued avid leech slave fetching for him Tera-bytes of anime.

You want to be here too?! Of course! Everyone wants. Just
send us some useful patch and your name will be immortalized
here forever.


CONTACT
=======

Ideas and bug reports, etc. are all appreciated. Even
better, if you can make the code function better on
one topic without making it function worse somewhere else,
that'd be superb.

Send mail to: <pimppa-leve(at)lists.sourceforge.net>
Its completely ok to post without subscribing.

<EOF>

