| 3 | | Shepherd should be installed as whichever user is going to run it. We recommend that this [wiki:Security not be root]. |
| 4 | | |
| 5 | | 1. '''[MythTV Users only]''' Set up your MythTV channels by running ''mythtv-setup'', going into the ''Channel Editor'', and using the ''Channel Scanner''. |
| 6 | | 1. '''[optional]''' Set a proxy if needed: |
| 7 | | {{{ |
| 8 | | export http_proxy=http://192.168.1.250:8888/ |
| 9 | | }}} |
| | 4 | It's not important which user you install and run Shepherd as, so long as you're consistent. We do, however, caution [wiki:Security against running Shepherd as root]. |
| | 5 | |
| | 6 | 1. '''[MythTV users only]''' We no longer recommend setting up MythTV to automatically run Shepherd due to the potentially confusing steps required. (In particular, it can be hard to know which user your system will run it as.) For simplicity, we instead describe how to set up Shepherd to supply MythTV with data via a cron job.[[BR]][[BR]]Configure MythTV first. In ''mythtv-setup'' -> ''3. Video Sources'' -> ''(your video source)'' -> ''Listings grabber'', select '''No grabber'''. Perform a channel scan: ''mythtv-setup'' -> ''5. Channel Editor'' -> ''Channel Scanner''.[[BR]][[BR]] |
| 18 | | 1. If Shepherd won't run because a "mandatory module" is not found, install it (see "[wiki:Installation#PerlDependencies Perl Dependencies]") and try again. You may have to install several mandatory Perl modules before Shepherd can run.[[BR]][[BR]]When Shepherd runs for the first time, it will attempt to download and install components (probably into ''~/.shepherd/''). Most likely, one or more components will fail to install due to missing Perl modules, but ignore this for now. |
| 19 | | 1. Answer the configuration questions to select your region. When asked if you want Guided Channel Selection, say "yes". Shepherd will then 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.[[BR]][[BR]]If you are not a MythTV user, or Shepherd cannot access your MythTV, you will need to use Advanced Channel Selection instead to manually enter [wiki:XMLTVIDs XMLTV IDs] for each channel. [[BR]][[BR]]When asked to confirm that you want to create Shepherd's configuration file, say '''yes'''. |
| 20 | | 1. '''[optional]''' Shepherd will now test all its components. If any require configuration (e.g. the oztivo grabber), you will be prompted to do this. You do not have to configure components, and you can do it later: just press enter to skip any questions asked of you. |
| 21 | | 1. '''[optional]''' Shepherd will ask if you want to grab data now. You probably don't, because you haven't installed the optional Perl modules, so say no. Shepherd will exit. |
| 22 | | 1. '''[optional]''' For maximum functionality, install any missing Perl modules required by components. See the [wiki:Installation#PerlDependencies detailed instructions] and [wiki:FAQ#HowimportantisittoinstalltheoptionalPerlmodules why this is worth doing]. Essentially, you want to install any missing Perl modules Shepherd complains about when you do this: |
| | 15 | 1. If Shepherd won't run because a "mandatory module" is not found, install it (see "[wiki:Installation#PerlDependencies Perl Dependencies]") and try again. You may have to install several mandatory Perl modules before Shepherd can run.[[BR]][[BR]]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.[[BR]][[BR]] |
| | 16 | 1. Answer the configuration questions to select your region. When asked if you want Guided Channel Selection, say "yes". Shepherd will then 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.[[BR]][[BR]]If you are not a MythTV user, or Shepherd cannot access your MythTV, you will need to use Advanced Channel Selection instead to manually enter [wiki:XMLTVIDs XMLTV IDs] for each channel. [[BR]][[BR]]When asked to confirm that you want to create Shepherd's configuration file, say '''yes'''.[[BR]][[BR]] |
| | 17 | 1. Shepherd will test its components (some of which may fail) and ask if you would like to install channel icons now. This is optional, and you can do it later if you prefer. If you say '''yes''', Shepherd will step you through a variety of icon galleries to choose from.[[BR]][[BR]] |
| | 18 | 1. Shepherd will ask if you want to grab data now. Say '''no'''. Shepherd will exit.[[BR]][[BR]] |
| | 19 | 1. For maximum functionality, install any missing Perl modules required by components. How to do this varies depending on your distribution: see the [wiki:Installation#PerlDependencies detailed instructions] and [wiki:FAQ#HowimportantisittoinstalltheoptionalPerlmodules why this is worth doing]. Essentially, you should attempt to install any modules that Shepherd complains are missing when you do this: |
| 35 | | 1. '''[optional]''' If you'd like Shepherd to provide you with some [wiki:channel_icons channel icons], set these up: |
| 36 | | {{{ |
| 37 | | ~/.shepherd/shepherd --set-icons |
| 38 | | }}} |
| 39 | | 1. '''[optional]''' Install [wiki:Installation#OptionalSoftware:Tor Tor] if you wish to increase the speed of some grabbers. (Note: currently no grabbers use Tor, so the benefit of this step is marginal.) |
| | 28 | 1. '''[optional]''' Install [wiki:Installation#OptionalSoftware:Tor Tor] if you wish to increase the potential speed of some grabbers. (Currently, no grabbers use Tor, so as of writing there is no benefit to this step.) |
| | 29 | |
| | 30 | Shepherd is now installed. This means that when run, it will create a file of TV guide data for you (by default: ''~/.shepherd/output.xmltv''). It also creates a log file at ''~/.shepherd/log/shepherd.log''. |
| | 31 | |
| | 32 | Most users want this guide data to be regularly fed to another program: to set this up, see the relevant section below on integration with [wiki:Installation#IntegrationwithMythTV MythTV], [wiki:Installation#IntegrationwithFreevo Freevo], or [wiki:Installation#IntegrationwithEyeTV EyeTV]. |
| 43 | | Shepherd's job is to create a file of TV guide data for the next 7 days: by default, ''~/.shepherd/output.xmltv''. (It also creates a log file at ''~/.shepherd/log/shepherd.log''.) Most users want this guide data to end up inside MythTV. This task is handled by MythTV's ''mythfilldatabase'' program. |
| 44 | | |
| 45 | | To periodically run Shepherd, you can: |
| 46 | | 1. In ''mythtv-setup'' -> ''Video Sources'', select "Australia" (''tv_grab_au''). Upon exiting this page, MythTV will run Shepherd in configuration mode. Control-C to exit. Run the MythTV frontend, and in ''Utilities/Setup'' -> ''Setup'' -> ''General'' -> ''Mythfilldatabase'', check "Automatically run mythfilldatabase". You might want to tweak the Start and End times (if convenient, please avoid 2AM and 8AM, as these tend to be peak times), but otherwise all default values should be fine. '''Note:''' This method will run Shepherd as whichever user ''mythfilldatabase'' runs as. If ''mythfilldatabase'' runs as root, and you cannot change that, then in order for Shepherd to find its config files, it must be installed as root, too (despite this being [wiki:Security a heightened security risk]).[[BR]][[BR]]or[[BR]][[BR]] |
| 47 | | 1. Create a cron job to run mythfilldatabase (and thus Shepherd) by yourself. e.g. Add a line such as this to /var/spool/cron/mythtv (for Fedora/Mythdora) and it will run mythfilldatabase once per day at 4AM as the mythtv user: |
| 48 | | {{{ |
| 49 | | 00 4 * * * /usr/bin/mythfilldatabase |
| 50 | | }}} |
| 51 | | OR to run at a random time (any where between 4AM and 8AM to spread the load)[[BR]][[BR]] |
| 52 | | {{{ |
| 53 | | 00 4 * * * sleep $(expr $RANDOM \% 14400) && /usr/bin/mythfilldatabase |
| 54 | | }}} |
| 55 | | |
| 56 | | You may also wish to ensure that your Shepherd and MythTV channels are correctly mapped to each other: |
| 57 | | {{{ |
| 58 | | ~/.shepherd/shepherd --show-channels |
| 59 | | }}} |
| 60 | | |
| 61 | | == Integration With Freevo == |
| | 36 | === Cron Job === |
| | 37 | As mentioned above, it's simpler to avoid MythTV's automated process for collecting guide data, and instead use a cron job. Enter: |
| | 38 | {{{ |
| | 39 | crontab -e |
| | 40 | }}} |
| | 41 | ... and add the following line: |
| | 42 | {{{ |
| | 43 | 44 * * * * ~/.shepherd/shepherd --daily --quiet && mythfilldatabase --file 1 ~/.shepherd/output.xmltv --quiet |
| | 44 | }}} |
| | 45 | The "''44 * * * *''" part means it'll run at the 44th minute of every hour. (If convenient, please pick a random number between 00 and 59, rather than 44, so not everybody runs at the same time.) The "''--daily''" option means Shepherd will only attempt to grab data if it's been about a day since it last did so successfully. The program ''mythfilldatabase'' is invoked to read Shepherd's output into MythTV, and the ''--quiet'' options prevent you from having output emailed to you. |
| | 46 | |
| | 47 | Once you've added that line and saved and exited, you should see: |
| | 48 | {{{ |
| | 49 | $ crontab -e |
| | 50 | crontab: installing new crontab |
| | 51 | }}} |
| | 52 | At 44 minutes past the hour (or at whatever time you chose), Shepherd will begin gathering guide data, then feed it to MythTV via mythfilldatabase. |
| | 53 | |
| | 54 | === Multiple sources === |
| | 55 | If you use multiple sources (e.g. free to air plus cable TV), your cron job should instead look like this: |
| | 56 | |
| | 57 | 44 * * * * ~/.shepherd/shepherd --daily --quiet && mythfilldatabase --update --file 1 ~/.shepherd/output.xmltv --quiet && mythfilldatabase --update --file 2 ~/.shepherd/output.xmltv --quiet |
| | 58 | |
| | 59 | The differences are the "''--update''" option, which prevents MythTV from creating channels on the wrong source, and that ''mythfilldatabase'' is invoked twice, once for each source. |
| | 60 | |
| | 61 | === The old method === |
| | 62 | |
| | 63 | The alternative to a cron job is to have MythTV automatically run Shepherd. This involves creating a symlink to Shepherd from ''/usr/bin/tv_grab_au'' and selecting "Australia (''tv_grab_au'') in ''mythtv-setup'' -> ''Video Sources''. You also have to run the MythTV frontend, and in ''Utilities/Setup'' -> ''Setup'' -> ''General'' -> ''Mythfilldatabase'', check "Automatically run mythfilldatabase". |
| | 64 | |
| | 65 | The main problem with this method 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 in turn can lead to Bad Things, such as root creating files that your regular Shepherd user cannot modify. |
| | 66 | |
| | 67 | == Integration with Freevo == |
