Installing and using MythTV: Configuring MythTV.

Next Previous Contents

## 9. Configuring MythTV.

By this point, all of the compile-time prerequisites have been installed, mysql is running and has had its initial database setup. It's now time to configure MythTV.

## 9.1 Configuring the Master backend system

Open a shell and decide where you will store your video files. This may be one directory or multiple directories on the same or different filesystems. There is no default directory used for new recordings, so you must create at least one storage directory and configure Myth to use it by running mythtv-setup. If you do not do this, then MythTV will be unable to record anything. The following example is specific for `/var/video`, but the same instructions would apply for any directory name you choose to use. See the Advanced Partition Formatting section for hints on creating a partition for MythTV.

> `

>     $ su
>     # mkdir /var/video
>     # chmod a+rwx /var/video
>     # exit

> `

NOTE: The last slash "/" is not required.

TIP: Try not to have your video mount point on the same partition as your root partition, which could lead to the filling up of your root partition with video data if the mount fails. For example:

If `/var/video` is created on your root partition and you then perform a mount of another drive to this directory there won't be any problems if everything is working the way it should. However, if the mount fails for some reason, `/var/video` still exists, so MythTV will find the directory and write files to it. If your `/` mount point is space limited, `/var/video` will also be space limited, and it won't take long to fill the partition. This will cause a number of side-effects, most of them bad. Instead, create subdirectories as the destination for the storage group.

Your directory structure could then look something like this:

> `

>     /mnt/video/drive1/video
>     /mnt/video/drive2/video

> `

Your `/etc/fstab` would look like this:

> `

>     /dev/hdb1 /mnt/video/drive1
>     /dev/hdc1 /mnt/video/drive2

> `

Because the Storage Group path is `/mnt/video/drive1/video`, if the mythbackend can only find `/mnt/video/drive1` it will not write files to that share, because the "video" directory doesn't exist.

After you create the desired directory or directories for storing your video files, you will need to add them to the proper Storage Group using mythtv-setup. This procedure is described below in the Storage Groups section.

The first thing to configure is the Master backend system. If you are running multiple backend systems, the Master backend will make all decisions about which programs will be recorded on which tuners. If you have only one backend, then it will be its own master.

The Master backend will always choose the first available tuner in the same order as you add cards through "mythtv-setup". In other words, the second card you add will only be used when there are two overlapping recordings, the third when there are three, and so on.

NOTE: It is possible to not have the cards on the Master backend be the first ones used. However, if you are new to MythTV it is easier to configure the Master backend first before moving on to the Slaves, at least until you become more familiar with the MythTV system. See Advanced Backend Configurations for information on configuring multiple backend systems in various ways.

Because MythTV uses a database to store all configuration variables, part of the bootstrap of MythTV is to indicate the location of the MySQL database server. If the frontend, backend and MySQL database server are all going to be running on the same box, you can continue to the next step. If not, you'll need to change the Host Name in the "Database Configuration" screen of the mythfrontend program.

Run the setup program:

> `

>     $ mythtv-setup

> `

The backend setup program will start and offer you a number of choices. It is strongly recommended that you go through them in order.

The first question will ask if you wish to clear out your existing configurations for your capture cards. Initially, you should say "YES" so that there are no surprises later.

The next question will ask you if you wish to clear out your video source information. You should answer "YES" to this as well.

Once the graphical setup starts, you'll see that there are six choices:

1. General
2. Capture Cards
3. Video Sources
4. Input connections
5. Channel Editor
6. Storage Directories

Use the arrow keys to move around, and press the space bar to select which option you wish to configure.

### General

The first screen of the General configuration deals with IP addresses of the system that you're running mythtv-setup on and any master backend you may have. If you've only got one machine, then the default values are fine and you can move to the next page by pressing the space bar. If you need to move around the screen, use the arrow keys to move focus between settings, not the mouse.

If you will be deploying multiple backends, or if your backend is on one system and you're running the frontend on another machine then do not use the "127.0.0.1" IP address.

NOTE: If you modify the 127.0.0.1 address and use a "real" IP address, you must use real IP addresses in both fields, otherwise your frontend machines will generate "Unexpected response to MYTH_PROTO_VERSION" errors.

Changing any of the port settings is very strongly discouraged. (If you do accidentally change them, the defaults are 6543 for the master/backend server, and 6544 for the HTTP requests)

Once you're satisfied with the values, move the focus down to Next and hit the space bar.

The next screen details the Host-specific Backend setup. This is where you will set the specific directory paths for this particular backend. Make sure that you've followed the steps at the beginning of this section and created a directory that exists and that MythTV will have write privileges to. When you're done, press Next to continue, taking you to the Global Backend Setup.

On the Global Backend Setup configure your backend with the appropriate settings. Use the left and right arrow keys to iterate through the choices available on each setting, and the up and down keys to move between settings. Move to Finish when you're done and press the space bar, taking you back to the main configuration screen.

### Capture Cards

You should have no capture cards defined, so the highlight will be on (New Capture Card). Press space to begin.

Choose the appropriate settings for your particular tuner. Use the arrow keys to move around and to make your choices, and press RETURN when complete. Pressing RETURN will take you back to the Capture Cards screen; if you have additional capture cards in this machine, press the space bar when the highlight is on the (New Capture Card) row to define another card.

If you have made a mistake, you can delete a card by highlighting it and pressing the 'D' key, or you can highlight it and press the RETURN or 'E' key to edit it.

Once you have no additional cards to setup, press ESC.

NOTE: If you have a dual digital/analog card, such as the pcHDTV cards and some DViCO cards, then you should not configure this as two separate cards. Configure the digital portion as a DVB card, then click on the "Analog Options" button within the DVB configuration panel for the card and configure the analog portion of the card there.

### Video Sources

When you start, the highlight should be on (New Video Source). Press the space bar to begin. The first field asks for the name of the video source. You may choose something easy to remember, like "Antenna" or "Cable". Once you've chosen a name, press the down arrow to move to the next field.

If you're in North America, change the grabber to "SchedulesDirect.org(Internal)", then continue pressing the down arrow to move to the next field. Fill in the username (lowercase only) and password that you have established with Schedules Direct, then move to the "Retrieve Listings" button and press the space bar.

NOTE: You need wget version 1.9.1 or higher to use Schedules Direct.

The mythtv-setup program will contact the Schedules Direct servers and get your account information. Once you're done, you may click the Finish button and skip the next few paragraphs in this document since they only apply to users that are using the external XMLTV script to get their guide data.

If you wish to continue using the XMLTV grabber, then move to the Zip/postal code field and put in the appropriate value.

If you're outside of North America, then some manual interaction will be required with XMLTV. You may need to switch from the MythTV setup program to the console it was run on to interact with XMLTV.

Once you have chosen your provider, press RETURN to continue. XMLTV will now begin collecting the initial data for your location. The screen may blank for a few seconds to several minutes, depending on the load of the listings provider and the speed of your connection to the Internet. Be patient!

You will then be returned to the Video Sources screen. If you have multiple video sources available, such as Antenna, Cable, etc, go ahead and define them all, even if they're not all going to be physically connected to the master backend server. Once you're done, press ESC to return to the main screen.

### Input Connections

The final configuration item is Input Connections. On this screen, you will associate the various video sources you defined earlier with a physical input to a encoder card. It's entirely possible that you have multiple tuners, and each tuner has a different input, so on this screen you let MythTV know which device will connect to which input source.

When you start this screen, you should see a listing of the various input connections available on each of the Capture cards you defined earlier. For example, you may have a capture card with a tuner, a SVideo and a Composite connection. If you wanted to associate the tuner (a.k.a., "Television") with an "Antenna" source you defined in Video Sources, you would move to the `/dev/videodevice (Television) ->` line and press the space bar. Using the left and right arrow keys will show you the various choices you have already created for video source. In our case, you would use the left/right cursor keys until "Antenna" was shown in the Video Source field. Press down to move to the next setting.

On the connection pane there is a "Scan for channels" button, if you are configuring a digital source such as a DVB card, you need scan for channels and you must do this before pressing the "Fetch channels from listings source" button. You may scan for analog channels on an analog input, but this is not needed.

The other button is called "Fetch channels from listings source". As long as you have a real listings source you should fetch channels from them for analog channels. You can do this for digital sources as well (unless the listing source is transmitted EIT data). If you are using XMLTV, you may need to switch from the MythTV setup program to the console it was run on to interact with XMLTV after pressing this button. It is possible to fetch the channels on the command line using mythfilldatabase. But if you need to do this, you will probably need to re-enter the MythTV setup program to configure the "Starting channel" setting for this source->input connection.

NOTE: If you have a Hauppauge PVR-500, you must think of it as two PVR-150's on a single PCI card. For example, if you have a single PVR-500 card, it will appear as `/dev/video0` and `/dev/video1`. Each `/dev/video` device will have a Tuner input.
Once you're done, press RETURN to go back to the Input Connections screen. You would then finish associating the video sources to any other hardware devices you have available.

NOTE: Don't add a video source to a hardware input if you don't actually have anything connected there. For example, adding "Cable" to the Tuner and to the Composite inputs without having something connected to Composite will lead to blank recordings.

Press ESC to return to the main menu, and press ESC again if you have no further items to configure, thereby returning you to the command line.

### Channel Editor

The channel editor is used to globally alter channel information, including items like hue, contrast, fine tuning and others. Users in North America shouldn't run the channel editor until you've completed the initial mythtv-setup and ran mythfilldatabase at least once to populate the database.

### Storage Groups

### Introduction.

Storage Groups are lists of directories that are used to hold MythTV recording files, giving you a flexible way to add capacity to your MythTV system without having to use exotic solutions such as LVM, filesystem expansion or RAID Online Capacity Expansion. You can also use Storage Groups to organize recordings and to put recordings of a certain type into one subdirectory.

Storage Groups do not offer redundancy in case of hard drive failure, but unlike LVM, if you lose a hard drive, you only lose the recordings that were on that drive. With LVM, if you lose a hard drive, you will most likely lose everything.

### How to use Storage Groups.

By default, there is only one Storage Group called "Default", and it is used for all recordings and Live TV.

NOTE: You need to add at least one directory to the Default Storage Group or else you will not be able to record anything with MythTV.

For example, if you have 5 hard drives in your system, your first hard drive could be your "boot" drive, and the remaining four could be dedicated to media storage. You could format the drives and mount them as `/mnt/store/d2`, `/mnt/store/d3`, `/mnt/store/d4` and `/mnt/store/d5`.

Within each mount point, it's strongly recommended that you use a sub-directory and make that the destination path for the Storage Group. See the Tip in the "Configuring the Master backend" section for additional information.

You would then add the four subdirectories you created under the mount points (`/mnt/store/d1/video`, etc) into the "Default" Storage Group.

At recording time, if there were four simultaneous recordings, MythTV would put one recording onto each drive.

MythTV will balance concurrent recordings across the available directories in a Storage Group in order to spread out the file I/O load. MythTV will prefer filesystems that are local to the backend over filesystems that are remote until the local filesystem has 2 concurrent recordings active or other equivalent I/O, then the next recording will go to the remote filesystem. The balancing method is based purely on I/O, Myth does not try to balance out disk space unless a filesystem is too low on free disk space in which case it will not be used except as a last resort.

Or, say that you originally installed MythTV to a 750GB hard drive, and that hard drive is now filling up. You could simply add a new drive to your system, mount it and update the Storage Group to add the additional space.

You may create additional Storage Groups to store specific recordings in their own directories. Storage Groups are edited via the 'Storage Directories' section of mythtv-setup.

You can also create multiple Storage Groups to group recordings together; recording schedules now have an option to specify which Storage Group to use.

Storage Groups are global, but can be overridden on a slave backend by creating a local Storage Group by running mythtv-setup on the slave. If a problem occurs and the slave backend is unable to use the desired Storage Group, it will fail back and try the directories defined in the master's Storage Group.

There's also a special 'LiveTV' Storage Group, but the directory list starts out empty. If you add a directory to the Storage Group, it will be used instead of putting LiveTV recordings in the Default Storage Group and will allow you to put your LiveTV recordings on their own filesystem.

Of course, you don't have to do anything, and Live TV recordings will just go into the Default Storage Group where they'll be the first programs eligible for expiration if the system needs free space for recordings.

Usage information for all Storage Group directories is visible on the mythfrontend status screen as well as the mythbackend status webpage. MythTV is smart enough to determine which directories are on shared filesystems so it should not count free or used space multiple times if you have more than one directory on the same filesystem.

### Migrating to Storage Groups.

Migrating to Storage groups is very simple: if you have existing recordings in a storage directory, then the system will automatically add that directory to the Default Storage Group. If you then add additional directories to a storage group, the system is flexible enough to check all Storage Groups for a file before deciding that it can't be found, which means that you can use the mv command from the Unix command line to arrange files however you'd like.

### Advanced: Algorithm used by the Storage Group

This section details the logic of the Storage Group allocation engine.

The current load-balancing preferences (in order) are:

- Local filesystems over remote
- Less-busy (less weight) over more-busy (more weight)
- More Free Space over Less Free Space

The 'business' of a filesystem is determined by weights. The following weights are added to a filesystem if it is in use for the following things:

- recording = +10
- playback = +5 (mythfrontend)
- comm flagging = +5 (mythcommflag)
- transcoding = +5 (mythtranscode)

If a recording is due to end within 3 minutes, it is not counted against the weight of a filesystem. This is done to account for the pre/post-roll and start-early/end-late settings.

## 9.2 Post-configuration

Run the `mythfilldatabase` program as directed. The master backend will obtain guide data for all the video sources you defined during setup.

NOTE: If you are using Schedules Direct and watching the output messages on the console or the log file it is normal to see a "401 Unauthorized" error followed by a "200 OK" when the connection to Schedules Direct is being established.

> `

>     From : Sun Jun 13 05:00:00 2004 To : Mon Jun 14 05:00:00 2004 (UTC)
>     --02:58:01--
>     http://datadirect.webservices.zap2it.com/tvlistings/xtvdService
>                => -'
>     Resolving datadirect.webservices.zap2it.com... 206.18.98.160
>     Connecting to datadirect.webservices.zap2it.com[206.18.98.160]:80...
>     connected.
>     HTTP request sent, awaiting response... 401 Unauthorized
>     Connecting to datadirect.webservices.zap2it.com[206.18.98.160]:80...
>     connected.
>     HTTP request sent, awaiting response... 200 OK
>     Length: unspecified [text/xml]

>         [    <=>                              ] 114,125       63.57K/s

>     02:58:03 (63.53 KB/s) - -' saved [114125]

>     Your subscription expires on 08/20/2004 12:00:00 AM
>     Grab complete.  Actual data from Sun Jun 13 05:00:00 2004 to Mon Jun 14
>     00:00:00 2004 (UTC)

> `

Once `mythfilldatabase` has finished, start the master server before continuing.

> `

>     $ mythbackend

> `

mythbackend will print information about connections and what it's doing to the console. If you'd like to see the options that are available for mythbackend, type `mythbackend -h` for help.

As of MythTV v0.22, the available options are:

> `

>     $ mythbackend --help
>     Valid options are:
>     -h or --help                   List valid command line parameters
>     -l or --logfile filename       Writes STDERR and STDOUT messages to filename
>     -p or --pidfile filename       Write PID of mythbackend to filename
>     -d or --daemon                 Runs mythbackend as a daemon
>     -v or --verbose debug-level    Use '-v help' for level info
>     --printexpire                  List of auto-expire programs
>     --printsched                   Upcoming scheduled programs
>     --testsched                    Test run scheduler (ignore existing schedule)
>     --resched                      Force the scheduler to update
>     --nosched                      Do not perform any scheduling
>     --nojobqueue                   Do not start the JobQueue
>     --noautoexpire                 Do not start the AutoExpire thread
>     --version                      Version information

> `

Running mythbackend as a daemon and using the logfile option will allow you to have mythbackend automatically start up during boot. You can follow the steps outlined in the section called Automatically starting mythbackend at system boot time for configuration steps.

If you enable the `-l` parameter, you will want to keep your logfiles rotated (so that they don't fill up a partition). See the section called Automatically rotating logs for more information.

## 9.3 Configuring a non-master backend

Ensure that you've granted access to the master MySQL database for remote backends as discussed in the section titled Modifying access to the MySQL database for multiple systems and that you have the correct IP address for the database server in the "Database Configuration" screen of the mythtv-setup application on this slave backend.

NOTE: Slave backends must not run a local MySQL daemon. By default, they will connect to their local daemon rather than the central database, causing unexpected behavior such as empty "Watch Recordings" lists and a failure to locate the Video Sources defined on the master backend. Modify the `/usr/local/share/mythtv/mysql.txt` file on all slave backends to ensure that the `DBHostName` has the address of the MySQL server. Caveat: You may make a slave backend the primary MySQL server, or run a non-MythTV database on a slave backend as long as you have edited the `mysql.txt` file on all systems and made it consistent. There can be only one authoritative MySQL database in a MythTV system - errors such as the one above ensue if backends and frontends have differing ideas of which MySQL database they should talk to.

Make sure that the IP addresses on the General setup screen are accurate. If the slave backend can't communicate with the master backend due to IP address misconfiguration then MythTV will not function properly.

Configuration of a non-master backend follows the same general procedure as that of the master backend, with the exception that you skip over the "Video Sources" step. All possible video sources need to be defined on the master backend system; only the master backend will query a listings provider to obtain guide data for all the non-master backends.

NOTE: Do not run `mythfilldatabase` on a non-master backend.

## 9.4 Configuring and running mythfilldatabase

NOTE: mythfilldatabase might take a while to complete, depending on any number of factors, most of which you can't control. It's best to just let the program run to completion.
mythfilldatabase --help will give a full listing of the options available.

mythfilldatabase --manual is another option; the manual option will allow you to fine tune channel frequencies and specify which channels will be added to the database.

mythfilldatabase --file is an option if there isn't an XMLTV grabber for your country, but you do have an XML formatted listings file created by some other program.

mythfilldatabase --xawchannels is an option if you have used xawtv to fine-tune your channels and would like to import the fine tuning offsets into MythTV.

mythfilldatabase --refresh-today will only pull guide data for today (in case of late-breaking changes to the schedule).

### Periodically running mythfilldatabase

In order to keep your database filled, mythfilldatabase should be run once a day.

To use MythTV's built-in capability, you'll need to run the mythfrontend Setup option. From the mythfrontend, enter the Setup>General screen and advance to "Mythfilldatabase", the fourth screen. Select the checkbox, then complete the options as you see fit. The mythbackend program will now run mythfilldatabase for you.

## 9.5 Grabbing channel icons for Schedules Direct users

While the Schedules Direct TV listings service has several advantages, it does not support grabbing logo icons for the stations you receive. However, there are utilities provided with MythTV which you may use to grab your initial set of icons and to keep them updated if your lineups change.

First, you need to generate or obtain an XML file with the information for your stations.

If you have XMLTV software installed, there is a perl script in MythTV's `contrib/` directory which will generate this file for you. Run the command:

> `

>     $ perl mkiconmap.pl

> `

You will be asked for your zip code and the service that you use. If there are no errors, the `iconmap.xml` file that you need for the next step will be created.

If you do not have XMLTV software installed and do not want to install it for the sake of this minor task, there is a generic `contrib/master_iconmap.xml` which you can copy and use but this may not be as complete as using the specific information for your service.

Once you have an `iconmap.xml` file, add the icon information to your database and grab any new icons with the command:

> `

>     $ mythfilldatabase --import-icon-map iconmap.xml --update-icon-map

> `

Next Previous Contents