Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
How to Install TvHeadend on FreeBSD, FreeNAS / NAS4Free / pfSense, with Finch / Qjail 3.5 -

NOTICE - TvHeadend Internal Grabbers don't work on FreeBSD yet. There is some work in progress updating the FreeBSD port to enable that.

TvHeadend How-To

How to install TvHeadend. Most of these commands can just be copy-pasted.

Install drivers for your TV Tuner device

  • In many cases, you MUST install the device-driver software webcamd. This is needed if your TV Tuner is a USB device, and most internal PCI Card "TV Tuner Card" etc. For the device you need to first make sure it is compatible to work on FreeBSD. Then install the correct firmware file into /boot/modules folder. All of these steps are explained in the WEBCAMD How-To. So please go there right now, if this step does apply to you.

  • However users of an network-based "ipTV" service, or owners of "ipTV" and "SAT>IP" compliant networked devices may skip this step. SAT>IP and ipTV products not accessed by webcamd. No special driver installation is required. Because ipTV products are directly accessible from within TvHeadend. No special driver installation is required. The support is built-into tvheadend server itself.

Create a new jail

# Enter the finch chroot environment, as root
sudo finch chroot

# Read the page "jail-ip-addresses" before choosing a jail IP address

# Set a matching ip address for the jail's 'lo0' ifconfig device (for localhost)

# Give an appropriate server name to your jail

# Create a basic jail, with local console access
qjail create -4 "$jail_ip,$jail_loopback" "$jailname"

# Enable unix sockets
qjail config -k "$jailname"

Configure the jail

# Set the ruleset number. Use the last 3 digits of $jail_ip

# Configure devfs rules to unhide disks
touch /etc/devfs.rules

grep "devfsrules_unhide_cuse=23" /etc/devfs.rules || cat >> /etc/devfs.rules <<- EOF

add path 'cuse*' unhide
add path 'video*' unhide
add path 'dvb*' unhide
add path 'dvb/*' unhide
add path 'dvb/adapter0/*' unhide
add path 'dvb/adapter1/*' unhide
add path 'input*' unhide
add path 'input/*' unhide


grep "devfsrules_jail_${jailname}=${rule_num}" /etc/devfs.rules || cat >> /etc/devfs.rules <<- EOF

add include \$devfsrules_jail
add include \$devfsrules_unhide_cuse


# Restart devfs to load the new ruleset
service devfs restart

# Stop the jail
qjail stop "$jailname"

# Configure the jail to use our new devfs ruleset
qjail config -b "$rule_num" "$jailname"

Login to the jail

# Start the jail
qjail start "$jailname"

# Login to our new jail as root
qjail console "$jailname"

Install avahi

This is needed only if you compile tvheadend from ports tree, with the AVAHI option enabled. The avahi service discovery daemon provides Bonjour / multicast DNS service discovery. And allows tvheadend to appear automatically on any local "Showtime Media Centre" clients in your LAN. Possibly xbmc clients too.

# Install avahi from pkgng
ASSUME_ALWAYS_YES="yes" pkg install avahi

# Configure avahi
sysrc "dbus_enable=YES"
sysrc "avahi_daemon_enable=YES"
sed -i "" -e 's/hosts: files dns/hosts: files dns mdns/' /etc/nsswitch.conf

# Start avahi service
service dbus start
service avahi-daemon start

Install TvHeadend

# Update local pkgng database, to avoid 'failed checksum' for 'pkg install'
pkg update -f

# Install tvheadend
ASSUME_ALWAYS_YES="yes" pkg install "tvheadend"

Configure an EPG Grabber for your region

# !! This section isn't ready yet, until TvHeadend is updated

# Install external EPG grabber programs tv_grab_*
pkg install p5-xmltv

# For UK region, the best EPG data is from atlas
# First go here to sign up and get the free API key

Configure TvHeadend

# Create a folder for log files
install -d -o webcamd -g webcamd /var/log/tvheadend

# Enable tvheadend rc.d service
sysrc "tvheadend_enable=YES"
sysrc "tvheadend_flags=-C"

# Start tvheadend
service tvheadend start

# Open tvheadend in a web browser, on TCP port 9981 of the jail's IP address
fetch -o - http://${jail_ip}:9981

You can configure your TV Tuner device, and add MUXES. Etc. All from TvHeadend's web interface.


# When you set the storage folders, don't forget to make them writable
# by the 'webcamd' user or group, which is UID 145 GID 145
webcamd:*:145:145:Webcamd user:/var/empty:/usr/sbin/nologin
  • You will need to configure a folder to store your recordings. Go to 'Configuration' --> 'Recording' and set the variable "Recording system path" to point to the root folder for all your recodings.
  • You may now wish to consult Mounting Filesystems. To create a separate dataset for your recordings folder, and so that it gets mounted correctly inside of the TvHeadend jail.
  • If you installed webcamd correctly, your TV Tuner devices should now appear in 'Configuration' --> 'DVB Inputs' --> 'TV Adaptors'.
  • For many DVB devices, the "auto-tuning" procedure does not work very well. Then you will need to delete all your mixes and try to add them back in manually.

Here are some useful pages, to help to get muxes working:

Copy link

rubenverhoef commented Sep 6, 2015

Thanks for your tutorial!

I have a problem, my tvheadend setup can't see my anysee tuner. I did the webcamd part without any problem. also the command: "install -d -o webcamd -g webcamd /var/log/tvheadend" returned install: unknown user webcamd.
I run the command inside the tvheadend jail.

i change the tvheadend user to root and it works, so there was some throbble that the tvheadend user cannot acces the tuner

Copy link

hurzl commented Sep 4, 2016

What are "Internal Grabbers"?
Why do I need finch, jail and avahi?

Copy link

papadave66 commented Dec 1, 2021

about update EPG. I googled a lot and choose to use Externel: XMLTV in Settings->EPG->EPG Grapping module.
If u can't see this option. try to use 'Expert' level in basic settings.

And I add following line in /etc/crontab

# Tvheadend EPG update
30      8       *       *       *       root       rm -f /tmp/e.xml && wget -q "http://EPG-WEBSITE/e.xml.xz" -O - | xz -d >> /tmp/e.xml && socat open:/tmp/e.xml UNIX-CONNECT:/usr/local/etc/tvheadend/epggrab/xmltv.sock

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment