Version 18 (modified by max, 7 years ago)

--

Installation

To install Shepherd:

  1. Download Shepherd: 
    wget http://www.whuffy.com/shepherd/shepherd
  2. Run it: 
    perl shepherd
  3. If Shepherd complains about missing Perl modules, install these. See "Dependencies" below.
  4. Shepherd will attempt to download the latest versions of itself and its components into ~/.shepherd/ (or /opt/shepherd/). You may notice that one or more components may fail to install properly, due to missing Perl modules. For maximum functionality, you should attempt to install missing Perl modules later (see "Dependencies").
  5. Answer the configuration questions to select your region and desired channels
  6. When configuration is complete, symlink /usr/bin/tv_grab_au to Shepherd, so that mythfilldatabase can call it automatically: 
    sudo ln -s ~/.shepherd/shepherd /usr/bin/tv_grab_au
  7. You may now delete the original Shepherd file you downloaded (leaving the new installed version ~/.shepherd/shepherd).

Dependencies

Shepherd uses numerous 3rd-party modules and software. Some of these are mandatory, and some are optional, meaning that certain components (including grabbers) may not work without them, but the overall program will.

A list of Required and Optional modules is below.

The general way to install a Perl module is to do the following (as root): 

cpan <module>

For example: 

cpan List::Compare

It shouldn't cause any issues to run this; if everything is up-to-date, it'll tell you and finish. However, your Linux distribution may offer an alternative way to install module packages, and keep them up to date. If so, it's often better to use that. Here are some distribution-specific instructions:

Debian-Based Distributions

The following command should install the necessary packages: 

sudo apt-get install xmltv libxml-simple-perl libjavascript-perl libalgorithm-diff-perl \
                     libgetopt-mixed-perl libcompress-zlib-perl libdata-dumper-simple-perl \
                     libdate-manip-perl liblist-compare-perl libdatetime-format-strptime-perl \
                     libhtml-parser-perl libxml-dom-perl

Gentoo

Some (but not all) required modules can be installed with: 

sudo emerge -av xmltv Algorithm-Diff

Required Modules

Shepherd cannot run without the following Perl modules:

  • Algorithm::Diff
  • Compress::Zlib
  • Cwd
  • Data::Dumper
  • Date::Manip
  • Getopt::Long
  • List::Compare
  • LWP::UserAgent 
cpan Algorithm::Diff Compress::Zlib Cwd Data::Dumper Date::Manip Getopt::Long List::Compare LWP::UserAgent

Required Module: XMLTV

XMLTV needs to be installed. The latest version can be downloaded from http://files.xmltv.org/
If you are unsure about whether you have XMLTV installed, run the command perldoc XMLTV and see if there is any documentation on your system. If there is, then it is already installed.

XMLTV version 0.5.44 or later is recommended as it supports HDTV flags.

Optional Perl modules

Various grabbers and postprocessors require additional Perl/CPAN dependencies. These include:

  • !DateTime::Format::Strptime
  • File::Basename
  • File::Path
  • Javascript
  • HTML::Entities
  • HTML::TokeParser
  • HTML::TreeBuilder
  • IO::File
  • Storable
  • Time::HiRes
  • XML::DOM 
cpan DateTime::Format::Strptime File::Basename File::Path HTML::Entities HTML::TokeParser
cpan HTML::TreeBuilder IO::File Storable Time::HiRes XML::DOM

Optional Module: Javascript

Some grabbers parse web pages that have Javascript embedded in them. These grabbers make use of a system-wide Javascript library, typically provided by js and js-devel packages from your Unix/Linux installation. Before you can install the Javascript perl module bindings, you must first have the js modules installed on your system.

If you're running a RedHat? Fedora system, you can verify whether you have these through RPM: 

# rpm -q js js-devel
js-1.5-2.fc3
js-devel-1.5-2.fc3

Providing rpm responds with something similar to above, the javascript library files are installed and you can proceed with installing the perl javascript bindings. If rpm indicates the packages are not installed, you will need to install them from a RPM repository. [rpmfind.net] can be useful here:

Once you have installed the javascript library files, you can install the Javascript perl bindings from CPAN: 

cpan Javascript

Optional Software: Tor

Many grabbers work faster/better if they can operate using The Onion Router (tor) from http://tor.eff.org/.[[BR]] Tor is available in RPM form from as http://tor.eff.org/dist/rpm/tor-0.1.1.25-tor.0.rh4_4.i386.rpm and http://dag.wieers.com/packages/libevent/libevent-1.2-1.fc3.rf.i386.rpm

Once Tor is installed, shepherd will automatically find it and start using it. No configuration of Tor is necessary.

Security

Shepherd automatically checks for new versions of itself and its components, downloads, and executes them. See Security for details and implications.

Troubleshooting

auto-update fails
If you're manually upgrading from a previous version because we broke auto-update, it may be necessary to delete your ~/.shepherd/ directory.
mythfilldatabase keeps adding unwanted channels
If you are upgrading from the older channel 9 grabber, and you use mythfilldatabase to fetch the data, you may have to add the '--update' option to ensure mythfilldatabase does not try and add missing channels to your video sources. This can be a problem if you have video sources that receive different sets of channels.