hellanzb                                                                  README


          ;;;;            .  .
     ... :liil ...........:..:      ,._    ,._      ...................
     :   l$$$:  _.,._       _..,,._ "$$$b. "$$$b.   `_..,,._        :::
     :   $$$$.d$$$$$$L   .d$$$$$$$$L $$$$:  $$$$: .d$$$$$$$$$;      :::
     :  :$$$$P`  T$$$$: :$$$$`  7$$F:$$$$  :$$$$ :$$$$: `$$$$ __  _  |_
     :  l$$$F   :$$$$$  8$$$l"""""` l$$$l  l$$$l l$$$l   $$$L | ) /_ |_)
     :  $$$$:   l$$$$$L `4$$$bcmang;ACID$::$$$88:`4$$$bmm$$$$;.     ...
     :    ```      ```""              ```    ```    .    ```.     ..:::..
     :..............................................:   v 0 . 1 3  `:::`
                                                                     `

                 hands-free nzb downloader and post processor
--------------------------------------------------------------------------------

INSTALLING:
--------------------------------------------------
It is recommended that you install hellanzb via one of the packaging systems
(FreeBSD ports, Mac OS X darwinports). The latest port files and the python
source tarball are available from:

http://www.hellanzb.com/distfiles

To alternatively install hellanzb manually (from the source tarball):

Prerequisites:

Unix O/S               E.g.: http://www.freebsd.org, http://www.apple.com/macosx
Python >= 2.3          http://www.python.org

Twisted >= 2.0         http://www.twistedmatrix.com *and*
Twisted Web            http://www.twistedmatrix.com/projects/web
  OR
Twisted = 1.3          http://www.twistedmatrix.com

par2cmdline =~ 0.4     http://parchive.sourceforge.net
rar or unrar =~ 3.41   http://www.rarlab.com

Optionally (For MacBinary file conversion support):
macbinconv =~ 1.1.2    http://sourceforge.net/projects/macbinconv

hellanzb requires the command line utilities "par2", and "rar" (or "unrar") 
and optionally "macbinconv" to be in your shell environment's PATH.

hellanzb can either be ran from its own directory, or to install it system wide,
simply run (as root) in the hellanzb directory:

    "python setup.py install"


CONFIGURING
--------------------------------------------------
o Copy <prefix>/etc/hellanzb.conf.sample to hellanzb.conf in the same directory
  (This is automatically done for you by the ports)

  The prefix is typically:
    /usr/local (FreeBSD) or
    /opt/local (Darwin)
    or the hellanzb directory if ran locally within it
    
o Open hellanzb.conf and edit the directories (PREFIX, DEST_DIR, etc) to your
  liking. The important directories are the QUEUE directory (where you'll put
  nzb files to add to the queue) and the DEST dir (where the finished files are
  placed)

o Configure your Usenet connection with a defineServer line. There may be
  multiple defineServer lines

o Edit the defineMusicType lines to match the music decompressors installed
  on your system (any defined music decompression command line utilities must
  be available in your shell environment's PATH)

o [Optional] Edit the growler configuration to enable Mac OS X Growl
  notifications


USING
--------------------------------------------------
Run hellanzb.py

Move .nzb files into the QUEUE directory

Watch hellanzb (or go do something else) download and process your nzb
archives, leaving the finished files in the DEST dir

Also, see the 'Safe Usage' section at the bottom of this file


MISCELLANEOUS
--------------------------------------------------

o Make sure your terminal is at least 80 columns wide otherwise you may see
  download status lines scroll off the screen

o You can make hellanzb simply post process an already downloaded archive:

  "hellanzb.py -p ArchiveDirectoryName"

  In the case the archive contains password protected rars:

  "hellanzb.py -p ArchiveDirectoryName -P rarPassword"

  By default, the -p option will attempt to contact an already running hellanzb
  queue daemon via XML RPC. If the queue daemon is successfully contacted, it
  will handle the post processing work.

  If the queue daemon cannot be contacted, post processing will take place in
  the current process (and the process will exit upon completion)

  You can force -p mode to do the post processing work in the current process
  (and not attempt to contact the queue daemon) by also specifying the -L
  option:

  "hellanzb.py -Lp ArchiveDirectoryName -P rarPassword"
  
o Post processing happens automatically after archives are downloaded. In the
  case that an automatic post processor is interrupted by hellanzb exiting
  (such as from a CTRL-C), post processing will be resumed when hellanzb is
  restarted

o hellanzb logs its output to /var/tmp/hellanzb.log by default (this can be
  turned off in the configuration file)

o In the rare case that something unexpected happens, try reproducing it with
  Hellanzb.DEBUG_MODE (or hellanzb.py -d) enabled. This will produce a
  highly verbose DEBUG file that will contain any unexpected errors that were
  not picked up by the normal log file

o The Hellanzb.DEBUG_MODE log file may become rather large. It (and the normal
  log file) can be automatically trimmed and optionally rolled over via the
  Hellanzb.LOG_FILE_MAX_BYTES and Hellanzb.LOG_FILE_BACKUP_COUNT config
  variables


SAFE USAGE
--------------------------------------------------
Copyright laws and laws pertaining to patents and inventions protect original
works of authorship and inventions. Individuals who reproduce, distribute
copies, receive copies, publicly perform or display works or inventions other
than their own and without the consent of the owners or holders of rights, or
their authorized agents, in original works of authorship or inventions, may be
in violation of copyright, patent or other intellectual property infringement.
The hellanzb authors and contributors do not encourage or condone the illegal
copying of copyrighted material. This is not intended to be legal counsel or
advice. If you have any questions, consult your attorney.


hellanzb -
http://www.hellanzb.com/
KnowledgeTap Development Group