If Shepherd won't run because a "mandatory module" is not found, install it (see "Perl Dependencies") and try again. You may have to install several mandatory Perl modules before Shepherd can run.

Shepherd will now install itself and its components (probably into ~/.shepherd/). Most likely, one or more components will fail due to missing Perl modules, but that's fine: we'll fix that later.

Answer the configuration question to select your region.

When asked if you want Guided Channel Selection, say yes.

Shepherd will step through each of your MythTV channels, asking you to choose appropriate guide data for each one. Some MythTV channels you won't want guide data for (e.g. radio channels, guide channels, duplicate channels); that's fine.

If you are not a MythTV user, or Shepherd cannot access your MythTV, you will enter Advanced Channel Selection instead to manually enter XMLTV IDs for each channel.

When asked to confirm that you want to create Shepherd's configuration file, say yes.

Shepherd will test its components. It's fine for now if some fail.

Shepherd will ask if you would like to automatically configure MythTV. If you're a MythTV user, this is a good idea, because otherwise it's quite easy to get wrong. Say yes, and Shepherd will setup a tv_grab_au symlink, register itself as the default grabber for MythTV, and add itself as a cron job so that your system runs it regularly.

Shepherd will ask if you would like to install channel icons into MythTV. This is optional, and you can do it later if you prefer (with "tv_grab_au --set-icons"). If you say yes, Shepherd will step you through a variety of icon galleries to choose from.

Shepherd will exit. For maximum functionality, you should now install any missing Perl modules required by components. How to do this varies depending on your distribution: see the detailed instructions and why this is worth doing. Essentially, you should attempt to install any modules that Shepherd complains are missing when you do this:

~/.shepherd/shepherd --check

To avoid confusion, delete the original Shepherd file you downloaded (leaving the newly installed version in ~/.shepherd/).

Shepherd is now installed. This means that when run, it will create a file of TV guide data (by default: ~/.shepherd/output.xmltv). It also creates a log file at ~/.shepherd/log/shepherd.log. Most users want this guide data to be regularly fed to another program: see the relevant section below on integration with MythTV, Freevo, or EyeTV.

Which user?

It's no longer important to choose the "right" user to install Shepherd. (In previous versions, we asked MythTV users to ensure Shepherd's user matched that of MythTV. But this could be tricky to figure out, so we changed it.)

The simplest way to install Shepherd is as whichever user you usually use. If you're concerned about security, you could create a new user specifically for Shepherd, but be aware that Shepherd is user-specific: once installed for a particular user, it will only run for that user. (This prevents permissions problems.) Installing Shepherd as user "alice" then attempting to run it as user "bob" will begin a fresh install in Bob's directory, to avoid interfering with Alice's.

Integration with MythTV

Auto-configuration

Shepherd now has the ability to auto-configure MythTV for you, which eliminates a few common traps. You are asked whether you want to do this during initial configuration, as described above, but you can also (re-)do it with:

~/.shepherd/shepherd --configure-mythtv

This will register Shepherd as 'tv_grab_au' on your system (by creating a symbolic link, usually in /usr/bin/), register itself with MythTV as the default grabber, and set up a cron job so that your system regularly invokes Shepherd in order to regularly download up-to-date guide data.

Following configuration, MythTV should begin using Shepherd to obtain guide data within a few minutes. (In MythTV frontend -> Information Center -> System Status -> Listings Status, you should see "Mythfilldatabase is currently running.) It can take a while for Shepherd to complete its first run, even two or three hours.

Note: this routine requires ​sudo be available for the user. It is not required for any further shepherd running, so can be temporarily enabled if preferred. Information on configuring sudo can be found in the ​sudo manpage or ​here.

Manually feeding Shepherd data to MythTV

You might want to manually load Shepherd data into MythTV if you think Shepherd ran successfully but for some reason the data isn't showing up in MythTV--perhaps your channels weren't configured correctly or something. So after changing things, you can reload the data with:

tv_grab_au --reoutput-mythtv

Or if that doesn't work, try:

tv_grab_au --refill-mythtv

... which accomplishes the same thing, only using mythfilldatabase's --file option, rather than sending data directly.

You can also use these commands to modify Shepherd's output file (~/.shepherd/output.xmltv) and see the changes in MythTV, if you ever have the urge to tweak (or test) your guide data.

Running Shepherd on a remote system to MythTV

It is possible to run Shepherd on one system and feed the resulting guide data to your MythTV box. In this case, you should:

Install Shepherd on the remote system. You will be unable to use "Guided" channel selection, and need to make sure that the XMLTV IDs you assign to each channel match those you have specified in MythTV. When Shepherd asks if you want to auto-configure MythTV, say no.

Tell the augment_timezone component to add timezones to your guide data, which it won't do by default if it can't figure out which version of MythTV you have:

tv_grab_au --component-set augment_timezone:timeoffset=Auto

Periodically run Shepherd. You'll probably want to create a cron job for this, which can simply call "tv_grab_au". This will eventually produce the file ~/.shepherd/output.xmltv. You'll need to copy that to your MythTV box somehow.

Have MythTV read in output.xmltv via mythfilldatabase. The correct format for this command depends on your MythTV version, but currently it is:

Here mythfilldatabase is invoked twice, once for each source. The "--update" option prevents MythTV from creating channels on the wrong source.

Note for Ubuntu users: Be aware of ​this bug, which can cause silent failure of cron jobs on systems with no mail transport installed.

The old method

The alternative to a cron job is to have MythTV automatically run Shepherd, via Utilities/Setup? -> Setup -> General -> Mythfilldatabase -> "Automatically run mythfilldatabase" in mythfrontend.

This is no longer recommended. The main problem is that MythTV may not invoke Shepherd as the user you expect: it might be your own user, it might be mythtv, or it might be root, depending on your system. This can lead to Bad Things, such as root creating files that your regular Shepherd user cannot modify.

Integration with Freevo

Freevo will use the Shepherd data with a little alteration.
In local_conf.py set the XMLTV_GRABBER
XMLTV_GRABBER = '/home/tv/.shepherd/tv_grab_au --timeoffset=Auto'
(or /usr/bin/tv_grab_au if you have set the symlink)
If you have existing xmltv channel id set, use the ones you have already set when running

~/.shepherd/shepherd --configure

Otherwise use any channel id you choose.
Test your setup with

freevo tv_grab

Integration with EyeTV

Beginning with EyeTV version 3.0.1, EyeTV can use xmltv files as its source for channel and program guide data. However, it is quite picky about how those files must be presented, so it won't quite work "out-of-the-box" with Shepherd. To integrate Shepherd with EyeTV, you need to do the following:

install and configure Shepherd

install and launch EyeTV

in EyeTV's Preferences, select "None" as the TV guide service

download the XMLTV DTD and save it (using the file name "xmltv.dtd") in your .shepherd directory

Check whether any components are missing Perl modules or need to be configured:

tv_grab_au --check

Check your config:

tv_grab_au --show-config

Reload previously-generated data into MythTV

tv_grab_au --refill-mythtv

Perl Dependencies

Shepherd and its components rely on various third-party Perl modules. Some are mandatory, meaning that Shepherd won't run without them. Most, however, are optional, meaning that Shepherd can still operate without them, but some of its components (including grabbers) won't.

You should install all the optional modules if possible, as this increases Shepherd's efficiency, reliability, and possibly the quality of the guide data it delivers. For more information, see the FAQ.

LINHES 6.03

Its simple, Shepherd is in the repo already so its just a matter of issuing the following command and you should be good to go

pacman -S shepherd

Easy, hey!

Redhat Enterprise Linux 6

After the initial install of the system, you need certain perl dependencies to build xmltv:

cpan Term::ReadKey Date::Manip File::Slurp XML::Writer

Then build and install xmltv manually as described below.

Then install the remaining mandatory and optional perl dependencies as described in 'Non-Distribution Specific'.

Apple OS X 10.8

The biggest hassle is the version of XMLTV in CPAN - it's horribly out of date. My previous server is running 0.5.31, CPAN offers 0.5.33 which is from 2004 and doesn't actually compile due to an error in the makefile. Downloading the latest and compiling it manually works fine.

The process is:

CPAN required modules for XMLTV:

cpan Date::Manip XML::Twig

CPAN recommended modules for XMLTV (I don't know if this helped at all, but I did it while I was attempting to make cpan XMLTV::Ask work):

Note: XMLTV

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 Software: JavaScript

See the JavaScript section below. Currently JavaScript is not required.

Optional Software: Tor

Some grabbers work faster/better if they can operate using The Onion Router (tor) from ​http://tor.eff.org/. Once Tor is installed, shepherd will automatically find it and start using it. No configuration of Tor is necessary.

For Debian-based installations, a simple "sudo apt-get install tor" will get things working.

Security

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

Using Shepherd with multiple sources

It is possible to use a single installation of Shepherd to grab data for multiple sources (such as FTA & Foxtel in the following example).

You can do this by using the following steps:

Using mythtv-setup create two channel sources, one for FTA and another for Foxtel.

Select tv_grab_au as the grabber for both of these sources

Add cards and channels to the appropriate sources as required

Configure shepherd to grab data for both the FTA and Foxtel channels that you have configured in Myth

From a frontend, select setup -> general. On the last page you can schedule mythfilldatabase to be run automatically. This page also allows you to add parameters to the mythfilldatabase command line, to which you must add '--update'. This prevents Myth from adding the Foxtel channels to the FTA source, and vice-versa.

Whilst Mythfilldatabase will call Shepherd twice (once for each source), data will only be downloaded once for both FTA and Foxtel during the first run, as Shepherd will automatically use cached data when run twice in a short period of time.

Troubleshooting

JavaScript

* Currently, no Shepherd component requires JavaScript support. *

As such, we don't recommend you bother trying to install the Perl JavaScript module, because it's such an enormous pain in the butt. However, it is possible that it may be required again by some component in the future, and if this occurs, then Shepherd installations without JavaScript may start receiving data of poorer quality.

You can check whether any Shepherd component is missing a required module with:

tv_grab_au --check

For historical reasons, below are instructions for installing JavaScript on various platforms.

Ubuntu Lucid 10.04 and later

In Lucid, Ubuntu ​removed the Perl module JavaScript. To enable JavaScript in Ubuntu Lucid 10.04 and later, you must manually install two packages: libmozjs0d and libjavascript-perl.

Download the .deb file, run it, and click "Install Package." Exit when finished. (Ubuntu 11.10 and later: This step may fail due to a missing dependency on 'perlapi-5.10.1'. If so, open a command line, navigate to the directory where you downloaded the libjavascript file, and enter "sudo dpkg -i --force depends <filename>", where <filename> will be something like libjavascript-perl_1.14-1_amd64.deb. This will, however, leave your system unable to 'apt-get upgrade' without Ubuntu complaining about unmet dependencies. I don't know a good solution for this.)

(optional) To confirm you have JavaScript support, run tv_grab_au --update. The grabbers rex and news should install with no errors. You may also wish to tv_grab_au --check.

Suse 11.0

The reason Javascript won't build is because the libjs .h files are in the wrong directory. A simple way of addressing this build issue is to temporarily add a symlink:

cd /usr/include
ln -s js smjs
cpan JavaScript
rm smjs

Suse 10.1, 10.2 and 10.3

After installing libjs and libjs-devel you will still be missing some files to get 'cpan JavaScript' working please be careful with the following it is more of a hack than a fix.

‘cpan JavaScript’ will still have issues but should be about 86% successful, you can now do a force install by

pc:/ # cpan
cpan> force install JavaScript

If the compile complains about missing include files, but they exist on your system in a different directory tree, maybe link the trees:
[in my case, one of the directories in the "-I" include-file search path was a non-existant /usr/lib/MozillaFirefox, but they exist under /usr/lib/mozilla-firefox]

cd /usr/lib
ln -s mozilla-firefox MozillaFirefox

This will cause the files to be found under both the 'real' path, and the path that JavaScript thinks they should be, and a re-attempt to install JavaScript worked OK.

Fedora Core 6 (FC6)

An older version of the perl JavaScript module needs to be installed since the newer versions (after 1.04) do not install properly even with the force option. Just take the default answers to the three questions about SpiderMonkey
cd /tmp
wget ​http://ftp.mozilla.org/pub/mozilla.org/js/js-1.60.tar.gz
tar xvzf js-1.60.tar.gz
cd js/src
make -f Makefile.ref BUILD_OPT=1
cp jsopcode.tbl /usr/include

cpan -f C/CL/CLAESJAC/JavaScript-1.04.tar.gz

Mythdora 4 and 5

An older version of the perl JavaScript module needs to be installed since the newer versions (after 1.04) do not install properly even with the force option. Just take the default answers to the three questions about SpiderMonkey

RedHat Fedora

If you're running a RedHat Fedora system, you can verify whether you have the required JavaScript perl module bindings js and js-devel 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:

Gentoo

First emerge the supporting libraries:

emerge dev-perl/JavaScript-SpiderMonkey

then install the Javascript perl bindings from CPAN:

perl -MCPAN -e 'install JavaScript'

Mythdora 12.23

On Mythdora 12.23 (based on Fedora 12) you must be very careful to answer Yes to the "Is your SpiderMonkey compiled with JS_THREADSAFE" question, or JavaScript will not install properly.
All other questions can be anwered with the defaults.

sudo cpan JavaScript

Fedora 14

Same as Mythdora 12.23 you must be very careful to answer Yes to the "Is your SpiderMonkey compiled with JS_THREADSAFE" question, or JavaScript will not install properly. All other questions can be anwered with the defaults.